@mearl/client 2.19.2 → 2.20.0

package/dist/unified.js

@@ -1,3 +1,4 @@
+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';
@@ -48,6 +49,16 @@ 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);
@@ -127,6 +138,67 @@ export class UnifiedClient {
         }, options);
     }
     async invoke(action, data = {}, options = {}) {
+        if (options.session && options.session !== 'new') {
+            const session = decodeControlSessionId(options.session);
+            const selected = decodeBrowserTarget(options.browser);
+            const pinned = decodeBrowserTarget(session.browser);
+            if (options.browser &&
+                (!selected ||
+                    selected.browser !== pinned?.browser ||
+                    selected.connector !== pinned?.connector)) {
+                throw new Error('The selected browser does not match the control session');
+            }
+            if (options.transport && session.transport !== options.transport)
+                throw new Error('A control session cannot change transport');
+            options = {
+                ...options,
+                browser: session.browser,
+                controlSessionId: session.id,
+                ...(session.transport === 'cdp' && !pinned?.connector ? { transport: 'cdp' } : {}),
+            };
+        }
+        else if (options.session === 'new') {
+            if (!['tab_open', 'page_snapshot', 'page_screenshot'].includes(action))
+                throw new Error('--session new requires tab_open, page_snapshot or page_screenshot');
+            options = { ...options, controlSessionId: 'new' };
+        }
+        if (action === 'page_upload' &&
+            data.files !== undefined &&
+            (!Array.isArray(data.files) ||
+                !data.files.length ||
+                data.files.some((file) => !file || (typeof file.filePath === 'string') === (typeof file.artifactId === 'string'))))
+            throw new Error('files requires exactly one filePath or artifactId per entry');
+        if (action === 'page_upload' &&
+            Array.isArray(data.files) &&
+            data.files.some((file) => file.filePath)) {
+            if (data.filePaths)
+                throw new Error('Use files or filePaths, not both');
+            const staged = [];
+            const temporary = [];
+            try {
+                for (const file of data.files) {
+                    if (file.filePath) {
+                        const uploaded = await stageFile(this, file.filePath, options);
+                        options = uploaded.options;
+                        temporary.push(uploaded.artifactId);
+                        staged.push({ artifactId: uploaded.artifactId });
+                    }
+                    else
+                        staged.push(file);
+                }
+                return await this.invokeRouted(action, { ...data, files: staged }, options);
+            }
+            finally {
+                for (const id of temporary)
+                    await this.invoke('__artifact_remove', { artifactId: id }, options).catch(() => { });
+            }
+        }
+        return this.invokeRouted(action, data, options);
+    }
+    saveArtifact(artifact, outputPath, options = {}) {
+        return exportArtifact(this, artifact, outputPath, options);
+    }
+    async invokeRouted(action, data = {}, options = {}) {
         validateRequiredActionTabId(action, data);
         const timeoutSec = options.timeoutSec ?? resolveActionTimeoutSec(action, data, this.options.requestTimeoutSec);
         if (action === 'connector_list')
@@ -162,7 +234,7 @@ export class UnifiedClient {
             if (options.connector) {
                 throw new Error('A local browser cannot be used together with --connector.');
             }
-            return this.invokeLocal(action, requestData, timeoutSec, target.browser);
+            return this.invokeLocal(action, requestData, timeoutSec, target.browser, undefined, options.controlSessionId);
         }
         if (connector) {
             const selected = target?.connector && !options.connector && !this.defaultConnector
@@ -171,10 +243,10 @@ export class UnifiedClient {
             if (target?.connector && selected.connectorId !== target.connector) {
                 throw new Error('The selected browser belongs to a different cloud connector.');
             }
-            return this.invokeRemote(action, requestData, timeoutSec, browser, selected);
+            return this.invokeRemote(action, requestData, timeoutSec, browser, selected, options.controlSessionId);
         }
         if (!this.options.serverUrl) {
-            return this.invokeLocal(action, requestData, timeoutSec, options.browser ?? this.defaultBrowser);
+            return this.invokeLocal(action, requestData, timeoutSec, options.browser ?? this.defaultBrowser, undefined, options.controlSessionId);
         }
         const selector = options.browser ??
             this.defaultBrowser ??
@@ -204,7 +276,7 @@ export class UnifiedClient {
         }
         const browser = optionTarget?.browser ?? defaultTarget?.browser ?? options.browser ?? this.defaultBrowser;
         const requestData = closeTarget ? { ...data, browser: closeTarget.browser } : data;
-        return this.invokeLocal(action, requestData, timeoutSec, browser, options.transport);
+        return this.invokeLocal(action, requestData, timeoutSec, browser, options.transport, options.controlSessionId);
     }
     async invokeLaunchWithoutControlBrowser(data, timeoutSec) {
         const local = await this.tryLocalBrowserList(timeoutSec);
@@ -410,17 +482,18 @@ export class UnifiedClient {
             ...(warnings.length > 0 ? { warnings } : {}),
         });
     }
