@mearl/client 2.20.6 → 2.22.0

package/dist/{pluginAppProfiles.js → plugins/sdk/pluginAppProfiles.js}

@@ -1,7 +1,7 @@
 import { readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
-import { validateAppProfileContribution, } from './generated-app-profile-definition.js';
-import { pluginFileVersion } from './pluginSource.js';
+import { validateAppProfileContribution, } from '../../generated/app-profile-definition.js';
+import { pluginFileVersion } from '../pluginSource.js';
 /** Profile resources share the Skill root and metadata refresh rules of toolbox resources. */
 export function loadPluginAppProfiles(entry, value) {
     if (value === undefined)

package/dist/plugins/sdk/pluginModelDefinition.d.ts

@@ -0,0 +1,6 @@
+import type { PluginModelCapability, PluginModelRequest, PluginModelResult } from '../../generated/plugin-models.js';
+export declare function pluginModelCapabilities(): {
+    providers: PluginModelCapability[];
+};
+export declare function normalizePluginModel(value: unknown): PluginModelRequest;
+export declare function validatePluginModelResult(request: PluginModelRequest, value: unknown): PluginModelResult;

package/dist/plugins/sdk/pluginModelDefinition.js

@@ -0,0 +1,75 @@
+import { CODEX_MODEL_CAPABILITY } from '@mearl/agent-runtime/capabilities';
+import { compilePluginStateSchema } from './pluginStateDefinition.js';
+export function pluginModelCapabilities() {
+    return { providers: [CODEX_MODEL_CAPABILITY] };
+}
+export function normalizePluginModel(value) {
+    const request = value;
+    if (!request ||
+        typeof request !== 'object' ||
+        Array.isArray(request) ||
+        typeof request.prompt !== 'string' ||
+        !request.prompt.trim() ||
+        Buffer.byteLength(JSON.stringify(request)) > 256 * 1024 ||
+        (request.instructions !== undefined && typeof request.instructions !== 'string') ||
+        (request.conversation !== undefined &&
+            (typeof request.conversation !== 'string' ||
+                !/^[a-zA-Z0-9:_-]{1,80}$/.test(request.conversation))) ||
+        (request.model !== undefined &&
+            (typeof request.model !== 'string' || !request.model.trim() || request.model.length > 256)) ||
+        (request.reasoningEffort !== undefined &&
+            !['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'].includes(request.reasoningEffort)) ||
+        Object.keys(request).some(key => ![
+            'provider',
+            'mode',
+            'prompt',
+            'instructions',
+            'model',
+            'reasoningEffort',
+            'outputSchema',
+            'permissions',
+            'conversation',
+        ].includes(key)))
+        throw new Error('Invalid model execution request');
+    const capability = pluginModelCapabilities().providers.find(item => item.provider === request.provider);
+    if (!capability?.modes.includes(request.mode) ||
+        (request.mode === 'agent' && !capability.permissions.includes(request.permissions)) ||
+        (request.mode === 'generate' && request.permissions !== undefined))
+        throw Object.assign(new Error('Requested model mode or permissions are unsupported; choose an advertised capability explicitly'), { code: 'PLUGIN_MODEL_CAPABILITY_UNSUPPORTED' });
+    if (request.outputSchema !== undefined) {
+        if (!capability.structuredOutput ||
+            !request.outputSchema ||
+            typeof request.outputSchema !== 'object' ||
+            Array.isArray(request.outputSchema) ||
+            request.outputSchema.$async ||
+            Buffer.byteLength(JSON.stringify(request.outputSchema)) > 64 * 1024)
+            throw new Error('Invalid model output schema');
+        compilePluginStateSchema(request.outputSchema);
+    }
+    return JSON.parse(JSON.stringify(request));
+}
+export function validatePluginModelResult(request, value) {
+    const result = value;
+    if (!result ||
+        typeof result.text !== 'string' ||
+        result.provider !== request.provider ||
+        result.mode !== request.mode)
+        throw new Error('Invalid model execution result');
+    if (request.outputSchema) {
+        let output;
+        try {
+            output = JSON.parse(result.text);
+        }
+        catch {
+            throw Object.assign(new Error('Model returned invalid JSON'), {
+                code: 'PLUGIN_MODEL_SCHEMA_INVALID',
+            });
+        }
+        if (!compilePluginStateSchema(request.outputSchema)(output))
+            throw Object.assign(new Error('Model result does not match the output schema'), {
+                code: 'PLUGIN_MODEL_SCHEMA_INVALID',
+            });
+        return { ...result, output };
+    }
+    return result;
+}

package/dist/plugins/sdk/pluginPageDefinition.d.ts

@@ -0,0 +1,3 @@
+import type { PluginPageRuntime } from '../../generated/plugin-pages.js';
+export declare function normalizePluginPageRuntime(value: unknown): PluginPageRuntime | undefined;
+export declare function compilePluginPageSchema(schema: Record<string, unknown>): import("ajv/dist/core.js").AnyValidateFunction<unknown>;

package/dist/plugins/sdk/pluginPageDefinition.js

@@ -0,0 +1,62 @@
+import { parse } from 'acorn';
+import { Ajv } from 'ajv';
+import { isPluginPageMatchPattern } from '../../generated/plugin-pages.js';
+const validators = new WeakMap();
+export function normalizePluginPageRuntime(value) {
+    if (value === undefined)
+        return undefined;
+    const runtime = value;
+    if (!runtime ||
+        runtime.version !== 1 ||
+        !Array.isArray(runtime.matches) ||
+        !runtime.matches.length ||
+        runtime.matches.length > 64 ||
+        !runtime.matches.every(isPluginPageMatchPattern) ||
+        typeof runtime.code !== 'string' ||
+        Buffer.byteLength(runtime.code) > 384 * 1024 ||
+        Buffer.byteLength(JSON.stringify(runtime)) > 448 * 1024)
+        throw new Error('Invalid plugin pageRuntime declaration');
+    const program = parse(`(${runtime.code}\n)`, { ecmaVersion: 'latest' });
+    const statement = program.body[0];
+    if (program.body.length !== 1 ||
+        statement.type !== 'ExpressionStatement' ||
+        !['ArrowFunctionExpression', 'FunctionExpression'].includes(statement.expression?.type ?? ''))
+        throw new Error('pageRuntime.code must be a self-contained function expression');
+    if (runtime.events !== undefined &&
+        (!runtime.events ||
+            typeof runtime.events !== 'object' ||
+            Array.isArray(runtime.events) ||
+            Object.keys(runtime.events).length > 32))
+        throw new Error('Invalid page runtime events');
+    for (const [name, event] of Object.entries(runtime.events ?? {})) {
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(name) ||
+            !event ||
+            !/^[a-z][a-z0-9-]*$/.test(event.command) ||
+            !event.schema ||
+            typeof event.schema !== 'object' ||
+            Array.isArray(event.schema) ||
+            (event.policy !== undefined && !['serial', 'latest', 'parallel'].includes(event.policy)) ||
+            (event.concurrency !== undefined &&
+                (!Number.isSafeInteger(event.concurrency) ||
+                    event.concurrency < 1 ||
+                    event.concurrency > 8)) ||
+            (event.maxPending !== undefined &&
+                (!Number.isSafeInteger(event.maxPending) ||
+                    event.maxPending < 1 ||
+                    event.maxPending > 64)) ||
+            event.schema.$async)
+            throw new Error(`Invalid page event binding: ${name}`);
+        compilePluginPageSchema(event.schema);
+    }
+    if (runtime.initialize !== undefined && !/^[a-z][a-z0-9-]*$/.test(runtime.initialize))
+        throw new Error('Invalid page runtime initialize command');
+    return JSON.parse(JSON.stringify(runtime));
+}
+export function compilePluginPageSchema(schema) {
+    let validate = validators.get(schema);
+    if (!validate) {
+        validate = new Ajv({ strict: true, allErrors: false }).compile(schema);
+        validators.set(schema, validate);
+    }
+    return validate;
+}

package/dist/plugins/sdk/pluginRecoveryDefinition.d.ts

@@ -0,0 +1,3 @@
+import type { PluginTaskRecoveryDeclaration } from '../../generated/plugin-recovery.js';
+export declare function normalizePluginTaskRecovery(value: unknown): PluginTaskRecoveryDeclaration | undefined;
+export declare function pluginRecoverySignature(value: unknown): string;

package/dist/plugins/sdk/pluginRecoveryDefinition.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { compilePluginStateSchema } from './pluginStateDefinition.js';
+export function normalizePluginTaskRecovery(value) {
+    if (value === undefined)
+        return;
+    const declaration = JSON.parse(JSON.stringify(value));
+    if (!declaration ||
+        declaration.version !== 1 ||
+        !declaration.commands ||
+        typeof declaration.commands !== 'object' ||
+        Array.isArray(declaration.commands) ||
+        Object.keys(declaration.commands).length > 32 ||
+        Buffer.byteLength(JSON.stringify(declaration)) > 128 * 1024)
+        throw new Error('Invalid taskRecovery declaration');
+    for (const [command, definition] of Object.entries(declaration.commands)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(command) ||
+            !definition ||
+            !Number.isSafeInteger(definition.checkpointVersion) ||
+            definition.checkpointVersion < 1 ||
+            !definition.schema ||
+            typeof definition.schema !== 'object' ||
+            Array.isArray(definition.schema) ||
+            definition.schema.$async)
+            throw new Error('Invalid task checkpoint definition');
+        compilePluginStateSchema(definition.schema);
+        if (definition.migrateFrom !== undefined) {
+            if (!Array.isArray(definition.migrateFrom) ||
+                definition.migrateFrom.length < 1 ||
+                definition.migrateFrom.length > 16)
+                throw new Error('Invalid checkpoint migration sources');
+            const versions = new Set();
+            for (const source of definition.migrateFrom) {
+                if (!source ||
+                    !Number.isSafeInteger(source.version) ||
+                    source.version < 1 ||
+                    source.version >= definition.checkpointVersion ||
+                    versions.has(source.version) ||
+                    !source.schema ||
+                    typeof source.schema !== 'object' ||
+                    Array.isArray(source.schema) ||
+                    source.schema.$async)
+                    throw new Error('Checkpoint migrations require distinct older versions and schemas');
+                compilePluginStateSchema(source.schema);
+                versions.add(source.version);
+            }
+        }
+    }
+    return declaration;
+}
+export function pluginRecoverySignature(value) {
+    return createHash('sha256')
+        .update(JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : item))
+        .digest('hex');
+}

