@mearl/client 2.19.3 → 2.20.1

package/dist/generated-browser-action-protocol.js

@@ -72,6 +72,7 @@ export const TAB_ID_REQUIRED_ACTIONS = [
     'page_wait',
     'page_navigate',
     'page_upload',
+    'page_download',
     'page_frames',
     'set_device_emulation',
     'set_app_profile',
@@ -128,6 +129,8 @@ export const BROWSER_ACTIONS = {
     browser_list: true,
     browser_select_browser: true,
     browser_release: true,
+    browser_control: true,
+    page_download: true,
     browser_launch: true,
     browser_close: true,
     page_screenshot: true,
@@ -170,6 +173,8 @@ export const BROWSER_COMMAND_ACTIONS = {
     send_mtop_request: true,
     browser_list: true,
     browser_release: true,
+    browser_control: true,
+    page_download: true,
     browser_launch: true,
     browser_close: true,
     page_screenshot: true,
@@ -237,6 +242,10 @@ export const EXTENSION_BROWSER_ACTIONS = {
     request_domain_permission: true,
     run_actions: true,
 };
+export const BROWSER_CAPABILITY_ACTIONS = {
+    ...EXTENSION_BROWSER_ACTIONS,
+    page_download: true,
+};
 export function isBrowserAction(value) {
     return typeof value === 'string' && Object.hasOwn(BROWSER_ACTIONS, value);
 }
@@ -244,7 +253,7 @@ export function isBrowserCommandAction(value) {
     return typeof value === 'string' && Object.hasOwn(BROWSER_COMMAND_ACTIONS, value);
 }
 export function isBrowserCapabilityAction(value) {
-    return isExtensionBrowserAction(value);
+    return typeof value === 'string' && Object.hasOwn(BROWSER_CAPABILITY_ACTIONS, value);
 }
 export function isExtensionBrowserAction(value) {
     return typeof value === 'string' && Object.hasOwn(EXTENSION_BROWSER_ACTIONS, value);

package/dist/index.d.ts

@@ -7,7 +7,7 @@
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
 export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugin.js';
-export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
@@ -24,6 +24,7 @@ export declare function sendMtopRequest(params: Protocol.SendMtopRequestParams,
 export declare function browserList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_list'>>;
 export declare function selectBrowser(params?: Protocol.SelectBrowserParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_select_browser'>>;
 export declare function browserRelease(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_release'>>;
+export declare function browserRelease(params: Protocol.BrowserReleaseParams, options: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_release'>>;
 export declare function browserLaunch(params: Protocol.BrowserLaunchParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_launch'>>;
 export declare function browserClose(params: Protocol.BrowserCloseParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_close'>>;
 export declare function setRule(params: Protocol.SetRuleParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_rule'>>;
@@ -52,3 +53,11 @@ export declare function setTimezone(params: Protocol.SetTimezoneParams, options?
 export declare function getCookie(params: Protocol.GetCookieParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_cookie'>>;
 export declare function setCookie(params: Protocol.SetCookieParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_cookie'>>;
 export declare function runActions(params: Protocol.RunActionsParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'run_actions'>>;
+export declare function browserControl(params: Protocol.BrowserControlParams, options?: UnifiedInvokeOptions): Promise<any>;
+export declare function pageDownload(params: Protocol.PageDownloadParams, options?: UnifiedInvokeOptions): Promise<any>;
+export declare function saveArtifact(artifact: Protocol.BrowserArtifact & {
+    browserId?: string;
+}, outputPath: string, options?: UnifiedInvokeOptions): Promise<{
+    outputPath: string;
+    bytes: number;
+}>;

package/dist/index.js

@@ -5,7 +5,7 @@
  * then routes actions using the global browser ids returned by browser_list.
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
-export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 import { invoke } from './unified.js';
 export function tabCheckpoint(params, options) {
     return invoke('tab_checkpoint', params, options);
@@ -41,8 +41,10 @@ export function browserList(options) {
 export function selectBrowser(params = {}, options) {
     return invoke('browser_select_browser', params, options);
 }
-export function browserRelease(options) {
-    return invoke('browser_release', {}, options);
+export function browserRelease(paramsOrOptions = {}, options) {
+    return options
+        ? invoke('browser_release', paramsOrOptions, options)
+        : invoke('browser_release', {}, paramsOrOptions);
 }
 export function browserLaunch(params, options) {
     return invoke('browser_launch', params, options);
@@ -128,3 +130,13 @@ export function setCookie(params, options) {
 export function runActions(params, options) {
     return invoke('run_actions', params, options);
 }
+export function browserControl(params, options) {
+    return invoke('browser_control', params, options);
+}
+export function pageDownload(params, options) {
+    return invoke('page_download', params, options);
+}
+export async function saveArtifact(artifact, outputPath, options = {}) {
+    const { exportArtifact } = await import('./artifacts.js');
+    return exportArtifact({ invoke }, artifact, outputPath, options);
+}

package/dist/pluginPageBundle.js

@@ -32,6 +32,40 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   let resolveReady;
   const ready = new Promise(resolve => { resolveReady = resolve; });
 
+  let pageModalOpen = null;
+  let modalRestoreFrame = null;
+  const syncPageModal = () => {
+    if (!port) return;
+    const open = Boolean(document.querySelector?.('dialog:modal'));
+    if (open && modalRestoreFrame !== null) {
+      cancelAnimationFrame(modalRestoreFrame);
+      modalRestoreFrame = null;
+    }
+    if (open === pageModalOpen) return;
+    if (!open && pageModalOpen === true) {
+      if (modalRestoreFrame !== null) return;
+      // Closing a dialog restores focus and can scroll the anchors before the next paint.
+      modalRestoreFrame = requestAnimationFrame(() => {
+        modalRestoreFrame = null;
+        if (document.querySelector?.('dialog:modal')) return;
+        const positions = [];
+        for (const { presentation } of anchoredAgentPanels.values()) {
+          if (!presentation.element.isConnected) continue;
+          const rect = presentation.element.getBoundingClientRect();
+          if (![rect.top, rect.left, rect.width, rect.height].every(Number.isFinite)) continue;
+          const bounds = { top: rect.top, left: rect.left, width: rect.width, height: rect.height };
+          presentation.bounds = bounds;
+          positions.push({ key: presentation.key, bounds });
+        }
+        pageModalOpen = false;
+        port.postMessage({ type: 'page-modal', open: false, positions });
+      });
+      return;
+    }
+    pageModalOpen = open;
+    port.postMessage({ type: 'page-modal', open });
+  };
+
   const requestHost = async (type, payload = {}) => {
     await ready;
     const requestId = String(++requestSequence);
@@ -172,36 +206,41 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     return context === undefined ? null : context.trim();
   };
 
-  const inlineAgentPanels = new Map();
+  const anchoredAgentPanels = new Map();
 
-  const stopInlineAgentPanelTracking = key => {
+  const stopAgentAnchorTracking = key => {
     if (key) {
-      inlineAgentPanels.get(key)?.cleanup();
-      inlineAgentPanels.delete(key);
+      anchoredAgentPanels.get(key)?.cleanup();
+      anchoredAgentPanels.delete(key);
       return;
     }
-    for (const tracked of inlineAgentPanels.values()) tracked.cleanup();
-    inlineAgentPanels.clear();
+    for (const tracked of anchoredAgentPanels.values()) tracked.cleanup();
+    anchoredAgentPanels.clear();
   };
 
-  const inlineAgentPanelAnchor = (options, key) => {
+  const agentPanelAnchor = (options, key, layout) => {
     const anchor = options.anchor;
     if (!(anchor instanceof Element)) {
-      throw new Error('Inline Agent panel anchor must be an element');
+      throw new Error('Agent panel anchor must be an element');
     }
     const rect = anchor.getBoundingClientRect();
     if (![rect.top, rect.left, rect.width, rect.height].every(Number.isFinite)) {
-      throw new Error('Inline Agent panel anchor returned invalid bounds');
+      throw new Error('Agent panel anchor returned invalid bounds');
     }
     return {
       element: anchor,
       key,
+      layout,
       bounds: { top: rect.top, left: rect.left, width: rect.width, height: rect.height },
     };
   };
 
-  const trackInlineAgentPanel = presentation => {
-    stopInlineAgentPanelTracking(presentation.key);
+  const trackAgentAnchor = presentation => {
+    if (presentation.layout === 'workspace' || [...anchoredAgentPanels.values()].some(item => item.presentation.layout === 'workspace')) {
+      stopAgentAnchorTracking();
+    } else {
+      stopAgentAnchorTracking(presentation.key);
+    }
     let frame = null;
     const update = () => {
       frame = null;
@@ -247,7 +286,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
       window.removeEventListener('resize', schedule);
       document.removeEventListener('scroll', schedule, true);
     };
-    inlineAgentPanels.set(presentation.key, { presentation, cleanup });
+    anchoredAgentPanels.set(presentation.key, { presentation, cleanup });
   };
 
   const scrollInlineAgentPage = (presentation, deltaX, deltaY) => {
@@ -277,8 +316,11 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   };
 
   const agentPanelPresentation = (options, layout, key) => {
-    if (layout !== 'inline') return null;
-    return inlineAgentPanelAnchor(options, key);
+    if (layout === 'inline') return agentPanelAnchor(options, key, layout);
+    if (layout === 'workspace' && options.anchor !== undefined) {
+      return agentPanelAnchor(options, key || 'toolbox-workspace', layout);
+    }
+    return null;
   };
 
   const setAgentPanelVisible = async (visible, options = {}) => {
@@ -298,16 +340,16 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     });
     if (presentation) {
       await ready;
-      trackInlineAgentPanel(presentation);
+      trackAgentAnchor(presentation);
     } else if (!visible && key) {
-      stopInlineAgentPanelTracking(key);
+      stopAgentAnchorTracking(key);
     } else {
-      stopInlineAgentPanelTracking();
+      stopAgentAnchorTracking();
     }
     try {
       await request;
     } catch (error) {
-      if (presentation) stopInlineAgentPanelTracking(presentation.key);
+      if (presentation) stopAgentAnchorTracking(presentation.key);
       throw error;
     }
   };
@@ -375,14 +417,14 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     });
     if (presentation) {
       await ready;
-      trackInlineAgentPanel(presentation);
+      trackAgentAnchor(presentation);
     } else {
-      stopInlineAgentPanelTracking();
+      stopAgentAnchorTracking();
     }
     try {
       await request;
     } catch (error) {
-      if (presentation) stopInlineAgentPanelTracking(presentation.key);
+      if (presentation) stopAgentAnchorTracking(presentation.key);
       throw error;
     }
   };
@@ -446,14 +488,14 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
       if (
         response?.type === 'agent-panel-wheel' &&
         typeof response.key === 'string' &&
-        inlineAgentPanels.has(response.key) &&
+        anchoredAgentPanels.has(response.key) &&
         typeof response.deltaX === 'number' &&
         Number.isFinite(response.deltaX) &&
         typeof response.deltaY === 'number' &&
         Number.isFinite(response.deltaY)
       ) {
         scrollInlineAgentPage(
-          inlineAgentPanels.get(response.key).presentation,
+          anchoredAgentPanels.get(response.key).presentation,
           response.deltaX,
           response.deltaY,
         );
@@ -469,6 +511,19 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     port.start();
     resolveReady(context);
     port.postMessage({ type: 'ready' });
+    // Dialogs in the sandbox cannot cover Agent overlays in the parent document.
+    syncPageModal();
+    const modalObserver = typeof MutationObserver === 'function'
+      ? new MutationObserver(syncPageModal)
+      : null;
+    modalObserver?.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['open'],
+      childList: true,
+      subtree: true,
+    });
+    document.addEventListener('toggle', syncPageModal, true);
+    document.addEventListener('close', syncPageModal, true);
   };
   window.addEventListener('message', connect);
   window.parent.postMessage({ type: 'mearl-plugin-ready' }, '*');

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
@@ -129,6 +130,17 @@ function isOrdinaryLocalBrowser(browser) {
         (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') {
@@ -328,6 +340,7 @@ 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, transport, undefined, controlSource).then(result => decorateBrowserListResult(transport === 'cdp' ? cdpOnlyBrowserList(result) : result));
     }
@@ -413,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)) {
@@ -439,7 +453,7 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     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)) {
@@ -486,7 +500,7 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
                     !(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);
@@ -497,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) {
@@ -536,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 => {

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;

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);
@@ -526,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)
@@ -537,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) {