-    async invokeLocal(action, data, timeoutSec, browser, transport) {
+    async invokeLocal(action, data, timeoutSec, browser, transport, controlSessionId) {
         const result = await invokeLocalBrowser(action, data, {
             timeoutSec,
             ...(browser ? { browser } : {}),
             ...(transport ? { transport } : {}),
             controlSource: 'local',
+            ...(controlSessionId ? { controlSessionId } : {}),
         });
         return this.decorateActionResult(action, result, { kind: 'local' });
     }
-    async invokeRemote(action, data, timeoutSec, browser, connector) {
-        const result = await this.requestRemote(action, data, timeoutSec, browser, connector.connectorId);
+    async invokeRemote(action, data, timeoutSec, browser, connector, controlSessionId) {
+        const result = await this.requestRemote(action, data, timeoutSec, browser, connector.connectorId, controlSessionId);
         return this.decorateActionResult(action, result, {
             kind: 'remote',
             connectorId: connector.connectorId,
@@ -428,6 +501,40 @@ export class UnifiedClient {
         });
     }
     decorateActionResult(action, result, source) {
+        if (result?.session?.sessionId && !result.session.sessionId.startsWith('mearl-session:')) {
+            const browserId = encodeBrowserTarget({
+                browser: result.session.browserId,
+                ...(source.connectorId ? { connector: source.connectorId } : {}),
+            });
+            result = {
+                ...result,
+                session: {
+                    ...result.session,
+                    browserId,
+                    sessionId: `mearl-session:${encodeURIComponent(browserId)}:${result.session.sessionId}:${result.session.transport}`,
+                },
+            };
+        }
+        if (typeof result?.browserId === 'string' && action.startsWith('__artifact_')) {
+            return {
+                ...result,
+                browserId: encodeBrowserTarget({
+                    browser: result.browserId,
+                    ...(source.connectorId ? { connector: source.connectorId } : {}),
+                }),
+            };
+        }
+        if (result?.download?.browserId)
+            result = {
+                ...result,
+                download: {
+                    ...result.download,
+                    browserId: encodeBrowserTarget({
+                        browser: result.download.browserId,
+                        ...(source.connectorId ? { connector: source.connectorId } : {}),
+                    }),
+                },
+            };
         if (action !== 'browser_launch' || typeof result?.browserId !== 'string')
             return result;
         return decorateBrowser(result, source);
@@ -449,7 +556,8 @@ export class UnifiedClient {
     connect() {
         return new Promise((resolve, reject) => {
             if (!this.options.serverUrl) {
-                reject(new Error('Cloud server URL is required. Start cloud-server, pass --server, or set MEARL_SERVER_URL.'));
+                reject(new Error('Cloud server URL is required. Run mearl-cloud-server status on the Agent machine. ' +
+                    'Resolution order: --server > MEARL_SERVER_URL > ~/.mearl/cloud-server.json.'));
                 return;
             }
             const ws = new WebSocket(this.options.serverUrl);
@@ -525,7 +633,7 @@ export class UnifiedClient {
         else
             pending.reject(new Error(response.error || 'Unknown error from cloud-server'));
     }
-    async requestRemote(action, data, timeoutSec, browser, connector) {
+    async requestRemote(action, data, timeoutSec, browser, connector, controlSessionId) {
         await this.ensureConnected();
         const ws = this.ws;
         if (!ws || ws.readyState !== WebSocket.OPEN)
@@ -536,6 +644,8 @@ export class UnifiedClient {
             message.browser = browser;
         if (connector)
             message.connector = connector;
+        if (controlSessionId)
+            message.controlSessionId = controlSessionId;
         const serialized = `${JSON.stringify(message)}\n`;
         const bytes = Buffer.byteLength(serialized, 'utf8');
         if (bytes > MAX_BUFFER_SIZE) {

package/package.json

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