package/dist/plugins/sdk/pluginStateDefinition.d.ts

@@ -0,0 +1,4 @@
+import type { PluginStateDeclaration } from '../../generated/plugin-state.js';
+export declare function compilePluginStateSchema(schema: Record<string, unknown>): import("ajv/dist/core.js").AnyValidateFunction<unknown>;
+export declare function normalizePluginState(value: unknown): PluginStateDeclaration | undefined;
+export declare function pluginStateSignature(collection: import('../../generated/plugin-state.js').PluginStateCollection): string;

package/dist/plugins/sdk/pluginStateDefinition.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { Ajv } from 'ajv';
+const validators = new WeakMap();
+export function compilePluginStateSchema(schema) {
+    let validate = validators.get(schema);
+    if (!validate) {
+        validate = new Ajv({ strict: true }).compile(schema);
+        validators.set(schema, validate);
+    }
+    return validate;
+}
+export function normalizePluginState(value) {
+    if (value === undefined)
+        return;
+    const declaration = JSON.parse(JSON.stringify(value));
+    if (!declaration ||
+        declaration.version !== 1 ||
+        !declaration.collections ||
+        Array.isArray(declaration.collections) ||
+        Object.keys(declaration.collections).length > 32 ||
+        Buffer.byteLength(JSON.stringify(declaration)) > 128 * 1024)
+        throw new Error('Invalid stateStorage declaration');
+    for (const [name, collection] of Object.entries(declaration.collections)) {
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(name) ||
+            !collection ||
+            !['installation', 'host', 'browser-session', 'instance'].includes(collection.scope) ||
+            !['persistent', 'cache', 'memory'].includes(collection.storage) ||
+            !Number.isSafeInteger(collection.schemaVersion) ||
+            collection.schemaVersion < 1 ||
+            !collection.schema ||
+            typeof collection.schema !== 'object' ||
+            Array.isArray(collection.schema) ||
+            collection.schema.$async)
+            throw new Error(`Invalid state collection: ${name}`);
+        if (['browser-session', 'instance'].includes(collection.scope) &&
+            !['cache', 'memory'].includes(collection.storage))
+            throw new Error('Document state requires cache or memory storage');
+        if (collection.storage === 'memory' &&
+            !['browser-session', 'instance'].includes(collection.scope))
+            throw new Error('Memory state requires a browser session or instance scope');
+        if (collection.maxEntries !== undefined &&
+            (!Number.isSafeInteger(collection.maxEntries) ||
+                collection.maxEntries < 1 ||
+                collection.maxEntries > 4096))
+            throw new Error('State maxEntries must be between 1 and 4096');
+        if (collection.maxBytes !== undefined &&
+            (!Number.isSafeInteger(collection.maxBytes) ||
+                collection.maxBytes < 1 ||
+                collection.maxBytes > (collection.storage === 'memory' ? 128 : 16) * 1024 * 1024))
+            throw new Error('State maxBytes exceeds its storage limit');
+        if (collection.ttlMs !== undefined &&
+            (!Number.isSafeInteger(collection.ttlMs) ||
+                collection.ttlMs < 1 ||
+                collection.ttlMs > 7 * 86400000))
+            throw new Error('State TTL must be between 1 ms and 7 days');
+        if (collection.storage === 'persistent' && collection.ttlMs !== undefined)
+            throw new Error('Persistent state does not accept TTL');
+        compilePluginStateSchema(collection.schema);
+    }
+    return declaration;
+}
+export function pluginStateSignature(collection) {
+    return createHash('sha256')
+        .update(JSON.stringify(collection, (_key, value) => value && typeof value === 'object' && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : value))
+        .digest('hex');
+}

