@mearl/client 2.20.1 → 2.20.3

package/dist/unified.js

@@ -1,9 +1,10 @@
+import { invokePageEvalWithArgs } from './pageEvalArguments.js';
 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 { invoke as invokeLocalBrowser } from './socket.js';
+import { invoke as invokeLocalBrowser, resolveLocalActionTarget } from './socket.js';
 import { loadCloudServerConfig, loadLocalConnectorId } from './unifiedConfig.js';
 const RESPONSE_GRACE_MS = 1_000;
 const GLOBAL_BROWSER_PREFIX = 'mearl:';
@@ -49,16 +50,6 @@ export function normalizeBrowserSelector(selector) {
     const decodedTarget = decodeBrowserTarget(selector);
     return (decodedTarget ? encodeBrowserTarget(decodedTarget) : selector.trim()).toLowerCase();
 }
-export function decodeControlSessionId(id) {
-    const match = /^mearl-session:([^:]+):(cs_[a-f0-9-]+):(extension|cdp|provider)$/.exec(id);
-    if (!match)
-        throw new Error('Invalid session id; reuse session.sessionId from the first response');
-    return {
-        browser: decodeURIComponent(match[1]),
-        id: match[2],
-        transport: match[3],
-    };
-}
 function decorateBrowser(browser, source) {
     const safeBrowser = omitTransientBrowserSecrets(browser);
     const originalBrowserId = String(browser.browserId);
@@ -102,6 +93,7 @@ function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 export class UnifiedClient {
+    controlSessions = new Map();
     options;
     defaultBrowser;
     defaultConnector;
@@ -139,7 +131,7 @@ export class UnifiedClient {
     }
     async invoke(action, data = {}, options = {}) {
         if (options.session && options.session !== 'new') {
-            const session = decodeControlSessionId(options.session);
+            const session = await this.resolveControlSession(options.session, options);
             const selected = decodeBrowserTarget(options.browser);
             const pinned = decodeBrowserTarget(session.browser);
             if (options.browser &&
@@ -162,6 +154,25 @@ export class UnifiedClient {
                 throw new Error('--session new requires tab_open, page_snapshot or page_screenshot');
             options = { ...options, controlSessionId: 'new' };
         }
+        if (action === 'page_eval' && data.args !== undefined) {
+            let pinnedOptions = {
+                ...options,
+                ...(options.browser || !this.defaultBrowser ? {} : { browser: this.defaultBrowser }),
+                ...(options.connector ||
+                    !this.defaultConnector ||
+                    decodeBrowserTarget(options.browser ?? this.defaultBrowser)
+                    ? {}
+                    : { connector: this.defaultConnector }),
+            };
+            let targetPinned = false;
+            return invokePageEvalWithArgs(async (request, transfer) => {
+                if (transfer && !targetPinned) {
+                    pinnedOptions = await this.pinPageEvalTarget(pinnedOptions, request);
+                    targetPinned = true;
+                }
+                return this.invokeRouted(action, request, pinnedOptions);
+            }, data);
+        }
         if (action === 'page_upload' &&
             data.files !== undefined &&
             (!Array.isArray(data.files) ||
@@ -198,9 +209,63 @@ export class UnifiedClient {
     saveArtifact(artifact, outputPath, options = {}) {
         return exportArtifact(this, artifact, outputPath, options);
     }
+    async pinPageEvalTarget(options, data) {
+        const target = decodeBrowserTarget(options.browser);
+        if (target && !options.connector)
+            return options;
+        const local = options.local ||
+            options.transport === 'cdp' ||
+            (!this.options.serverUrl && !options.connector);
+        if (local) {
+            const resolved = resolveLocalActionTarget('page_eval', data, {
+                browser: options.browser,
+                transport: options.transport,
+            });
+            if (resolved?.socketPath)
+                return { ...options, socketPath: resolved.socketPath };
+            if (resolved?.browser)
+                return { ...options, browser: encodeBrowserTarget({ browser: resolved.browser }) };
+        }
+        if (options.connector && !options.browser) {
+            const timeoutSec = options.timeoutSec ?? this.options.requestTimeoutSec;
+            const connector = await this.resolveConnector(options.connector, timeoutSec);
+            const resolved = await this.requestRemote('__resolve_action_target', { action: 'page_eval', data }, timeoutSec, undefined, connector.connectorId);
+            if (!resolved?.browser)
+                throw new Error('Cannot pin the connector browser for large page_eval arguments. Pass --browser <global-id>.');
+            const pinned = {
+                ...options,
+                browser: encodeBrowserTarget({
+                    browser: resolved.browser,
+                    connector: connector.connectorId,
+                }),
+            };
+            delete pinned.connector;
+            return pinned;
+        }
+        const listing = (await this.invokeRouted('browser_list', {}, options));
+        const connected = listing.browsers.filter(browser => browser.status === 'connected' && (!local || browser.transport !== 'provider'));
+        const implicitHost = options.local || options.transport === 'cdp' || options.connector || !this.options.serverUrl;
+        const automatic = connected.find(browser => browser.browserId === listing.defaultBrowserId) ??
+            (implicitHost || connected.length === 1 ? connected[0] : undefined);
+        const candidates = options.browser
+            ? findBrowsers(listing.browsers, options.browser)
+            : automatic
+                ? [automatic]
+                : [];
+        if (candidates.length !== 1)
+            throw new Error('Large page_eval arguments require a unique connected browser. Pass --browser <global-id>.');
+        const browser = candidates[0];
+        const pinned = { ...options, browser: browser.browserId };
+        delete pinned.connector;
+        if (browser.transport === 'cdp' && !decodeBrowserTarget(browser.browserId)?.connector)
+            pinned.transport = 'cdp';
+        return pinned;
+    }
     async invokeRouted(action, data = {}, options = {}) {
         validateRequiredActionTabId(action, data);
         const timeoutSec = options.timeoutSec ?? resolveActionTimeoutSec(action, data, this.options.requestTimeoutSec);
+        if (options.socketPath)
+            return this.invokeLocal(action, data, timeoutSec, undefined, options.transport, options.controlSessionId, options.socketPath);
         if (action === 'connector_list')
             return this.listConnectors(timeoutSec);
         if (action === 'browser_list') {
@@ -482,11 +547,12 @@ export class UnifiedClient {
             ...(warnings.length > 0 ? { warnings } : {}),
         });
     }
-    async invokeLocal(action, data, timeoutSec, browser, transport, controlSessionId) {
+    async invokeLocal(action, data, timeoutSec, browser, transport, controlSessionId, socketPath) {
         const result = await invokeLocalBrowser(action, data, {
             timeoutSec,
             ...(browser ? { browser } : {}),
             ...(transport ? { transport } : {}),
+            ...(socketPath ? { socketPath } : {}),
             controlSource: 'local',
             ...(controlSessionId ? { controlSessionId } : {}),
         });
@@ -501,17 +567,23 @@ export class UnifiedClient {
         });
     }
     decorateActionResult(action, result, source) {
-        if (result?.session?.sessionId && !result.session.sessionId.startsWith('mearl-session:')) {
+        if (result?.session?.sessionId) {
             const browserId = encodeBrowserTarget({
                 browser: result.session.browserId,
                 ...(source.connectorId ? { connector: source.connectorId } : {}),
             });
+            if (action !== '__control_session_resolve') {
+                this.controlSessions.set(result.session.sessionId, {
+                    browser: browserId,
+                    id: result.session.sessionId,
+                    transport: result.session.transport,
+                });
+            }
             result = {
                 ...result,
                 session: {
                     ...result.session,
                     browserId,
-                    sessionId: `mearl-session:${encodeURIComponent(browserId)}:${result.session.sessionId}:${result.session.transport}`,
                 },
             };
         }
@@ -539,6 +611,57 @@ export class UnifiedClient {
             return result;
         return decorateBrowser(result, source);
     }
+    async resolveControlSession(id, options) {
+        if (!/^s_[A-Za-z0-9_-]{8}$/.test(id))
+            throw new Error('Invalid session id; reuse session.sessionId from the first response');
+        const cached = this.controlSessions.get(id);
+        if (cached)
+            return cached;
+        const timeoutSec = options.timeoutSec ?? 15;
+        const localLookup = this.invokeLocal('__control_session_resolve', { sessionId: id }, timeoutSec, undefined);
+        const discover = async () => {
+            const { connectors } = await this.listConnectors(timeoutSec);
+            return Promise.allSettled(connectors.map(connector => this.invokeRemote('__control_session_resolve', { sessionId: id }, timeoutSec, undefined, connector)));
+        };
+        const [local, remote] = await Promise.allSettled([
+            localLookup,
+            this.options.serverUrl && !options.local && !options.transport
+                ? discover()
+                : Promise.resolve([]),
+        ]);
+        const localSession = local.status === 'fulfilled' ? local.value?.session : undefined;
+        const localTarget = decodeBrowserTarget(localSession?.browserId);
+        const localConnectorId = localSession?.sessionId === id ? loadLocalConnectorId() : null;
+        const results = [local, ...(remote.status === 'fulfilled' ? remote.value : [remote])].filter(result => {
+            if (result === local || result.status === 'rejected')
+                return true;
+            const session = result.value?.session;
+            const target = decodeBrowserTarget(session?.browserId);
+            // The same host can be reached over both its local socket and its cloud connector.
+            return !(localConnectorId &&
+                target?.connector === localConnectorId &&
+                target.browser === localTarget?.browser &&
+                session?.sessionId === id &&
+                session.transport === localSession.transport);
+        });
+        const sessions = results.flatMap(result => result.status === 'fulfilled' && result.value?.session?.sessionId === id
+            ? [result.value.session]
+            : []);
+        const ambiguous = results.some(result => result.status === 'rejected' &&
+            errorMessage(result.reason).startsWith('CONTROL_SESSION_AMBIGUOUS'));
+        if (sessions.length > 1 || ambiguous) {
+            this.controlSessions.delete(id);
+            throw new Error('CONTROL_SESSION_AMBIGUOUS: multiple hosts own this id');
+        }
+        const session = sessions[0];
+        if (!session) {
+            const errors = results.flatMap(result => result.status === 'rejected' ? [errorMessage(result.reason)] : []);
+            throw new Error(`CONTROL_SESSION_NOT_FOUND: ${id}${errors.length ? ` (${errors.join('; ')})` : ''}`);
+        }
+        const target = { browser: session.browserId, id, transport: session.transport };
+        this.controlSessions.set(id, target);
+        return target;
+    }
     async ensureConnected() {
         if (this.ws?.readyState === WebSocket.OPEN)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.20.1",
+  "version": "2.20.3",
   "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.20.1",
-    "@mearl/provider": "2.20.1"
+    "@mearl/cloud-types": "2.20.3",
+    "@mearl/provider": "2.20.3"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",