@mearl/client 2.19.2 → 2.20.0

package/dist/pluginRegistry.js

@@ -4,6 +4,7 @@ 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 { pluginFileVersion } from './pluginSource.js';
 const RESERVED_NAMES = new Set([
     'check',
     'help',
@@ -19,6 +20,17 @@ export class PluginError extends Error {
         this.code = code;
     }
 }
+export function pluginRegistrationNeedsRefresh(registration, includePage = false) {
+    if (!registration.source)
+        return true;
+    if (pluginFileVersion(registration.entry) !== registration.source.entry)
+        return true;
+    if (!includePage || !registration.toolbox)
+        return false;
+    if (!registration.source.page)
+        return true;
+    return Object.entries(registration.source.page).some(([path, version]) => pluginFileVersion(path) !== version);
+}
 export function pluginDirectory() {
     return resolve(process.env.MEARL_PLUGIN_DIR || join(homedir(), '.mearl', 'plugins'));
 }
@@ -242,6 +254,7 @@ export function resolvePluginEntry(target) {
 export function registerPlugin(name, target, description, options = {}) {
     assertPluginName(name);
     const entry = resolvePluginEntry(target);
+    const entryVersion = pluginFileVersion(entry);
     const directory = pluginDirectory();
     mkdirSync(directory, { recursive: true, mode: 0o700 });
     const file = join(directory, `${name}.json`);
@@ -268,6 +281,7 @@ export function registerPlugin(name, target, description, options = {}) {
     }
     const record = {
         entry,
+        source: { entry: entryVersion, ...(builtPage ? { page: builtPage.sources } : {}) },
         ...(summary ? { description: summary } : {}),
         ...(managedBy ? { managedBy } : {}),
         ...(toolbox ? { toolbox } : {}),
@@ -324,12 +338,26 @@ export function findPluginRegistration(name) {
             : undefined;
         const toolbox = normalizePluginToolboxContribution(record.toolbox);
         const pageBundle = toolbox ? normalizePageBundle(record.pageBundle) : undefined;
+        const source = record.source;
+        if (source !== undefined &&
+            (!source ||
+                typeof source !== 'object' ||
+                Array.isArray(source) ||
+                typeof source.entry !== 'string' ||
+                (source.page !== undefined &&
+                    (!source.page ||
+                        typeof source.page !== 'object' ||
+                        Array.isArray(source.page) ||
+                        Object.entries(source.page).some(([path, version]) => !isAbsolute(path) || typeof version !== 'string'))))) {
+            throw new Error('invalid source');
+        }
         return {
             entry: record.entry,
             ...(description ? { description } : {}),
             ...(managedBy ? { managedBy } : {}),
             ...(toolbox ? { toolbox } : {}),
             ...(pageBundle ? { pageBundle } : {}),
+            ...(source ? { source } : {}),
         };
     }
     catch {

package/dist/pluginSource.d.ts

@@ -0,0 +1,2 @@
+/** 文件替换和同大小写入都需要使缓存失效；检测只读取文件元数据。 */
+export declare function pluginFileVersion(path: string): string;

package/dist/pluginSource.js

@@ -0,0 +1,8 @@
+import { statSync } from 'node:fs';
+/** 文件替换和同大小写入都需要使缓存失效；检测只读取文件元数据。 */
+export function pluginFileVersion(path) {
+    const stat = statSync(path);
+    if (!stat.isFile())
+        throw new Error(`插件资源不是文件: ${path}`);
+    return `${stat.dev}-${stat.ino}-${stat.mtimeMs}-${stat.ctimeMs}-${stat.size}`;
+}

package/dist/socket.d.ts

@@ -17,6 +17,7 @@ export declare const SOCKET_PATH: string;
 export type ControlSource = 'local' | 'remote';
 type CompatibleControlSource = ControlSource | 'cloud';
 export interface InvokeOptions {
+    controlSessionId?: string;
     /** 超时时间（秒），默认 15 */
     timeoutSec?: number;
     /** Force CDP transport instead of extension */

package/dist/socket.js

@@ -13,7 +13,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { StringDecoder } from 'node:string_decoder';
-import { listInstalledProviders } from '@mearl/provider/host';
+import { ensureProviderControlHost, listInstalledProviders } from '@mearl/provider/host';
 import { readLiveProvider } from '@mearl/provider/runtime';
 import { resolveFileRefs } from './fileRefs.js';
 import { listLiveBrowsers, findBrowser, describeBrowser, } from './browserRegistry.js';
@@ -32,6 +32,7 @@ export const SOCKET_PATH = process.platform === 'win32'
 function toControlSourceWireValue(source) {
     return source === 'remote' || source === 'cloud' ? 'cloud' : 'local';
 }
+const SESSION_OPTION = Symbol('control-session');
 /**
  * Process-wide default browser selector. Lets a long-lived host (e.g. the MCP
  * server) pin a target once via `select_browser` without threading it through
@@ -96,13 +97,50 @@ function browserListFromProviderRecords(browsers) {
         browsers: providerBrowsers,
     };
 }
+function withDiscoveryWarning(result, error) {
+    const cause = error.cause ?? error;
+    const code = cause?.code;
+    const detail = code ?? (error instanceof Error ? error.message.split('\n')[0] : String(error));
+    return {
+        ...result,
+        warnings: [
+            ...(Array.isArray(result.warnings) ? result.warnings : []),
+            `Local CDP discovery could not complete: ${detail}`,
+        ],
+    };
+}
+function cdpOnlyBrowserList(result) {
+    const browsers = Array.isArray(result.browsers) ? result.browsers : [];
+    const cdpBrowsers = browsers.filter(browser => browser.transport === 'cdp');
+    return {
+        ...result,
+        count: cdpBrowsers.length,
+        connectedCount: cdpBrowsers.filter(browser => browser.status === 'connected').length,
+        browsers: cdpBrowsers,
+    };
+}
 function areInstalledProvidersRunning() {
     return listInstalledProviders().every(provider => readLiveProvider(provider.providerId));
 }
 function isConnectedBrowser(browser) {
     return browser.status === undefined || browser.status === 'connected';
 }
+function isOrdinaryLocalBrowser(browser) {
+    return (!browser.browserId.startsWith('managed:') &&
+        (browser.transport === 'extension' || browser.transport === 'cdp'));
+}
 function supportsAction(browser, action, data) {
+    if (browser.transport === 'provider') {
+        if (action === 'browser_control' ||
+            (action === 'browser_release' && data[SESSION_OPTION]))
+            return true;
+        if (action.startsWith('__artifact_'))
+            return (browser.capabilities?.actions.includes('page_upload') === true ||
+                ((action === '__artifact_read' || action === '__artifact_remove') &&
+                    browser.capabilities?.actions.includes('page_download') === true));
+        if (action === 'run_actions' && data[SESSION_OPTION])
+            return true;
+    }
     if (action === 'get_versions')
         return true;
     if (action === 'get_browser_access_url') {
@@ -141,47 +179,62 @@ function selectBrowserResult(data) {
 }
 /** Deduplicates concurrent recovery attempts in long-lived clients such as the MCP server. */
 let persistentSpawnPromise = null;
+let discoveryListPromise = null;
+let discoveryListCache = null;
+const DISCOVERY_STARTUP_TIMEOUT_MS = 3_000;
+const DISCOVERY_RETRY_INTERVAL_MS = 50;
+const DISCOVERY_MISS_CACHE_MS = 2_000;
+function instanceSocketPath(pid) {
+    return process.platform === 'win32'
+        ? `\\\\.\\pipe\\mearl-agent-${pid}`
+        : path.join(os.tmpdir(), `mearl-agent-${pid}.sock`);
+}
+function discoveryCacheKey() {
+    const browsers = listLiveBrowsers()
+        .map(browser => [
+        browser.browserId,
+        browser.pid,
+        browser.socketPath,
+        browser.status,
+        browser.updatedAt,
+    ])
+        .sort((a, b) => String(a[0]).localeCompare(String(b[0])));
+    const providers = listInstalledProviders()
+        .map(provider => provider.providerId)
+        .sort();
+    return JSON.stringify({ browsers, providers });
+}
+async function spawnNativeHost(args) {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve, reject) => {
+        const child = spawn('mearl-native-host', args, {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.once('error', reject);
+        child.once('spawn', () => {
+            child.unref();
+            resolve(child.pid);
+        });
+    });
+}
 /**
  * Attempt to spawn `mearl-native-host` in the background (detached).
- * Browser discovery hosts probe the default local CDP endpoint for browser_list and only
- * persist when a real browser is available.
  * Returns true if a spawn was attempted (regardless of success).
  */
-async function trySpawnNativeHost(mode = 'control') {
-    const persistent = mode === 'control';
-    if (persistent && persistentSpawnPromise)
+async function trySpawnNativeHost() {
+    if (persistentSpawnPromise)
         return persistentSpawnPromise;
     const spawnPromise = (async () => {
         try {
-            const { spawn } = await import('node:child_process');
-            return await new Promise(resolve => {
-                const args = persistent ? ['--daemon'] : ['--daemon', '--discover-cdp'];
-                const child = spawn('mearl-native-host', args, {
-                    detached: true,
-                    stdio: 'ignore',
-                    windowsHide: true,
-                });
-                let settled = false;
-                const finish = (ok) => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    resolve(ok);
-                };
-                // `spawn ENOENT` 等错误会通过事件异步抛出；必须显式监听避免进程崩溃。
-                child.once('error', () => finish(false));
-                child.once('spawn', () => {
-                    child.unref();
-                    finish(true);
-                });
-            });
+            await spawnNativeHost(['--daemon']);
+            return true;
         }
         catch {
             return false;
         }
     })();
-    if (!persistent)
-        return spawnPromise;
     persistentSpawnPromise = spawnPromise;
     try {
         return await spawnPromise;
@@ -191,6 +244,54 @@ async function trySpawnNativeHost(mode = 'control') {
             persistentSpawnPromise = null;
     }
 }
+async function discoverLocalBrowserList(timeoutSec, controlSource) {
+    if (discoveryListPromise)
+        return discoveryListPromise;
+    const cacheKey = discoveryCacheKey();
+    if (discoveryListCache &&
+        discoveryListCache.key === cacheKey &&
+        Date.now() < discoveryListCache.until) {
+        if (discoveryListCache.error)
+            throw discoveryListCache.error;
+        return discoveryListCache.result;
+    }
+    discoveryListCache = null;
+    const request = (async () => {
+        const pid = await spawnNativeHost(['--daemon', '--discover-cdp']);
+        if (pid === undefined)
+            throw new Error('Native host did not report its process id');
+        const socketPath = instanceSocketPath(pid);
+        const deadline = Date.now() + Math.min(timeoutSec * 1_000, DISCOVERY_STARTUP_TIMEOUT_MS);
+        while (true) {
+            try {
+                return await invokeOnce('browser_list', {}, timeoutSec, undefined, socketPath, controlSource);
+            }
+            catch (error) {
+                if (!isConnError(error) || Date.now() >= deadline)
+                    throw error;
+                await new Promise(resolve => setTimeout(resolve, DISCOVERY_RETRY_INTERVAL_MS));
+            }
+        }
+    })();
+    discoveryListPromise = request;
+    try {
+        const result = await request;
+        if (!result.browsers?.some((browser) => browser.transport === 'cdp' &&
+            browser.status === 'connected' &&
+            !browser.browserId?.startsWith('managed:'))) {
+            discoveryListCache = { key: cacheKey, result, until: Date.now() + DISCOVERY_MISS_CACHE_MS };
+        }
+        return result;
+    }
+    catch (error) {
+        discoveryListCache = { key: cacheKey, error, until: Date.now() + DISCOVERY_MISS_CACHE_MS };
+        throw error;
+    }
+    finally {
+        if (discoveryListPromise === request)
+            discoveryListPromise = null;
+    }
+}
 function readOwnedLegacySocketIdentity() {
     if (process.platform === 'win32')
         return null;
@@ -239,8 +340,9 @@ export function invoke(action, data = {}, options = {}) {
     const { timeoutSec = resolveActionTimeoutSec(action, data), transport, browser, controlSource = 'local', } = options;
     // 统一解析 payload 顶层字段中的 `@<path>` 文件引用（所有 action 通用）
     const resolvedData = resolveFileRefs(data);
+    Object.defineProperty(resolvedData, SESSION_OPTION, { value: options.controlSessionId });
     if (action === 'browser_list') {
-        return dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(result => decorateBrowserListResult(result));
+        return dispatchInvoke(action, resolvedData, timeoutSec, transport, undefined, controlSource).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);
@@ -252,6 +354,11 @@ function isConnError(error) {
 function isSocketSandboxError(error) {
     return error?.code === 'EPERM';
 }
+function isUnavailableConnection(error) {
+    const cause = error.cause ?? 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) {
@@ -269,6 +376,44 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     }
     const browsers = listLiveBrowsers();
     const controllableBrowsers = browsers.filter(isConnectedBrowser);
+    if (action === 'browser_list' && transport === 'cdp') {
+        const registeredCdp = controllableBrowsers.find(browser => browser.transport === 'cdp' && isOrdinaryLocalBrowser(browser));
+        if (registeredCdp) {
+            try {
+                return await invokeOnce(action, data, timeoutSec, transport, registeredCdp.socketPath, controlSource);
+            }
+            catch (error) {
+                if (!isConnError(error))
+                    throw error;
+            }
+        }
+        try {
+            return await discoverLocalBrowserList(timeoutSec, controlSource);
+        }
+        catch (error) {
+            if (isUnavailableConnection(error) &&
+                browsers.some(browser => browser.transport === 'provider') &&
+                areInstalledProvidersRunning()) {
+                return withDiscoveryWarning(browserListFromProviderRecords(browsers), error);
+            }
+            throw error;
+        }
+    }
+    // A Provider record can keep the registry nonempty without representing a local
+    // browser transport. Let the discovery daemon probe CDP before returning that inventory.
+    if (action === 'browser_list' && !controllableBrowsers.some(isOrdinaryLocalBrowser)) {
+        try {
+            return await discoverLocalBrowserList(timeoutSec, controlSource);
+        }
+        catch (error) {
+            if (isUnavailableConnection(error) &&
+                browsers.some(browser => browser.transport === 'provider') &&
+                areInstalledProvidersRunning()) {
+                return withDiscoveryWarning(browserListFromProviderRecords(browsers), error);
+            }
+            throw error;
+        }
+    }
     // Explicit target: must match a live browser; do not silently fall back.
     if (selector) {
         const match = findBrowser(browsers, selector);
@@ -281,14 +426,15 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
         if (match.status === 'pairing' &&
             action !== 'get_versions' &&
             action !== 'browser_close' &&
-            action !== 'browser_release') {
+            action !== 'browser_release' &&
+            action !== 'browser_control') {
             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 {
-            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource, match.providerBrowserId);
+            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource, match.transport === 'provider' ? match.browserId : undefined);
         }
         catch (error) {
             if (isConnError(error) || isSocketSandboxError(error)) {
@@ -301,12 +447,13 @@ 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') &&
+    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];
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.providerBrowserId);
+            return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined);
         }
         catch (error) {
             if (isSocketSandboxError(error)) {
@@ -318,10 +465,18 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
                 throw error;
         }
     }
-    if (action === 'browser_list' &&
-        browsers.some(browser => browser.transport === 'provider') &&
-        areInstalledProvidersRunning()) {
-        return browserListFromProviderRecords(browsers);
+    if (action === 'browser_list') {
+        try {
+            return await discoverLocalBrowserList(timeoutSec, controlSource);
+        }
+        catch (error) {
+            if (isUnavailableConnection(error) &&
+                browsers.some(browser => browser.transport === 'provider') &&
+                areInstalledProvidersRunning()) {
+                return withDiscoveryWarning(browserListFromProviderRecords(browsers), error);
+            }
+            throw error;
+        }
     }
     return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, /* isRetry */ false);
 }
@@ -337,21 +492,15 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
         if (shouldAttemptSpawn && !isRetry) {
             if (err.code === 'ECONNREFUSED')
                 removeStaleLegacySocket(legacySocketIdentity);
-            const spawned = await trySpawnNativeHost(action === 'browser_list' ? 'discovery' : 'control');
+            const spawned = await trySpawnNativeHost();
             if (spawned) {
-                // Wait for the native host to start listening. Discovery retries the legacy socket directly
-                // so the spawned host receives the probe even if another browser registers in the meantime.
                 await new Promise(r => setTimeout(r, 1200));
-                if (action === 'browser_list') {
-                    return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, 
-                    /* isRetry */ true);
-                }
                 const browsers = listLiveBrowsers();
                 const target = browsers.find(browser => isConnectedBrowser(browser) &&
                     !(transport === 'cdp' && browser.transport === 'provider') &&
                     supportsAction(browser, action, data));
                 if (target) {
-                    return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.providerBrowserId);
+                    return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined);
                 }
                 return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, 
                 /* isRetry */ true);
@@ -362,7 +511,11 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
         throw new Error(formatConnectError(err, SOCKET_PATH), { cause: error });
     }
 }
-function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource, providerBrowserId) {
+async function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource, providerTarget) {
+    if (providerTarget) {
+        const host = await ensureProviderControlHost(Math.min(timeoutSec * 1000, 10_000));
+        socketPath = host.socketPath;
+    }
     const id = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     return new Promise((resolve, reject) => {
         if (process.platform !== 'win32' && fs.existsSync(socketPath) && process.getuid) {
@@ -401,10 +554,12 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSour
                 version: CLIENT_VERSION,
                 controlSource: toControlSourceWireValue(controlSource),
             };
+            if (data[SESSION_OPTION])
+                message.controlSessionId = data[SESSION_OPTION];
             if (transport)
                 message.transport = transport;
-            if (providerBrowserId)
-                message.browserId = providerBrowserId;
+            if (providerTarget)
+                message.providerTarget = providerTarget;
             socket.write(JSON.stringify(message) + '\n');
         });
         socket.on('data', chunk => {
@@ -453,7 +608,8 @@ function formatConnectError(error, socketPath) {
     if (error.code === 'ENOENT') {
         return [
             `未找到 Socket: ${socketPath}`,
-            'native host 自动拉起失败，请手动排查：',
+            'native host 自动拉起失败。先运行 mearl check --local；缺少命令时运行 npx @mearl/setup --local --yes。',
+            '自动拉起只使用默认 daemon 参数；自定义 CDP/Profile/浏览器参数需手工启动，参见 mearl-native-host --help。',
             '',
             '【方式一：浏览器插件模式】',
             `1. 确认已安装 Mearl 浏览器插件（${EXTENSION_INSTALL_URL}）`,
@@ -469,7 +625,7 @@ function formatConnectError(error, socketPath) {
     if (error.code === 'ECONNREFUSED') {
         return [
             `Socket 连接被拒绝: ${socketPath}`,
-            'native host 自动恢复失败。',
+            '已尝试处理 stale socket，但 native host 自动恢复仍失败。请运行 mearl check --local 定位故障。',
             '请确认 Chrome 浏览器正在运行，可尝试在 chrome://extensions 重新加载插件。',
             '',
             installHint,

package/dist/unified.d.ts

@@ -1,6 +1,11 @@
+import type { BrowserArtifact } from './generated-browser-action-protocol.js';
 import { type CloudConnectorListResult } from '@mearl/cloud-types';
 import type { PluginInvocation, PluginInvokeOptions } from './plugin.js';
 export interface UnifiedInvokeOptions {
+    /** Use new on the first tab_open/page_snapshot, then reuse the returned id. */
+    session?: string;
+    /** Source-local session id used by transport adapters. */
+    controlSessionId?: string;
     timeoutSec?: number;
     /** Global browser id, source-local browser id, or unique browser name. */
     browser?: string;
@@ -25,6 +30,11 @@ 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 options;
     private defaultBrowser;
@@ -39,6 +49,13 @@ export declare class UnifiedClient {
     disconnect(): void;
     invokePlugin(name: string, invocation: PluginInvocation, options?: PluginInvokeOptions): Promise<unknown>;
     invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+    saveArtifact(artifact: BrowserArtifact & {
+        browserId?: string;
+    }, outputPath: string, options?: UnifiedInvokeOptions): Promise<{
+        outputPath: string;
+        bytes: number;
+    }>;
+    private invokeRouted;
     private invokeExplicitLocal;
     private invokeLaunchWithoutControlBrowser;
     private selectDefaultBrowser;