package/dist/runtimePaths.d.ts

@@ -0,0 +1,4 @@
+export declare const CLIENT_VERSION: string;
+export declare const PLUGIN_TASK_HOST_PATH: string;
+export declare const PLUGIN_WORKER_PATH: string;
+export declare const PLUGIN_MODEL_SESSION_WORKER_PATH: string;

package/dist/runtimePaths.js

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+// Package metadata and process entries share this anchor in compiled and bundled hosts.
+const require = createRequire(import.meta.url);
+export const CLIENT_VERSION = require('../package.json').version;
+export const PLUGIN_TASK_HOST_PATH = fileURLToPath(new URL('./plugin-task-host.js', import.meta.url));
+export const PLUGIN_WORKER_PATH = fileURLToPath(new URL('./plugin-worker.js', import.meta.url));
+export const PLUGIN_MODEL_SESSION_WORKER_PATH = fileURLToPath(new URL('./pluginModelSessionWorker.js', import.meta.url));

package/dist/socket.d.ts

@@ -7,7 +7,8 @@
  * 当 Socket 不存在，或 legacy Socket 是无人监听的残留文件时，
  * 自动尝试拉起 native host，稍后重试连接。
  */
-export declare const CLIENT_VERSION: string;
+import { CLIENT_VERSION } from './runtimePaths.js';
+export { CLIENT_VERSION };
 /**
  * Legacy well-known socket. New native-hosts publish per-browser sockets in the
  * registry and we address those; this path is a fallback for pre-registry hosts
@@ -46,4 +47,3 @@ export declare function resolveLocalActionTarget(action: string, data: Record<st
  * legacy well-known socket，并在 socket 不存在或已残留时自动拉起 native host。
  */
 export declare function invoke(action: string, data?: Record<string, any>, options?: InvokeOptions): Promise<any>;
