@mearl/client 2.20.1 → 2.20.3

package/dist/pluginPageBundle.js

@@ -29,6 +29,8 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   let port = null;
   let requestSequence = 0;
   const pending = new Map();
+  const pageEventListeners = new Map();
+  let subscriptionSequence = 0;
   let resolveReady;
   const ready = new Promise(resolve => { resolveReady = resolve; });
 
@@ -76,54 +78,25 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   };
 
   const invoke = async (command, input = {}) => {
-    if (typeof command !== 'string' || !/^[a-z][a-z0-9-]*$/.test(command)) {
-      throw new Error('Invalid plugin command');
-    }
+    if (typeof command !== 'string' || (!/^[a-z][a-z0-9-]*$/.test(command) && !/^host\.[a-z][a-zA-Z]*(?:\.[a-z][a-zA-Z]*)*$/.test(command))) throw new Error('Invalid command');
     if (!input || typeof input !== 'object' || Array.isArray(input)) {
       throw new Error('Plugin command input must be an object');
     }
     return requestHost('invoke', { command, input });
   };
 
-  const start = async (command, input = {}) => {
-    if (typeof command !== 'string' || !/^[a-z][a-z0-9-]*$/.test(command)) {
-      throw new Error('Invalid plugin command');
-    }
-    if (!input || typeof input !== 'object' || Array.isArray(input)) {
-      throw new Error('Plugin command input must be an object');
-    }
-    return requestHost('invoke-start', { command, input });
-  };
-
-  const operation = async operationId => {
-    if (typeof operationId !== 'string' || !/^[0-9a-f-]{36}$/i.test(operationId)) {
-      throw new Error('Invalid plugin operation id');
-    }
-    return requestHost('invoke-operation', { operationId });
-  };
-
-  const runningOperations = async () => requestHost('invoke-operations');
-
-  const selectDirectory = async () => {
-    const path = await requestHost('select-directory');
-    if (path !== null && typeof path !== 'string') {
-      throw new Error('Directory selection returned an invalid path');
-    }
-    return path;
-  };
-
-  const copyText = async text => {
-    if (typeof text !== 'string' || text.length > 1000000) {
-      throw new Error('Clipboard text must be a string no longer than 1000000 characters');
-    }
-    await requestHost('clipboard-write', { text });
-  };
-
-  const openExternalLink = async url => {
-    if (typeof url !== 'string' || !url || url.length > 8192) {
-      throw new Error('External link must be a non-empty URL no longer than 8192 characters');
-    }
-    await requestHost('open-external-link', { url });
+  const subscribe = async (source, target, listener) => {
+    if (source !== 'page' || !target || !Number.isSafeInteger(target.tabId) || target.tabId < 0 ||
+        typeof target.runtimeId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(target.runtimeId) ||
+        typeof listener !== 'function') throw new Error('Invalid event subscription');
+    const subscriptionId = String(++subscriptionSequence);
+    pageEventListeners.set(subscriptionId, listener);
+    try { await requestHost('subscribe', { source, target, subscriptionId }); }
+    catch (error) { pageEventListeners.delete(subscriptionId); throw error; }
+    return () => {
+      if (!pageEventListeners.delete(subscriptionId)) return;
+      void requestHost('unsubscribe', { subscriptionId }).catch(() => {});
+    };
   };
 
   const handleExternalLinkClick = event => {
@@ -140,28 +113,11 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     }
     if (url.protocol !== 'http:' && url.protocol !== 'https:') return;
     event.preventDefault();
-    void openExternalLink(url.href).catch(error => {
+    void invoke('host.link.open', { url: url.href }).catch(error => {
       console.error('Failed to open external link', error);
     });
   };
 
-  const toast = async (message, options = {}) => {
-    if (typeof message !== 'string' || !message.trim() || message.length > 4000) {
-      throw new Error('Toast message must be a non-empty string no longer than 4000 characters');
-    }
-    if (!options || typeof options !== 'object' || Array.isArray(options)) {
-      throw new Error('Toast options must be an object');
-    }
-    const type = options.type ?? 'info';
-    const duration = options.duration ?? 3000;
-    if (!['success', 'error', 'info'].includes(type)) throw new Error('Invalid toast type');
-    if (!Number.isInteger(duration) || duration < 1000 || duration > 30000) {
-      throw new Error('Toast duration must be between 1000 and 30000 milliseconds');
-    }
-    await ready;
-    port.postMessage({ type: 'toast', message: message.trim(), toastType: type, duration });
-  };
-
   const agentPanelLayout = options => {
     if (!options || typeof options !== 'object' || Array.isArray(options)) {
       throw new Error('Agent panel options must be an object');
@@ -441,7 +397,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     return query;
   };
 
-  const api = { copyText, invoke, operation, ready: () => ready, runAgentTask, runningOperations, selectDirectory, setAgentGuides, setAgentPanelVisible, setQueryParam, start, toast };
+  const api = { invoke, subscribe, ready: () => ready, runAgentTask, setAgentGuides, setAgentPanelVisible, setQueryParam };
   const ui = globalThis.__mearlToolboxUi;
   if (ui !== undefined) {
     if (!ui || typeof ui !== 'object' || ui.runtime !== 'preact') {
@@ -481,6 +437,10 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     port = nextPort;
     port.onmessage = responseEvent => {
       const response = responseEvent.data;
+      if (response?.type === 'event' && typeof response.subscriptionId === 'string') {
+        pageEventListeners.get(response.subscriptionId)?.(response.event, response.metadata);
+        return;
+      }
       if (response?.type === 'context') {
         applyContext(response.context);
         return;
@@ -506,7 +466,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
       if (!request) return;
       pending.delete(response.requestId);
       if (response.ok) request.resolve(response.result);
-      else request.reject(new Error(response.error || 'Plugin command failed'));
+      else request.reject(Object.assign(new Error(response.error || 'Plugin command failed'), { handledByHost: response.handledByHost === true }));
     };
     port.start();
     resolveReady(context);
@@ -604,6 +564,11 @@ body {
 }
 button, input, select, textarea { font: inherit; }
 </style>`;
+export const PLUGIN_PAGE_RUNTIME_HASH = createHash('sha256')
+    .update(PAGE_BRIDGE_SCRIPT)
+    .update(PAGE_SECURITY_META)
+    .update(PAGE_THEME_STYLE)
+    .digest('hex');
 function pluginRoot(entry) {
     const entryDirectory = dirname(entry);
     return basename(entryDirectory) === 'scripts' ? dirname(entryDirectory) : entryDirectory;

package/dist/pluginRegistry.d.ts

@@ -18,6 +18,7 @@ export interface PluginToolboxAgentConfig {
 }
 export interface PluginToolboxContribution {
     version: 1;
+    displayMode?: 'popup' | 'tab' | 'both';
     title: string;
     description?: string;
     icon?: string;
@@ -40,6 +41,7 @@ export interface PluginRegistration {
     source?: {
         entry: string;
         page?: Record<string, string>;
+        pageRuntime?: string;
     };
 }
 export declare function pluginRegistrationNeedsRefresh(registration: PluginRegistration, includePage?: boolean): boolean;

package/dist/pluginRegistry.js

@@ -3,7 +3,7 @@ import { closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, re
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { COMMAND_MAP } from './commands.js';
-import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, } from './pluginPageBundle.js';
+import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, PLUGIN_PAGE_RUNTIME_HASH, } from './pluginPageBundle.js';
 import { pluginFileVersion } from './pluginSource.js';
 const RESERVED_NAMES = new Set([
     'check',
@@ -27,6 +27,8 @@ export function pluginRegistrationNeedsRefresh(registration, includePage = false
         return true;
     if (!includePage || !registration.toolbox)
         return false;
+    if (registration.source.pageRuntime !== PLUGIN_PAGE_RUNTIME_HASH)
+        return true;
     if (!registration.source.page)
         return true;
     return Object.entries(registration.source.page).some(([path, version]) => pluginFileVersion(path) !== version);
@@ -108,6 +110,10 @@ export function normalizePluginToolboxContribution(value) {
         throw new Error('toolbox 必须是对象');
     }
     const candidate = value;
+    if (candidate.displayMode !== undefined &&
+        !['popup', 'tab', 'both'].includes(candidate.displayMode)) {
+        throw new Error('toolbox.displayMode 必须是 popup、tab 或 both');
+    }
     const title = typeof candidate.title === 'string' ? candidate.title.trim() : '';
     const description = typeof candidate.description === 'string' ? candidate.description.trim() : undefined;
     const icon = typeof candidate.icon === 'string' ? candidate.icon.trim() : undefined;
@@ -216,6 +222,7 @@ export function normalizePluginToolboxContribution(value) {
     return {
         version: 1,
         title,
+        ...(candidate.displayMode !== undefined ? { displayMode: candidate.displayMode } : {}),
         ...(description ? { description } : {}),
         ...(icon ? { icon } : {}),
         ...(locales ? { locales } : {}),
@@ -281,7 +288,10 @@ export function registerPlugin(name, target, description, options = {}) {
     }
     const record = {
         entry,
-        source: { entry: entryVersion, ...(builtPage ? { page: builtPage.sources } : {}) },
+        source: {
+            entry: entryVersion,
+            ...(builtPage ? { page: builtPage.sources, pageRuntime: PLUGIN_PAGE_RUNTIME_HASH } : {}),
+        },
         ...(summary ? { description: summary } : {}),
         ...(managedBy ? { managedBy } : {}),
         ...(toolbox ? { toolbox } : {}),
@@ -344,6 +354,8 @@ export function findPluginRegistration(name) {
                 typeof source !== 'object' ||
                 Array.isArray(source) ||
                 typeof source.entry !== 'string' ||
+                (source.pageRuntime !== undefined &&
+                    (typeof source.pageRuntime !== 'string' || !/^[a-f0-9]{64}$/.test(source.pageRuntime))) ||
                 (source.page !== undefined &&
                     (!source.page ||
                         typeof source.page !== 'object' ||

package/dist/pythonPlugin.d.ts

@@ -2,6 +2,7 @@ import type { PluginOptions } from './plugin.js';
 export interface PythonPluginCommand {
     description: string;
     signature: string;
+    toolboxOnly: boolean;
 }
 export interface PythonPluginDescriptor {
     commands: PythonPluginCommand[];

package/dist/pythonPlugin.js

@@ -53,6 +53,12 @@ class _App:
         self.request_id = 0
 
     def command(self, signature, handler=None, description=""):
+        return self._register_command(signature, handler, description, False)
+
+    def toolboxCommand(self, signature, handler=None, description=""):
+        return self._register_command(signature, handler, description, True)
+
+    def _register_command(self, signature, handler, description, toolbox_only):
         if not self.registering:
             raise RuntimeError("命令只能在入口注册阶段声明")
         if not isinstance(signature, str):
@@ -67,6 +73,7 @@ class _App:
                 "signature": signature,
                 "description": description,
                 "handler": candidate,
+                "toolboxOnly": toolbox_only,
             })
             return candidate
 
@@ -163,7 +170,7 @@ try:
     descriptor = {
         "type": "ready",
         "commands": [
-            {"signature": item["signature"], "description": item["description"]}
+            {"signature": item["signature"], "description": item["description"], "toolboxOnly": item["toolboxOnly"]}
             for item in app.commands
         ],
     }
@@ -223,10 +230,15 @@ function parseDescriptor(message) {
     const commands = message.commands.map(value => {
         if (!isObject(value) ||
             typeof value.signature !== 'string' ||
-            typeof value.description !== 'string') {
+            typeof value.description !== 'string' ||
+            typeof value.toolboxOnly !== 'boolean') {
             throw new Error('Python 插件返回了无效的命令描述');
         }
-        return { signature: value.signature, description: value.description };
+        return {
+            signature: value.signature,
+            description: value.description,
+            toolboxOnly: value.toolboxOnly,
+        };
     });
     if (message.name !== undefined && typeof message.name !== 'string') {
         throw new Error('Python 插件返回了无效的 name');

package/dist/socket.d.ts

@@ -18,6 +18,8 @@ export type ControlSource = 'local' | 'remote';
 type CompatibleControlSource = ControlSource | 'cloud';
 export interface InvokeOptions {
     controlSessionId?: string;
+    /** Pin a known local endpoint for a sequence of transport requests. */
+    socketPath?: string;
     /** 超时时间（秒），默认 15 */
     timeoutSec?: number;
     /** Force CDP transport instead of extension */
@@ -31,6 +33,11 @@ export interface InvokeOptions {
 export declare function setDefaultBrowser(selector: string | undefined): void;
 export declare function getDefaultBrowser(): string | undefined;
 export declare function decorateBrowserListResult(result: Record<string, any>): Record<string, any>;
+/** Resolve an existing local route without executing the action. */
+export declare function resolveLocalActionTarget(action: string, data: Record<string, any>, options?: InvokeOptions): {
+    browser?: string;
+    socketPath?: string;
+} | undefined;
 /**
  * 向 native host 发送一个 action 请求并等待响应。
  *

package/dist/socket.js

@@ -18,6 +18,7 @@ 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;
 const MAX_SOCKET_BUFFER_SIZE = 64 * 1024 * 1024;
@@ -160,6 +161,24 @@ function supportsAction(browser, action, data) {
     return (browser.transport !== 'provider' ||
         browser.capabilities?.actions.some(capability => capability === action) === true);
 }
+function routableBrowsers(browsers, action, data, transport) {
+    return browsers.filter(browser => isConnectedBrowser(browser) &&
+        (action !== 'browser_list' || browser.transport !== 'provider') &&
+        !(transport === 'cdp' && browser.transport === 'provider') &&
+        supportsAction(browser, action, data));
+}
+/** Resolve an existing local route without executing the action. */
+export function resolveLocalActionTarget(action, data, options = {}) {
+    const selector = options.browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
+    const socketPath = options.socketPath ?? process.env.MEARL_SOCKET_PATH?.trim();
+    if (socketPath && (options.socketPath || !selector))
+        return { socketPath };
+    const browsers = listLiveBrowsers();
+    const target = selector
+        ? findBrowser(browsers, selector)
+        : routableBrowsers(browsers, action, data, options.transport)[0];
+    return target ? { browser: target.browserId } : undefined;
+}
 function selectBrowserResult(data) {
     const selector = typeof data.browser === 'string' ? data.browser.trim() : '';
     if (!selector) {
@@ -329,6 +348,17 @@ function removeStaleLegacySocket(identity) {
  * legacy well-known socket，并在 socket 不存在或已残留时自动拉起 native host。
  */
 export function invoke(action, data = {}, options = {}) {
+    if (action === '__resolve_action_target') {
+        if (!isBrowserCapabilityAction(data.action))
+            return Promise.reject(new Error('Invalid browser capability action'));
+        const target = resolveLocalActionTarget(data.action, data.data ?? {}, options);
+        const browser = target?.browser ??
+            (target?.socketPath
+                ? listLiveBrowsers().find(item => item.socketPath === target.socketPath &&
+                    supportsAction(item, data.action, data.data ?? {}))?.browserId
+                : undefined);
+        return Promise.resolve(browser ? { browser } : null);
+    }
     if (action === 'browser_select_browser') {
         try {
             return Promise.resolve(selectBrowserResult(data));
@@ -338,14 +368,50 @@ export function invoke(action, data = {}, options = {}) {
         }
     }
     const { timeoutSec = resolveActionTimeoutSec(action, data), transport, browser, controlSource = 'local', } = options;
+    if (action === '__control_session_resolve') {
+        return resolveControlSession(data.sessionId, timeoutSec, controlSource);
+    }
     // 统一解析 payload 顶层字段中的 `@<path>` 文件引用（所有 action 通用）
     const resolvedData = resolveFileRefs(data);
     Object.defineProperty(resolvedData, SESSION_OPTION, { value: options.controlSessionId });
     if (action === 'browser_list') {
-        return dispatchInvoke(action, resolvedData, timeoutSec, transport, undefined, controlSource).then(result => decorateBrowserListResult(transport === 'cdp' ? cdpOnlyBrowserList(result) : result));
+        return dispatchInvoke(action, resolvedData, timeoutSec, transport, undefined, controlSource, options.socketPath).then(result => decorateBrowserListResult(transport === 'cdp' ? cdpOnlyBrowserList(result) : result));
     }
     const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
-    return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector, controlSource);
+    return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector, controlSource, options.socketPath);
+}
+/** Session ownership lives in the control hosts and survives individual CLI connections. */
+async function resolveControlSession(sessionId, timeoutSec, controlSource) {
+    const browsers = listLiveBrowsers();
+    const configuredSocketPath = process.env.MEARL_SOCKET_PATH?.trim();
+    const sockets = configuredSocketPath
+        ? [configuredSocketPath]
+        : [
+            ...new Set(browsers
+                .filter(browser => browser.transport !== 'provider')
+                .map(browser => browser.socketPath)),
+        ];
+    const provider = configuredSocketPath
+        ? undefined
+        : browsers.find(browser => browser.transport === 'provider');
+    if (!sockets.length && !provider)
+        sockets.push(SOCKET_PATH);
+    const requests = sockets.map(socketPath => invokeOnce('__control_session_resolve', { sessionId }, timeoutSec, undefined, socketPath, controlSource));
+    if (provider) {
+        requests.push(invokeOnce('__control_session_resolve', { sessionId }, timeoutSec, undefined, provider.socketPath, controlSource, provider.browserId));
+    }
+    const results = await Promise.allSettled(requests);
+    const sessions = results.flatMap(result => result.status === 'fulfilled' && result.value?.session?.sessionId === sessionId
+        ? [result.value.session]
+        : []);
+    if (sessions.length > 1)
+        throw new Error('CONTROL_SESSION_AMBIGUOUS: multiple hosts own this id');
+    if (sessions.length)
+        return { session: sessions[0] };
+    const failure = results.find(result => result.status === 'rejected' && !isConnError(result.reason));
+    if (failure?.status === 'rejected')
+        throw failure.reason;
+    return { session: null };
 }
 function isConnError(error) {
     const code = error?.code;
@@ -359,9 +425,9 @@ function isUnavailableConnection(error) {
     const code = cause?.code;
     return isConnError(cause) || isSocketSandboxError(cause) || code === 'EACCES';
 }
-async function dispatchInvoke(action, data, timeoutSec, transport, selector, controlSource) {
-    const configuredSocketPath = process.env.MEARL_SOCKET_PATH?.trim();
-    if (!selector && configuredSocketPath) {
+async function dispatchInvoke(action, data, timeoutSec, transport, selector, controlSource, socketPath) {
+    const configuredSocketPath = socketPath ?? process.env.MEARL_SOCKET_PATH?.trim();
+    if (configuredSocketPath && (socketPath || !selector)) {
         try {
             return await invokeOnce(action, data, timeoutSec, transport, configuredSocketPath, controlSource);
         }
@@ -447,11 +513,9 @@ 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 => (action !== 'browser_list' || browser.transport !== 'provider') &&
-        !(transport === 'cdp' && browser.transport === 'provider') &&
-        supportsAction(browser, action, data));
-    if (routableBrowsers.length > 0) {
-        const target = routableBrowsers[0];
+    const candidates = routableBrowsers(browsers, action, data, transport);
+    if (candidates.length > 0) {
+        const target = candidates[0];
         try {
             return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined);
         }

package/dist/unified.d.ts

@@ -30,12 +30,8 @@ interface BrowserTarget {
 }
 export declare function decodeBrowserTarget(selector: string | undefined): BrowserTarget | undefined;
 export declare function normalizeBrowserSelector(selector: string): string;
-export declare function decodeControlSessionId(id: string): {
-    browser: string;
-    id: string;
-    transport: 'extension' | 'cdp' | 'provider';
-};
 export declare class UnifiedClient {
+    private readonly controlSessions;
     private readonly options;
     private defaultBrowser;
     private defaultConnector;
@@ -55,6 +51,7 @@ export declare class UnifiedClient {
         outputPath: string;
         bytes: number;
     }>;
+    private pinPageEvalTarget;
     private invokeRouted;
     private invokeExplicitLocal;
     private invokeLaunchWithoutControlBrowser;
@@ -71,6 +68,7 @@ export declare class UnifiedClient {
     private invokeLocal;
     private invokeRemote;
     private decorateActionResult;
+    private resolveControlSession;
     private ensureConnected;
     private connect;
     private startHeartbeat;