@mearl/client 2.14.0 → 2.15.1

package/dist/socket.js

@@ -4,7 +4,8 @@
  * 通过 Unix Domain Socket (macOS/Linux) 或 Named Pipe (Windows) 与 native host 进程通信。
  * 每次调用新建连接，收到响应后关闭，简单可靠。
  *
- * 当 Socket 文件不存在（ENOENT）时，自动尝试拉起 native host，稍后重试连接。
+ * 当 Socket 不存在，或 legacy Socket 是无人监听的残留文件时，
+ * 自动尝试拉起 native host，稍后重试连接。
  */
 import net from 'node:net';
 import fs from 'node:fs';
@@ -138,46 +139,85 @@ function selectBrowserResult(data) {
     setDefaultBrowser(match.browserId);
     return { selected: { browserId: match.browserId, name: match.browserName } };
 }
-/** Whether this process has already attempted to auto-spawn a persistent native-host. */
-let spawnAttempted = false;
+/** Deduplicates concurrent recovery attempts in long-lived clients such as the MCP server. */
+let persistentSpawnPromise = null;
 /**
  * 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', retryPreviousAttempt = false) {
+async function trySpawnNativeHost(mode = 'control') {
     const persistent = mode === 'control';
-    if (persistent && spawnAttempted && !retryPreviousAttempt)
-        return false;
-    if (persistent)
-        spawnAttempted = true;
-    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);
+    if (persistent && 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);
+                });
             });
-        });
+        }
+        catch {
+            return false;
+        }
+    })();
+    if (!persistent)
+        return spawnPromise;
+    persistentSpawnPromise = spawnPromise;
+    try {
+        return await spawnPromise;
+    }
+    finally {
+        if (persistentSpawnPromise === spawnPromise)
+            persistentSpawnPromise = null;
+    }
+}
+function readOwnedLegacySocketIdentity() {
+    if (process.platform === 'win32')
+        return null;
+    try {
+        const stat = fs.lstatSync(SOCKET_PATH);
+        if (!stat.isSocket())
+            return null;
+        if (process.getuid && stat.uid !== process.getuid())
+            return null;
+        return { dev: stat.dev, ino: stat.ino };
     }
     catch {
-        return false;
+        return null;
+    }
+}
+/** Remove only the same-user socket inode whose failed connection proved it stale. */
+function removeStaleLegacySocket(identity) {
+    if (!identity)
+        return;
+    try {
+        const current = fs.lstatSync(SOCKET_PATH);
+        if (!current.isSocket() || current.dev !== identity.dev || current.ino !== identity.ino)
+            return;
+        fs.unlinkSync(SOCKET_PATH);
+    }
+    catch {
+        // Spawning and the final retry provide the authoritative recovery result.
     }
 }
 /**
@@ -185,7 +225,7 @@ async function trySpawnNativeHost(mode = 'control', retryPreviousAttempt = false
  *
  * 目标解析优先级：显式 options.browser → setDefaultBrowser → 环境变量
  * MEARL_BROWSER → 自动（注册表中最近聚焦的浏览器）。注册表为空时回退到
- * legacy well-known socket，并在 socket 不存在（ENOENT）时自动拉起 native host。
+ * legacy well-known socket，并在 socket 不存在或已残留时自动拉起 native host。
  */
 export function invoke(action, data = {}, options = {}) {
     if (action === 'browser_select_browser') {
@@ -284,16 +324,19 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     }
     return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, /* isRetry */ false);
 }
-/** Legacy well-known socket, auto-spawning a native-host on ENOENT and retrying once. */
+/** Legacy well-known socket, repairing a missing or stale endpoint and retrying once. */
 async function invokeViaLegacy(action, data, timeoutSec, transport, controlSource, isRetry) {
+    const legacySocketIdentity = readOwnedLegacySocketIdentity();
     try {
         return await invokeOnce(action, data, timeoutSec, transport, SOCKET_PATH, controlSource);
     }
     catch (error) {
         const err = error;
-        const shouldAttemptSpawn = err.code === 'ENOENT' || (action === 'browser_release' && err.code === 'ECONNREFUSED');
+        const shouldAttemptSpawn = err.code === 'ENOENT' || err.code === 'ECONNREFUSED';
         if (shouldAttemptSpawn && !isRetry) {
-            const spawned = await trySpawnNativeHost(action === 'browser_list' ? 'discovery' : 'control', action === 'browser_release');
+            if (err.code === 'ECONNREFUSED')
+                removeStaleLegacySocket(legacySocketIdentity);
+            const spawned = await trySpawnNativeHost(action === 'browser_list' ? 'discovery' : 'control');
             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.
@@ -425,7 +468,7 @@ function formatConnectError(error, socketPath) {
     if (error.code === 'ECONNREFUSED') {
         return [
             `Socket 连接被拒绝: ${socketPath}`,
-            'native host 可能已退出。',
+            'native host 自动恢复失败。',
             '请确认 Chrome 浏览器正在运行，可尝试在 chrome://extensions 重新加载插件。',
             '',
             installHint,

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')
@@ -569,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.14.0",
+  "version": "2.15.1",
   "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.14.0",
-    "@mearl/provider": "2.14.0"
+    "@mearl/cloud-types": "2.15.1",
+    "@mearl/provider": "2.15.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",