-export {};

package/dist/socket.js

@@ -11,16 +11,16 @@ import net from 'node:net';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { createRequire } from 'node:module';
+import { CLIENT_VERSION } from './runtimePaths.js';
 import { StringDecoder } from 'node:string_decoder';
 import { ensureProviderControlHost, listInstalledProviders } from '@mearl/provider/host';
+import { MEARL_PROVIDER_PROTOCOL_VERSION } from '@mearl/provider';
 import { readLiveProvider } from '@mearl/provider/runtime';
 import { resolveFileRefs } from './fileRefs.js';
 import { listLiveBrowsers, findBrowser, describeBrowser, } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
-import { isBrowserCapabilityAction } from './generated-browser-action-protocol.js';
-const require = createRequire(import.meta.url);
-export const CLIENT_VERSION = require('../package.json').version;
+import { isBrowserCapabilityAction } from './generated/browser-action-protocol.js';
+export { CLIENT_VERSION };
 const MAX_SOCKET_BUFFER_SIZE = 64 * 1024 * 1024;
 /**
  * Legacy well-known socket. New native-hosts publish per-browser sockets in the
@@ -581,6 +581,7 @@ async function invokeOnce(action, data, timeoutSec, transport, socketPath, contr
         socketPath = host.socketPath;
     }
     const id = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    const deadline = Date.now() + Math.ceil(timeoutSec * 1000);
     return new Promise((resolve, reject) => {
         if (process.platform !== 'win32' && fs.existsSync(socketPath) && process.getuid) {
             const ownerUid = fs.statSync(socketPath).uid;
@@ -616,14 +617,17 @@ async function invokeOnce(action, data, timeoutSec, transport, socketPath, contr
                 action,
                 data,
                 version: CLIENT_VERSION,
+                protocolVersion: MEARL_PROVIDER_PROTOCOL_VERSION,
                 controlSource: toControlSourceWireValue(controlSource),
             };
             if (data[SESSION_OPTION])
                 message.controlSessionId = data[SESSION_OPTION];
             if (transport)
                 message.transport = transport;
-            if (providerTarget)
+            if (providerTarget) {
                 message.providerTarget = providerTarget;
+                message.deadline = deadline;
+            }
             socket.write(JSON.stringify(message) + '\n');
         });
         socket.on('data', chunk => {
@@ -681,7 +685,7 @@ function formatConnectError(error, socketPath) {
             '3. 确认 Chrome 浏览器正在运行，如仍无法连接可在 chrome://extensions 重新加载插件',
             '',
             '【方式二：CDP 远程调试模式（Chrome 145+，无需插件）】',
-            '  访问 chrome://inspect/#remote-debugging，勾选 "Discover network targets"',
+            '  访问 chrome://inspect/#remote-debugging，勾选 "Allow remote debugging for this browser instance"',
             '  Chrome 会弹出授权提示，点击允许，native host 自动读取 DevToolsActivePort 文件连接',
             '  确认有普通网页已打开（非 chrome:// 页面）',
         ].join('\n');

package/dist/unified.d.ts

@@ -1,6 +1,6 @@
-import type { BrowserArtifact } from './generated-browser-action-protocol.js';
+import type { BrowserArtifact } from './generated/browser-action-protocol.js';
 import { type CloudConnectorListResult } from '@mearl/cloud-types';
-import type { PluginInvocation, PluginInvokeOptions } from './plugin.js';
+import type { PluginInvocation, PluginInvokeOptions } from './plugins/sdk/plugin.js';
 export interface UnifiedInvokeOptions {
     /** Use new on the first tab_open/page_snapshot, then reuse the returned id. */
     session?: string;
