@mearl/client 2.20.2 → 2.20.3

package/README.md

@@ -76,6 +76,8 @@ mearl browser_release
 
 多步骤任务首次 `tab_open` 或 `page_snapshot` 使用 `--session new`，响应在原结果旁附带 `session`，后续用其 `sessionId` 自动路由，无需额外创建/查询 action。Session 绑定一个浏览器与传输；页面首次使用自动关联，复用页面与新建页面分别记录。同一页面只允许一个会话控制，旧调用不能绕过占用；Session 不隔离 Cookie 或存储。
 
+`sessionId` 是形如 `s_aB3d_E-f` 的短 ID。会话及其浏览器、传输映射保存在常驻控制宿主的内存中；新的 CLI 进程会内部查询本机和远端宿主完成路由，无需调用方保存或传递路由信息，也不写入会话映射文件。控制宿主退出后会话失效。
+
 旧调用不必传 `--session`，现有动作、`run_actions` 批次和上传 `filePaths` 参数继续可用。活动会话存在时，旧调用不能操作其占用页面、执行浏览器级释放/关闭或修改共享设置；旧批次中的开页/关闭浏览器需改为独立调用。CDP Mock 按标签页生效，跨页使用同一 Mock 时需分别配置。
 
 ```bash
@@ -271,7 +273,7 @@ export default function register(app) {
 `app.command(signature, handler, description?, examples?)` 注册 CLI、SDK 和 Agent 可调用的业务命令。
 `app.toolboxCommand(signature, handler, description?, examples?)` 注册仅供工具页面调用的命令，参数和 handler 契约相同；
 它不出现在 CLI 帮助中，CLI（包括 JSON payload）、SDK、MCP 及插件间的 `app.invoke` 都不能调用。
-工具页面通过 `window.mearl.invoke` 或 `window.mearl.start` 执行；两类命令都必须显式列在 `toolbox.page.commands` 中才能供页面调用。
+工具页面通过 `window.mearl.invoke(command, input)` 或 `window.mearl.invoke('host.operation.start', { command, input })` 执行；两类命令都必须显式列在 `toolbox.page.commands` 中才能供页面调用。
 注册的 `toolboxCommand` 若没有列入该白名单，插件加载会失败。分块上传、分块读取和页面临时资源释放适合使用它；
 对 Agent 有独立业务价值的查询、导入、压缩、比较等完整操作使用 `app.command`。
 Python 入口也支持 `app.toolboxCommand(...)`，包括 `@app.toolboxCommand(..., description="...")` 装饰器。

package/dist/commands.d.ts

@@ -722,7 +722,19 @@ export declare const COMMANDS: readonly [{
         readonly name: "expression";
         readonly type: "string";
         readonly required: true;
-        readonly description: "要执行的 JS 表达式";
+        readonly description: "要执行的 JS 表达式；传 args 时须求值为函数";
+    }, {
+        readonly name: "args";
+        readonly type: "unknown[]";
+        readonly description: "传给页面函数的 JSON 参数；SDK/CLI 自动处理大参数分块，保持指定执行环境";
+    }, {
+        readonly name: "executionWorld";
+        readonly type: "string";
+        readonly description: "main（默认）读取网页 JS；isolated 使用命名隔离环境，扩展连接无需 debugger";
+    }, {
+        readonly name: "worldId";
+        readonly type: "string";
+        readonly description: "isolated 必填，小写字母开头，允许数字和连字符，最长 64 字符";
     }, {
         readonly name: "awaitPromise";
         readonly type: "boolean";
@@ -953,6 +965,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "quality";
         readonly type: "number";
         readonly description: "JPEG 压缩质量（0-100），默认 80";
+    }, {
+        readonly name: "captureMode";
+        readonly type: "\"cdp\" | \"visible\"";
+        readonly description: "默认 cdp；visible 使用活动标签页截图，普通网页无需 debugger；设备模拟复用模拟会话并截取业务视口，不支持 selector";
     }, {
         readonly name: "tabId";
         readonly type: "number";
@@ -960,7 +976,7 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly notes: readonly ["使用 --output <path> 保存图片；省略时 stdout 返回含 base64 data 的 JSON，避免直接将其加载为文本。"];
-    readonly result: readonly ["meta 包含 format、width、height、size、url、title；宽高为物理像素（CSS 尺寸 × DPR）。"];
+    readonly result: readonly ["meta 包含 format、width、height、size、url、title；宽高为实际截图的物理像素。"];
     readonly examples: ["page_screenshot --payload '{\"tabId\":12345}' --output ./screenshot.png", "page_screenshot --payload '{\"tabId\":12345,\"selector\":\".product-card\"}' --output ./card.png"];
 }, {
     readonly name: "set_device_emulation";

package/dist/commands.js

@@ -787,7 +787,27 @@ export const COMMANDS = [
         name: 'page_eval',
         description: '在页面上下文中执行任意 JavaScript 表达式',
         params: [
-            { name: 'expression', type: 'string', required: true, description: '要执行的 JS 表达式' },
+            {
+                name: 'expression',
+                type: 'string',
+                required: true,
+                description: '要执行的 JS 表达式；传 args 时须求值为函数',
+            },
+            {
+                name: 'args',
+                type: 'unknown[]',
+                description: '传给页面函数的 JSON 参数；SDK/CLI 自动处理大参数分块，保持指定执行环境',
+            },
+            {
+                name: 'executionWorld',
+                type: 'string',
+                description: 'main（默认）读取网页 JS；isolated 使用命名隔离环境，扩展连接无需 debugger',
+            },
+            {
+                name: 'worldId',
+                type: 'string',
+                description: 'isolated 必填，小写字母开头，允许数字和连字符，最长 64 字符',
+            },
             {
                 name: 'awaitPromise',
                 type: 'boolean',
@@ -1049,14 +1069,17 @@ export const COMMANDS = [
             { name: 'selector', type: 'string', description: 'CSS 选择器，提供后只截取该元素区域' },
             { name: 'format', type: '"png" | "jpeg"', description: '图片格式，默认 png' },
             { name: 'quality', type: 'number', description: 'JPEG 压缩质量（0-100），默认 80' },
+            {
+                name: 'captureMode',
+                type: '"cdp" | "visible"',
+                description: '默认 cdp；visible 使用活动标签页截图，普通网页无需 debugger；设备模拟复用模拟会话并截取业务视口，不支持 selector',
+            },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
         notes: [
             '使用 --output <path> 保存图片；省略时 stdout 返回含 base64 data 的 JSON，避免直接将其加载为文本。',
         ],
-        result: [
-            'meta 包含 format、width、height、size、url、title；宽高为物理像素（CSS 尺寸 × DPR）。',
-        ],
+        result: ['meta 包含 format、width、height、size、url、title；宽高为实际截图的物理像素。'],
         examples: [
             `page_screenshot --payload '{"tabId":12345}' --output ./screenshot.png`,
             `page_screenshot --payload '{"tabId":12345,"selector":".product-card"}' --output ./card.png`,

package/dist/generated-browser-action-protocol.d.ts

@@ -437,6 +437,7 @@ export interface PageScreenshotParams {
     selector?: string;
     format?: 'png' | 'jpeg';
     quality?: number;
+    captureMode?: 'cdp' | 'visible';
 }
 export declare const BROWSER_DEVICE_PRESET_NAMES: readonly ["iphone-duo-folded", "iphone-duo-unfolded", "iphone-17-pro", "iphone-17e", "pixel-11", "ipad-mini-a17-pro", "galaxy-s26", "pura-x-max", "iphone-15-pro", "iphone-se", "pixel-8", "ipad-mini", "galaxy-s23"];
 export type BrowserDevicePresetName = (typeof BROWSER_DEVICE_PRESET_NAMES)[number];
@@ -615,11 +616,22 @@ export interface PageHoverParams {
 export interface PageEvalParams {
     tabId: number;
     expression: string;
+    /** When provided, expression must evaluate to a function called with these JSON arguments. */
+    args?: unknown[];
     frameId?: string;
     awaitPromise?: boolean;
-    observe?: PageObservationWaitOptions;
+    observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
+    executionWorld?: 'main' | 'isolated';
+    worldId?: string;
+}
+export declare function resolvePageEvalExpression(params: Pick<PageEvalParams, 'expression' | 'args'>): string;
+export interface PageUserScriptParams {
+    tabId: number;
+    worldId: string;
+    code: string;
 }
+export declare function validatePageUserScriptParams(params: PageUserScriptParams): void;
 export interface PageSnapshotQuery {
     text?: string;
     role?: string;

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

@@ -50,6 +50,26 @@ export const APP_PROFILE_NAMES = [
     'didi',
     'easybike',
 ];
+export function resolvePageEvalExpression(params) {
+    if (typeof params.expression !== 'string' || !params.expression.trim())
+        throw new Error('Invalid expression');
+    if (params.args === undefined)
+        return params.expression;
+    if (!Array.isArray(params.args))
+        throw new Error('page_eval args must be an array');
+    return `(${params.expression})(...JSON.parse(${JSON.stringify(JSON.stringify(params.args))}))`;
+}
+export function validatePageUserScriptParams(params) {
+    if (!Number.isSafeInteger(params?.tabId) || params.tabId < 0) {
+        throw new Error('Invalid target tab');
+    }
+    if (typeof params.worldId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(params.worldId)) {
+        throw new Error('Invalid user script worldId');
+    }
+    if (typeof params.code !== 'string' || !params.code.trim() || params.code.length > 256 * 1024) {
+        throw new Error('User script code must be non-empty and within 256 KiB characters');
+    }
+}
 export const TAB_ID_REQUIRED_ACTIONS = [
     'tab_checkpoint',
     'capture_checkpoint',

package/dist/pageEvalArguments.d.ts

@@ -0,0 +1,3 @@
+import { type PageEvalParams } from './generated-browser-action-protocol.js';
+/** Serialize page_eval arguments within transport limits while retaining the caller's execution world. */
+export declare function invokePageEvalWithArgs(invoke: (payload: Record<string, unknown>, transfer?: boolean) => Promise<any>, params: PageEvalParams): Promise<any>;

package/dist/pageEvalArguments.js

@@ -0,0 +1,47 @@
+import { randomUUID } from 'node:crypto';
+import { validatePageUserScriptParams, resolvePageEvalExpression, } from './generated-browser-action-protocol.js';
+const CHUNK_CHARACTERS = 48 * 1024;
+/** Serialize page_eval arguments within transport limits while retaining the caller's execution world. */
+export async function invokePageEvalWithArgs(invoke, params) {
+    if (!Number.isSafeInteger(params.tabId) || params.tabId < 0)
+        throw new Error('Invalid target tab');
+    resolvePageEvalExpression({ expression: params.expression, args: [] });
+    if (!Array.isArray(params.args))
+        throw new Error('page_eval args must be an array');
+    if (params.executionWorld !== undefined && !['main', 'isolated'].includes(params.executionWorld))
+        throw new Error('Invalid page executionWorld');
+    if (params.executionWorld === 'isolated')
+        validatePageUserScriptParams({
+            tabId: params.tabId,
+            worldId: params.worldId ?? '',
+            code: params.expression,
+        });
+    const args = JSON.stringify(params.args);
+    if (args.length > 64 * 1024 * 1024)
+        throw new Error('Page script arguments must fit within 64 MiB characters');
+    const { args: _args, ...request } = params;
+    const evaluate = async (expression, transfer = false) => {
+        const payload = {
+            ...request,
+            ...(transfer ? { observe: false, diagnostics: false } : {}),
+            expression,
+        };
+        const result = await (transfer ? invoke(payload, true) : invoke(payload));
+        if (transfer && result?.action?.success === false)
+            throw new Error(result.action.error || 'page_eval failed');
+        return result;
+    };
+    if (args.length + params.expression.length <= CHUNK_CHARACTERS) {
+        return evaluate(resolvePageEvalExpression(params));
+    }
+    const key = JSON.stringify('__mearlPageScriptTransfer_' + randomUUID());
+    try {
+        for (let offset = 0; offset < args.length; offset += CHUNK_CHARACTERS) {
+            await evaluate(`void (window[${key}] = (window[${key}] || '') + ${JSON.stringify(args.slice(offset, offset + CHUNK_CHARACTERS))})`, true);
+        }
+        return await evaluate(`(() => { const args = JSON.parse(window[${key}]); delete window[${key}]; return (${params.expression})(...args); })()`);
+    }
+    finally {
+        await evaluate(`delete window[${key}]`, true).catch(() => { });
+    }
+}

package/dist/plugin.d.ts

@@ -1,3 +1,4 @@
+export { invokePageEvalWithArgs } from './pageEvalArguments.js';
 import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
 import { type PluginToolboxContribution, type PluginRegistration } from './pluginRegistry.js';
 import type { UnifiedInvokeOptions } from './unified.js';

package/dist/plugin.js

@@ -1,3 +1,4 @@
+export { invokePageEvalWithArgs } from './pageEvalArguments.js';
 import { readFileSync } from 'node:fs';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';

package/dist/pluginPageBundle.js

@@ -29,6 +29,8 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   let port = null;
   let requestSequence = 0;
   const pending = new Map();
+  const pageEventListeners = new Map();
+  let subscriptionSequence = 0;
   let resolveReady;
   const ready = new Promise(resolve => { resolveReady = resolve; });
 
@@ -76,64 +78,25 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   };
 
   const invoke = async (command, input = {}) => {
-    if (typeof command !== 'string' || !/^[a-z][a-z0-9-]*$/.test(command)) {
-      throw new Error('Invalid plugin command');
-    }
+    if (typeof command !== 'string' || (!/^[a-z][a-z0-9-]*$/.test(command) && !/^host\.[a-z][a-zA-Z]*(?:\.[a-z][a-zA-Z]*)*$/.test(command))) throw new Error('Invalid command');
     if (!input || typeof input !== 'object' || Array.isArray(input)) {
       throw new Error('Plugin command input must be an object');
     }
     return requestHost('invoke', { command, input });
   };
 
-  const start = async (command, input = {}) => {
-    if (typeof command !== 'string' || !/^[a-z][a-z0-9-]*$/.test(command)) {
-      throw new Error('Invalid plugin command');
-    }
-    if (!input || typeof input !== 'object' || Array.isArray(input)) {
-      throw new Error('Plugin command input must be an object');
-    }
-    return requestHost('invoke-start', { command, input });
-  };
-
-  const operation = async operationId => {
-    if (typeof operationId !== 'string' || !/^[0-9a-f-]{36}$/i.test(operationId)) {
-      throw new Error('Invalid plugin operation id');
-    }
-    return requestHost('invoke-operation', { operationId });
-  };
-
-  const runningOperations = async () => requestHost('invoke-operations');
-  const readClipboard = async () => requestHost('clipboard-read');
-  const getActiveTab = async () => requestHost('active-tab');
-
-  const selectDirectory = async () => {
-    const path = await requestHost('select-directory');
-    if (path !== null && typeof path !== 'string') {
-      throw new Error('Directory selection returned an invalid path');
-    }
-    return path;
-  };
-
-  const copyText = async text => {
-    if (typeof text !== 'string' || text.length > 1000000) {
-      throw new Error('Clipboard text must be a string no longer than 1000000 characters');
-    }
-    await requestHost('clipboard-write', { text });
-  };
-
-  const copyImage = async data => {
-    if (typeof data !== 'string' || data.length > 16 * 1024 * 1024 ||
-        !/^data:image\/(png|jpeg|webp);base64,/.test(data)) {
-      throw new Error('Clipboard image must be a PNG, JPEG or WebP data URL within 16 MiB');
-    }
-    await requestHost('clipboard-image-write', { data });
-  };
-
-  const openExternalLink = async url => {
-    if (typeof url !== 'string' || !url || url.length > 8192) {
-      throw new Error('External link must be a non-empty URL no longer than 8192 characters');
-    }
-    await requestHost('open-external-link', { url });
+  const subscribe = async (source, target, listener) => {
+    if (source !== 'page' || !target || !Number.isSafeInteger(target.tabId) || target.tabId < 0 ||
+        typeof target.runtimeId !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(target.runtimeId) ||
+        typeof listener !== 'function') throw new Error('Invalid event subscription');
+    const subscriptionId = String(++subscriptionSequence);
+    pageEventListeners.set(subscriptionId, listener);
+    try { await requestHost('subscribe', { source, target, subscriptionId }); }
+    catch (error) { pageEventListeners.delete(subscriptionId); throw error; }
+    return () => {
+      if (!pageEventListeners.delete(subscriptionId)) return;
+      void requestHost('unsubscribe', { subscriptionId }).catch(() => {});
+    };
   };
 
   const handleExternalLinkClick = event => {
@@ -150,28 +113,11 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     }
     if (url.protocol !== 'http:' && url.protocol !== 'https:') return;
     event.preventDefault();
-    void openExternalLink(url.href).catch(error => {
+    void invoke('host.link.open', { url: url.href }).catch(error => {
       console.error('Failed to open external link', error);
     });
   };
 
-  const toast = async (message, options = {}) => {
-    if (typeof message !== 'string' || !message.trim() || message.length > 4000) {
-      throw new Error('Toast message must be a non-empty string no longer than 4000 characters');
-    }
-    if (!options || typeof options !== 'object' || Array.isArray(options)) {
-      throw new Error('Toast options must be an object');
-    }
-    const type = options.type ?? 'info';
-    const duration = options.duration ?? 3000;
-    if (!['success', 'error', 'info'].includes(type)) throw new Error('Invalid toast type');
-    if (!Number.isInteger(duration) || duration < 1000 || duration > 30000) {
-      throw new Error('Toast duration must be between 1000 and 30000 milliseconds');
-    }
-    await ready;
-    port.postMessage({ type: 'toast', message: message.trim(), toastType: type, duration });
-  };
-
   const agentPanelLayout = options => {
     if (!options || typeof options !== 'object' || Array.isArray(options)) {
       throw new Error('Agent panel options must be an object');
@@ -451,7 +397,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     return query;
   };
 
-  const api = { copyImage, copyText, getActiveTab, invoke, operation, readClipboard, ready: () => ready, runAgentTask, runningOperations, selectDirectory, setAgentGuides, setAgentPanelVisible, setQueryParam, start, toast };
+  const api = { invoke, subscribe, ready: () => ready, runAgentTask, setAgentGuides, setAgentPanelVisible, setQueryParam };
   const ui = globalThis.__mearlToolboxUi;
   if (ui !== undefined) {
     if (!ui || typeof ui !== 'object' || ui.runtime !== 'preact') {
@@ -491,6 +437,10 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     port = nextPort;
     port.onmessage = responseEvent => {
       const response = responseEvent.data;
+      if (response?.type === 'event' && typeof response.subscriptionId === 'string') {
+        pageEventListeners.get(response.subscriptionId)?.(response.event, response.metadata);
+        return;
+      }
       if (response?.type === 'context') {
         applyContext(response.context);
         return;
@@ -516,7 +466,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
       if (!request) return;
       pending.delete(response.requestId);
       if (response.ok) request.resolve(response.result);
-      else request.reject(new Error(response.error || 'Plugin command failed'));
+      else request.reject(Object.assign(new Error(response.error || 'Plugin command failed'), { handledByHost: response.handledByHost === true }));
     };
     port.start();
     resolveReady(context);

package/dist/socket.d.ts

@@ -18,6 +18,8 @@ export type ControlSource = 'local' | 'remote';
 type CompatibleControlSource = ControlSource | 'cloud';
 export interface InvokeOptions {
     controlSessionId?: string;
+    /** Pin a known local endpoint for a sequence of transport requests. */
+    socketPath?: string;
     /** 超时时间（秒），默认 15 */
     timeoutSec?: number;
     /** Force CDP transport instead of extension */
@@ -31,6 +33,11 @@ export interface InvokeOptions {
 export declare function setDefaultBrowser(selector: string | undefined): void;
 export declare function getDefaultBrowser(): string | undefined;
 export declare function decorateBrowserListResult(result: Record<string, any>): Record<string, any>;
+/** Resolve an existing local route without executing the action. */
+export declare function resolveLocalActionTarget(action: string, data: Record<string, any>, options?: InvokeOptions): {
+    browser?: string;
+    socketPath?: string;
+} | undefined;
 /**
  * 向 native host 发送一个 action 请求并等待响应。
  *

package/dist/socket.js

@@ -18,6 +18,7 @@ import { readLiveProvider } from '@mearl/provider/runtime';
 import { resolveFileRefs } from './fileRefs.js';
 import { listLiveBrowsers, findBrowser, describeBrowser, } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
+import { isBrowserCapabilityAction } from './generated-browser-action-protocol.js';
 const require = createRequire(import.meta.url);
 export const CLIENT_VERSION = require('../package.json').version;
 const MAX_SOCKET_BUFFER_SIZE = 64 * 1024 * 1024;
@@ -160,6 +161,24 @@ function supportsAction(browser, action, data) {
     return (browser.transport !== 'provider' ||
         browser.capabilities?.actions.some(capability => capability === action) === true);
 }
+function routableBrowsers(browsers, action, data, transport) {
+    return browsers.filter(browser => isConnectedBrowser(browser) &&
+        (action !== 'browser_list' || browser.transport !== 'provider') &&
+        !(transport === 'cdp' && browser.transport === 'provider') &&
+        supportsAction(browser, action, data));
+}
+/** Resolve an existing local route without executing the action. */
+export function resolveLocalActionTarget(action, data, options = {}) {
+    const selector = options.browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
+    const socketPath = options.socketPath ?? process.env.MEARL_SOCKET_PATH?.trim();
+    if (socketPath && (options.socketPath || !selector))
+        return { socketPath };
+    const browsers = listLiveBrowsers();
+    const target = selector
+        ? findBrowser(browsers, selector)
+        : routableBrowsers(browsers, action, data, options.transport)[0];
+    return target ? { browser: target.browserId } : undefined;
+}
 function selectBrowserResult(data) {
     const selector = typeof data.browser === 'string' ? data.browser.trim() : '';
     if (!selector) {
@@ -329,6 +348,17 @@ function removeStaleLegacySocket(identity) {
  * legacy well-known socket，并在 socket 不存在或已残留时自动拉起 native host。
  */
 export function invoke(action, data = {}, options = {}) {
+    if (action === '__resolve_action_target') {
+        if (!isBrowserCapabilityAction(data.action))
+            return Promise.reject(new Error('Invalid browser capability action'));
+        const target = resolveLocalActionTarget(data.action, data.data ?? {}, options);
+        const browser = target?.browser ??
+            (target?.socketPath
+                ? listLiveBrowsers().find(item => item.socketPath === target.socketPath &&
+                    supportsAction(item, data.action, data.data ?? {}))?.browserId
+                : undefined);
+        return Promise.resolve(browser ? { browser } : null);
+    }
     if (action === 'browser_select_browser') {
         try {
             return Promise.resolve(selectBrowserResult(data));
@@ -338,14 +368,50 @@ export function invoke(action, data = {}, options = {}) {
         }
     }
     const { timeoutSec = resolveActionTimeoutSec(action, data), transport, browser, controlSource = 'local', } = options;
+    if (action === '__control_session_resolve') {
+        return resolveControlSession(data.sessionId, timeoutSec, controlSource);
+    }
     // 统一解析 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));
+        return dispatchInvoke(action, resolvedData, timeoutSec, transport, undefined, controlSource, options.socketPath).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);
+    return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector, controlSource, options.socketPath);
+}
+/** Session ownership lives in the control hosts and survives individual CLI connections. */
+async function resolveControlSession(sessionId, timeoutSec, controlSource) {
+    const browsers = listLiveBrowsers();
+    const configuredSocketPath = process.env.MEARL_SOCKET_PATH?.trim();
+    const sockets = configuredSocketPath
+        ? [configuredSocketPath]
+        : [
+            ...new Set(browsers
+                .filter(browser => browser.transport !== 'provider')
+                .map(browser => browser.socketPath)),
+        ];
+    const provider = configuredSocketPath
+        ? undefined
+        : browsers.find(browser => browser.transport === 'provider');
+    if (!sockets.length && !provider)
+        sockets.push(SOCKET_PATH);
+    const requests = sockets.map(socketPath => invokeOnce('__control_session_resolve', { sessionId }, timeoutSec, undefined, socketPath, controlSource));
+    if (provider) {
+        requests.push(invokeOnce('__control_session_resolve', { sessionId }, timeoutSec, undefined, provider.socketPath, controlSource, provider.browserId));
+    }
+    const results = await Promise.allSettled(requests);
+    const sessions = results.flatMap(result => result.status === 'fulfilled' && result.value?.session?.sessionId === sessionId
+        ? [result.value.session]
+        : []);
+    if (sessions.length > 1)
+        throw new Error('CONTROL_SESSION_AMBIGUOUS: multiple hosts own this id');
+    if (sessions.length)
+        return { session: sessions[0] };
+    const failure = results.find(result => result.status === 'rejected' && !isConnError(result.reason));
+    if (failure?.status === 'rejected')
+        throw failure.reason;
+    return { session: null };
 }
 function isConnError(error) {
     const code = error?.code;
@@ -359,9 +425,9 @@ function isUnavailableConnection(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) {
+async function dispatchInvoke(action, data, timeoutSec, transport, selector, controlSource, socketPath) {
+    const configuredSocketPath = socketPath ?? process.env.MEARL_SOCKET_PATH?.trim();
+    if (configuredSocketPath && (socketPath || !selector)) {
         try {
             return await invokeOnce(action, data, timeoutSec, transport, configuredSocketPath, controlSource);
         }
@@ -447,11 +513,9 @@ 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 => (action !== 'browser_list' || browser.transport !== 'provider') &&
-        !(transport === 'cdp' && browser.transport === 'provider') &&
-        supportsAction(browser, action, data));
-    if (routableBrowsers.length > 0) {
-        const target = routableBrowsers[0];
+    const candidates = routableBrowsers(browsers, action, data, transport);
+    if (candidates.length > 0) {
+        const target = candidates[0];
         try {
             return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.transport === 'provider' ? target.browserId : undefined);
         }

package/dist/unified.d.ts

@@ -30,12 +30,8 @@ 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 controlSessions;
     private readonly options;
     private defaultBrowser;
     private defaultConnector;
@@ -55,6 +51,7 @@ export declare class UnifiedClient {
         outputPath: string;
         bytes: number;
     }>;
+    private pinPageEvalTarget;
     private invokeRouted;
     private invokeExplicitLocal;
     private invokeLaunchWithoutControlBrowser;
@@ -71,6 +68,7 @@ export declare class UnifiedClient {
     private invokeLocal;
     private invokeRemote;
     private decorateActionResult;
+    private resolveControlSession;
     private ensureConnected;
     private connect;
     private startHeartbeat;

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.2",
+  "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/provider": "2.20.2",
-    "@mearl/cloud-types": "2.20.2"
+    "@mearl/cloud-types": "2.20.3",
+    "@mearl/provider": "2.20.3"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",