@@ -51,6 +51,7 @@ export declare class UnifiedClient {
         outputPath: string;
         bytes: number;
     }>;
+    pinBrowserTarget(options?: UnifiedInvokeOptions): Promise<UnifiedInvokeOptions>;
     private pinPageEvalTarget;
     private invokeRouted;
     private invokeExplicitLocal;

package/dist/unified.js

@@ -3,7 +3,7 @@ import { stageFile, exportArtifact } from './artifacts.js';
 import WebSocket from 'ws';
 import { DEFAULT_CONNECT_TIMEOUT, DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_REQUEST_TIMEOUT, MAX_BUFFER_SIZE, isHeartbeatMessage, resolveCloudConnectorSelector, } from '@mearl/cloud-types';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
-import { validateRequiredActionTabId, } from './generated-browser-action-protocol.js';
+import { validateRequiredActionTabId, } from './generated/browser-action-protocol.js';
 import { invoke as invokeLocalBrowser, resolveLocalActionTarget } from './socket.js';
 import { loadCloudServerConfig, loadLocalConnectorId } from './unifiedConfig.js';
 const RESPONSE_GRACE_MS = 1_000;
@@ -124,12 +124,72 @@ export class UnifiedClient {
         this.ws = null;
     }
     async invokePlugin(name, invocation, options = {}) {
-        const { invokeRegisteredPlugin } = await import('./plugin.js');
+        const { invokeRegisteredPlugin } = await import('./plugins/sdk/plugin.js');
         return invokeRegisteredPlugin(name, invocation, {
             invoke: (action, payload, invokeOptions) => this.invoke(action, payload, invokeOptions),
+            runModel: async (plugin, request, execution) => {
+                const { PluginModelClient } = await import('./plugins/clients/pluginModels.js');
+                const models = new PluginModelClient({ source: options.source ?? 'sdk' });
+                try {
+                    return await models.run(plugin, request, {
+                        signal: execution.signal,
+                        onProgress: progress => {
+                            if (progress !== undefined)
+                                execution.onProgress?.(progress);
+                        },
+                    });
+                }
+                finally {
+                    models.disconnect();
+                }
+            },
         }, options);
     }
     async invoke(action, data = {}, options = {}) {
+        if (action === 'plugin_state') {
+            const { PluginStateClient } = await import('./plugins/clients/pluginState.js');
+            const state = new PluginStateClient();
+            try {
+                return await state.call(String(data.plugin ?? ''), data.collection, data.operation, data, options);
+            }
+            finally {
+                state.disconnect();
+            }
+        }
+        if (action === 'plugin_model') {
+            const { PluginModelClient } = await import('./plugins/clients/pluginModels.js');
+            const models = new PluginModelClient();
+            try {
+                if (data.operation === 'capabilities')
+                    return await models.capabilities();
+                if (data.operation === 'list')
+                    return await models.list(data.provider);
+                if (data.operation === 'start')
+                    return await models.start(String(data.plugin ?? ''), data.request, data.taskOptions ?? {});
+                if (data.operation === 'run')
+                    return await models.run(String(data.plugin ?? ''), data.request, data.taskOptions ?? {});
+                throw new Error('Invalid model operation');
+            }
+            finally {
+                models.disconnect();
+            }
+        }
+        if (action === 'plugin_page') {
+            const { PluginHostConnection } = await import('./plugins/clients/pluginHostConnection.js');
+            const { PluginPageClient } = await import('./plugins/clients/pluginPages.js');
+            const connection = new PluginHostConnection();
+            const pages = new PluginPageClient({}, connection);
+            try {
+                const pinned = ['attach', 'activation'].includes(data.operation)
+                    ? await this.pinBrowserTarget(options)
+                    : options;
+                return await pages.call(String(data.plugin ?? ''), data.operation, data, pinned);
+            }
+            finally {
+                pages.disconnect();
+                connection.disconnect();
+            }
+        }
         if (options.session && options.session !== 'new') {
             const session = await this.resolveControlSession(options.session, options);
             const selected = decodeBrowserTarget(options.browser);
@@ -209,6 +269,27 @@ export class UnifiedClient {
     saveArtifact(artifact, outputPath, options = {}) {
         return exportArtifact(this, artifact, outputPath, options);
     }
+    async pinBrowserTarget(options = {}) {
+        const selector = options.browser ?? this.defaultBrowser;
+        if (decodeBrowserTarget(selector))
+            return { ...options, browser: selector };
+        const listing = (await this.invoke('browser_list', {}, {
+            ...options,
+            ...(options.connector || !this.defaultConnector
+                ? {}
+                : { connector: this.defaultConnector }),
+        }));
+        const connected = listing.browsers.filter(browser => browser.status === 'connected');
+        const matches = selector
+            ? findBrowsers(connected, selector)
+            : connected.filter(browser => browser.browserId === listing.defaultBrowserId);
+        const target = matches.length ? matches : selector ? [] : connected;
+        if (target.length !== 1)
+            throw new Error('Plugin pages require an explicit, connected and unambiguous browser target');
+        const pinned = { ...options, browser: target[0].browserId };
+        delete pinned.connector;
+        return pinned;
+    }
     async pinPageEvalTarget(options, data) {
         const target = decodeBrowserTarget(options.browser);
         if (target && !options.connector)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.20.6",
+  "version": "2.22.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -60,11 +60,15 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "acorn": "^8.16.0",
+    "ajv": "^8.18.0",
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.20.6",
-    "@mearl/provider": "2.20.6"
+    "@mearl/daemon-core": "2.22.0",
+    "@mearl/cloud-types": "2.22.0",
+    "@mearl/provider": "2.22.0",
+    "@mearl/agent-runtime": "2.22.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",

package/dist/pythonPlugin.d.ts

@@ -1,20 +0,0 @@
-import type { PluginOptions } from './plugin.js';
-export interface PythonPluginCommand {
-    description: string;
-    signature: string;
-    toolboxOnly: boolean;
-}
-export interface PythonPluginDescriptor {
-    commands: PythonPluginCommand[];
-    description?: string;
-    name?: string;
-    toolbox?: unknown;
-    appProfiles?: unknown;
-}
-export interface PythonPluginApp {
-    readonly options: Readonly<PluginOptions>;
-    invoke(action: string, payload?: Record<string, any>, options?: PluginOptions): Promise<any>;
-    progress(message: string): void;
-}
-export declare function describePythonPlugin(entry: string, options: Readonly<PluginOptions>): Promise<PythonPluginDescriptor>;
-export declare function runPythonPluginCommand(entry: string, command: string, input: Record<string, any>, app: PythonPluginApp): Promise<unknown>;