@mearl/client 2.19.3 → 2.20.0

package/README.md

@@ -72,6 +72,29 @@ mearl browser_list
 mearl browser_release
 ```
 
+### 控制会话与文件
+
+多步骤任务首次 `tab_open` 或 `page_snapshot` 使用 `--session new`，响应在原结果旁附带 `session`，后续用其 `sessionId` 自动路由，无需额外创建/查询 action。Session 绑定一个浏览器与传输；页面首次使用自动关联，复用页面与新建页面分别记录。同一页面只允许一个会话控制，旧调用不能绕过占用；Session 不隔离 Cookie 或存储。
+
+旧调用不必传 `--session`，现有动作、`run_actions` 批次和上传 `filePaths` 参数继续可用。活动会话存在时，旧调用不能操作其占用页面、执行浏览器级释放/关闭或修改共享设置；旧批次中的开页/关闭浏览器需改为独立调用。CDP Mock 按标签页生效，跨页使用同一 Mock 时需分别配置。
+
+```bash
+mearl tab_open --session new --payload '{"url":"https://example.com"}'
+mearl page_snapshot --session '<sessionId>' --payload '{"tabId":12345}'
+mearl browser_control --session '<sessionId>' --payload '{"operation":"handoff","reason":"请完成扫码"}'
+mearl page_download --session '<sessionId>' --payload '{"tabId":12345,"trigger":{"selector":"#export"}}' --output /absolute/path/report.csv
+mearl page_upload --session '<sessionId>' --payload '{"tabId":12345,"selector":"input[type=file]","files":[{"filePath":"/absolute/path/report.csv"}]}'
+mearl browser_release --session '<sessionId>' --payload '{"closeCreatedTabs":true,"keepTabIds":[12345]}'
+```
+
+用户在 Popup 的浏览器管理页接管、交还或结束会话。交接后排队旧请求和批次后续步骤停止；已派发动作可能仍然生效。交还后重新取快照。CDP-only 环境可在用户明确确认后用同一 `browser_control` 的 `operation:"resume"` 交还，无需额外 action。会话跨 CLI 连接保留，宿主进程退出后失效；不会根据空闲时间清理用户正在操作的会话。
+
+带 Session 的释放只影响该会话，默认保留页面及环境；`closeCreatedTabs` 只关闭新建页，`keepTabIds` 保留结果页，复用的用户页面始终保留。`preserveEnvironment:false` 清理这些页面的环境。活动会话存在时，浏览器级释放与关闭会被拒绝。
+
+`page_download` 先监听再点击，返回浏览器文件产物；CLI `--output` 或 SDK `saveArtifact(artifact, absolutePath, { session })` 以 256 KiB 分块导出到调用方。`page_upload.files` 接受调用方绝对路径 `{filePath}` 或浏览器 `{artifactId}`，`filePaths` 仍指浏览器宿主路径。单文件最多 256 MiB；保存到调用方的结果独立于临时产物。会话释放清理临时产物，`keepArtifactIds` 可保留指定产物；无会话产物空闲一小时回收，宿主退出清理暂存。
+
+扩展捕获下载需要匹配来源页 referrer 或明确的预期 `url`，无法归属时不会认领最近下载。CDP 只在托管浏览器中使用临时下载目录，共享浏览器保持默认目录，Chrome 未返回完成文件路径时明确报错。下载超时可能已经触发，需检查现场再决定下一步。当前会话与下载适配 Extension/CDP；直接处理页面动作的外部 Provider 对不支持的能力明确报错。
+
 ### 外部浏览器 Provider
 
 Provider 浏览器与扩展、CDP 浏览器一起出现在 `browser_list` 中，并使用同一个

package/dist/actionTimeouts.js

@@ -29,6 +29,8 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
     if (action === 'send_mtop_request') {
         return Math.max(fallback, Math.ceil(((data.timeout ?? 10000) + 5000) / 1000));
     }
+    if (action === 'page_download')
+        return Math.max(fallback, Math.ceil((Number(data.timeout ?? 30000) + 10000) / 1000));
     if (action === 'page_wait') {
         const waitMs = data.time ?? data.timeout ?? 10000;
         return Math.max(fallback, Math.ceil((Number(waitMs) + 5000) / 1000));

package/dist/artifacts.d.ts

@@ -0,0 +1,17 @@
+import type { BrowserArtifact } from './generated-browser-action-protocol.js';
+import type { UnifiedInvokeOptions } from './unified.js';
+interface Invoker {
+    invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+}
+export declare function stageFile(client: Invoker, filePath: string, options: UnifiedInvokeOptions): Promise<{
+    artifactId: string;
+    options: UnifiedInvokeOptions;
+}>;
+/** Atomically export browser-host data to the calling machine without large JSON responses. */
+export declare function exportArtifact(client: Invoker, artifact: BrowserArtifact & {
+    browserId?: string;
+}, outputPath: string, options?: UnifiedInvokeOptions): Promise<{
+    outputPath: string;
+    bytes: number;
+}>;
+export {};

package/dist/artifacts.js

@@ -0,0 +1,80 @@
+import { open, mkdir, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+const CHUNK_BYTES = 256 * 1024;
+export async function stageFile(client, filePath, options) {
+    if (!path.isAbsolute(filePath))
+        throw new Error('Caller-local file paths must be absolute');
+    const source = await open(filePath, 'r');
+    let id;
+    let pinned = options;
+    try {
+        const metadata = await source.stat();
+        if (!metadata.isFile() || metadata.size > 256 * 1024 * 1024)
+            throw new Error('Upload requires a regular file of at most 256 MiB');
+        const created = await client.invoke('__artifact_init', { filename: path.basename(filePath) }, options);
+        pinned = { ...options, browser: created.browserId };
+        id = created.artifact.artifactId;
+        let offset = 0;
+        for await (const chunk of source.createReadStream({
+            highWaterMark: CHUNK_BYTES,
+            autoClose: false,
+        })) {
+            await client.invoke('__artifact_write', { artifactId: id, offset, base64: chunk.toString('base64') }, pinned);
+            offset += chunk.length;
+        }
+        await client.invoke('__artifact_complete', { artifactId: id, bytes: offset }, pinned);
+        return { artifactId: id, options: pinned };
+    }
+    catch (error) {
+        if (id)
+            await client.invoke('__artifact_remove', { artifactId: id }, pinned).catch(() => { });
+        throw error;
+    }
+    finally {
+        await source.close();
+    }
+}
+/** Atomically export browser-host data to the calling machine without large JSON responses. */
+export async function exportArtifact(client, artifact, outputPath, options = {}) {
+    if (!Number.isSafeInteger(artifact.bytes) || artifact.bytes < 0)
+        throw new Error('Invalid artifact size');
+    if (!path.isAbsolute(outputPath))
+        throw new Error('Artifact output paths must be absolute');
+    if (!options.session && !artifact.browserId && !options.browser)
+        throw new Error('An artifact requires its originating browser');
+    const pinned = { ...options, ...(artifact.browserId ? { browser: artifact.browserId } : {}) };
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    const temporary = `${outputPath}.${randomUUID()}.part`;
+    const target = await open(temporary, 'wx', 0o600);
+    try {
+        let offset = 0;
+        if (artifact.bytes === 0) {
+            const empty = await client.invoke('__artifact_read', { artifactId: artifact.artifactId, offset: 0 }, pinned);
+            if (empty.totalBytes !== 0 || empty.bytes !== 0 || empty.base64 !== '')
+                throw new Error('Artifact export size mismatch');
+        }
+        while (offset < artifact.bytes) {
+            const chunk = await client.invoke('__artifact_read', { artifactId: artifact.artifactId, offset }, pinned);
+            const bytes = Buffer.from(chunk.base64, 'base64');
+            if (!bytes.length ||
+                bytes.length !== chunk.bytes ||
+                chunk.totalBytes !== artifact.bytes ||
+                offset + bytes.length > artifact.bytes)
+                throw new Error('Invalid artifact chunk or truncated transfer');
+            await target.write(bytes);
+            offset += bytes.length;
+        }
+        await target.sync();
+        await target.close();
+        if ((await stat(temporary)).size !== artifact.bytes)
+            throw new Error('Artifact export size mismatch');
+        await rename(temporary, outputPath);
+        return { outputPath, bytes: artifact.bytes };
+    }
+    catch (error) {
+        await target.close().catch(() => { });
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}

package/dist/cli.d.ts

@@ -3,6 +3,7 @@ export interface MearlCliOptions {
     clientVersion?: string;
 }
 export interface ParsedArgs {
+    session?: string;
     action: string;
     browser?: string;
     compact: boolean;

package/dist/cli.js

@@ -38,6 +38,7 @@ const CATEGORIES = [
             'page_wait',
             'page_navigate',
             'page_upload',
+            'page_download',
             'page_eval',
         ],
     },
@@ -48,7 +49,13 @@ const CATEGORIES = [
     },
     {
         title: '浏览器',
-        names: ['browser_list', 'browser_launch', 'browser_release', 'browser_close'],
+        names: [
+            'browser_list',
+            'browser_launch',
+            'browser_release',
+            'browser_close',
+            'browser_control',
+        ],
     },
 ];
 const BUILTIN_COMMANDS = [
@@ -119,6 +126,7 @@ function printUsage(commandName, version) {
         '  --timeout <seconds>   超时时间（默认按 action 推导）',
         '  --compact             stdout 输出紧凑格式 JSON',
         '  --output <path>       保存输出或截图',
+        '  --session <new|id>    首次建立或复用控制会话',
         '  --browser <id|名称>   指定 browser_list 返回的浏览器',
         '',
         '其他选项：',
@@ -422,6 +430,7 @@ export function parseClientArgs(args, plugin = false) {
         .option('--json')
         .option('--output <path>')
         .option('--browser <id-or-name>')
+        .option('--session <new-or-id>')
         .option('--connector <id-or-name>')
         .option('--local')
         .option('--updates')
@@ -484,6 +493,7 @@ export function parseClientArgs(args, plugin = false) {
         updates: options.updates === true,
         ...(outputPath ? { outputPath } : {}),
         ...(options.browser ? { browser: options.browser } : {}),
+        ...(options.session ? { session: options.session } : {}),
         ...(connector ? { connector } : {}),
         ...resolveServer(options.server),
         ...(plugin
@@ -512,6 +522,7 @@ async function runPluginCli(args, commandName) {
         const invokeOptions = {
             ...(parsed.timeoutOption ? { timeoutSec: parsed.timeoutSec } : {}),
             ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.session ? { session: parsed.session } : {}),
             ...(parsed.connector ? { connector: parsed.connector } : {}),
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
@@ -665,6 +676,7 @@ export async function runMearlCli(args, options = {}) {
             ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
             ...(parsed.serverUrlSource ? { serverUrlSource: parsed.serverUrlSource } : {}),
             ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.session ? { session: parsed.session } : {}),
             ...(parsed.connector ? { connector: parsed.connector } : {}),
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
@@ -684,12 +696,25 @@ export async function runMearlCli(args, options = {}) {
         const result = await client.invoke(parsed.action, parsed.payload, {
             timeoutSec: parsed.timeoutSec,
             ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.session ? { session: parsed.session } : {}),
             ...(parsed.connector ? { connector: parsed.connector } : {}),
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
         });
-        if (parsed.outputPath) {
+        if (parsed.outputPath && parsed.action === 'page_download') {
+            await client.saveArtifact(result.download, resolve(parsed.outputPath), {
+                ...(parsed.session ? { session: parsed.session } : {}),
+            });
+            process.stdout.write(JSON.stringify({ ...result, outputPath: resolve(parsed.outputPath) }) + '\n');
+            if (!parsed.session)
+                await client.invoke('__artifact_remove', { artifactId: result.download.artifactId }, { browser: result.download.browserId });
+        }
+        else if (parsed.outputPath) {
             writeOutput(parsed.action, result, parsed.outputPath);
+            if (parsed.action === 'page_screenshot' && result?.session) {
+                const { data: _image, ...metadata } = result;
+                process.stdout.write(JSON.stringify({ ...metadata, outputPath: resolve(parsed.outputPath) }) + '\n');
+            }
         }
         else {
             process.stdout.write(`${parsed.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2)}\n`);

package/dist/commands.d.ts

@@ -23,6 +23,48 @@ export interface CommandDef {
     result?: readonly string[];
 }
 export declare const COMMANDS: readonly [{
+    readonly name: "browser_control";
+    readonly description: "把控制会话交给用户；用户在 Mearl 浏览器管理页交还后重新观察页面";
+    readonly params: [{
+        readonly name: "operation";
+        readonly type: "\"handoff\" | \"resume\"";
+        readonly required: true;
+        readonly description: "交给用户操作；resume 仅在用户明确交还后使用";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "可选的目标页面";
+    }, {
+        readonly name: "reason";
+        readonly type: "string";
+        readonly description: "用户需要处理的事项";
+    }];
+    readonly notes: readonly ["必须携带 --session；接管停止后续派发，已经发出的操作可能仍然生效。"];
+}, {
+    readonly name: "page_download";
+    readonly description: "先监听再点击，等待下载完成并创建浏览器文件产物";
+    readonly outputFlag: true;
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "下载来源页面";
+    }, {
+        readonly name: "trigger";
+        readonly type: "object";
+        readonly required: true;
+        readonly description: "page_click 参数，不含 tabId";
+    }, {
+        readonly name: "url";
+        readonly type: "string";
+        readonly description: "预期下载 URL；扩展无法通过 referrer 归属时需显式指定";
+    }, {
+        readonly name: "timeout";
+        readonly type: "number";
+        readonly description: "下载等待毫秒，默认 30000，范围 1000–300000";
+    }];
+    readonly notes: readonly ["--output 把文件分块保存到调用方机器；未指定时返回 artifactId，可供 page_upload 复用。", "共享 CDP 浏览器保持原下载目录；Chrome 未返回文件路径时明确报错。超时不能直接重复点击。"];
+}, {
     readonly name: "tab_checkpoint";
     readonly description: "为目标标签页建立日志、请求和埋点增量边界";
     readonly params: [{
@@ -354,6 +396,24 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "browser_release";
     readonly description: "释放当前浏览器的调试控制和会话级临时效果（含设备/时区模拟）；不用于普通任务收尾，Provider 实例的行为以 mearl <providerId> 为准";
+    readonly params: [{
+        readonly name: "closeCreatedTabs";
+        readonly type: "boolean";
+        readonly description: "带 --session 时关闭会话创建的过程页，默认 false";
+    }, {
+        readonly name: "keepTabIds";
+        readonly type: "number[]";
+        readonly description: "保留的结果页面；复用的用户页面始终保留";
+    }, {
+        readonly name: "preserveEnvironment";
+        readonly type: "boolean";
+        readonly description: "带 --session 时默认 true，保留 Mock 与模拟现场；false 清理这些页面的环境";
+    }, {
+        readonly name: "keepArtifactIds";
+        readonly type: "string[]";
+        readonly description: "保留在浏览器宿主的文件产物；其余会话临时文件删除";
+    }];
+    readonly notes: readonly ["带 --session 时可用于任务收尾，只释放该会话；未带会话时保留原浏览器级释放行为，活动会话存在时拒绝全局释放。"];
     readonly summary: "释放浏览器调试控制和会话级临时效果";
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
@@ -808,6 +868,10 @@ export declare const COMMANDS: readonly [{
     readonly name: "page_upload";
     readonly description: "向 <input type=\"file\"> 元素上传一个或多个文件";
     readonly params: [{
+        readonly name: "files";
+        readonly type: "object[]";
+        readonly description: "调用方绝对路径 {filePath} 或浏览器产物 {artifactId}；与 filePaths 二选一";
+    }, {
         readonly name: "selector";
         readonly type: "string";
         readonly required: true;
@@ -815,8 +879,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "filePaths";
         readonly type: "string[]";
-        readonly required: true;
-        readonly description: "本地文件路径数组";
+        readonly description: "浏览器宿主上的绝对路径数组；与 files 二选一";
     }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";

package/dist/commands.js

@@ -36,6 +36,49 @@ const PAGE_ACTION_RESULT = [
     '显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。',
 ];
 export const COMMANDS = [
+    {
+        name: 'browser_control',
+        description: '把控制会话交给用户；用户在 Mearl 浏览器管理页交还后重新观察页面',
+        params: [
+            {
+                name: 'operation',
+                type: '"handoff" | "resume"',
+                required: true,
+                description: '交给用户操作；resume 仅在用户明确交还后使用',
+            },
+            { name: 'tabId', type: 'number', description: '可选的目标页面' },
+            { name: 'reason', type: 'string', description: '用户需要处理的事项' },
+        ],
+        notes: ['必须携带 --session；接管停止后续派发，已经发出的操作可能仍然生效。'],
+    },
+    {
+        name: 'page_download',
+        description: '先监听再点击，等待下载完成并创建浏览器文件产物',
+        outputFlag: true,
+        params: [
+            { name: 'tabId', type: 'number', required: true, description: '下载来源页面' },
+            {
+                name: 'trigger',
+                type: 'object',
+                required: true,
+                description: 'page_click 参数，不含 tabId',
+            },
+            {
+                name: 'url',
+                type: 'string',
+                description: '预期下载 URL；扩展无法通过 referrer 归属时需显式指定',
+            },
+            {
+                name: 'timeout',
+                type: 'number',
+                description: '下载等待毫秒，默认 30000，范围 1000–300000',
+            },
+        ],
+        notes: [
+            '--output 把文件分块保存到调用方机器；未指定时返回 artifactId，可供 page_upload 复用。',
+            '共享 CDP 浏览器保持原下载目录；Chrome 未返回文件路径时明确报错。超时不能直接重复点击。',
+        ],
+    },
     // ── API 调试 ──────────────────────────────────────────────────────────────
     {
         name: 'tab_checkpoint',
@@ -337,6 +380,31 @@ export const COMMANDS = [
     {
         name: 'browser_release',
         description: '释放当前浏览器的调试控制和会话级临时效果（含设备/时区模拟）；不用于普通任务收尾，Provider 实例的行为以 mearl <providerId> 为准',
+        params: [
+            {
+                name: 'closeCreatedTabs',
+                type: 'boolean',
+                description: '带 --session 时关闭会话创建的过程页，默认 false',
+            },
+            {
+                name: 'keepTabIds',
+                type: 'number[]',
+                description: '保留的结果页面；复用的用户页面始终保留',
+            },
+            {
+                name: 'preserveEnvironment',
+                type: 'boolean',
+                description: '带 --session 时默认 true，保留 Mock 与模拟现场；false 清理这些页面的环境',
+            },
+            {
+                name: 'keepArtifactIds',
+                type: 'string[]',
+                description: '保留在浏览器宿主的文件产物；其余会话临时文件删除',
+            },
+        ],
+        notes: [
+            '带 --session 时可用于任务收尾，只释放该会话；未带会话时保留原浏览器级释放行为，活动会话存在时拒绝全局释放。',
+        ],
         summary: '释放浏览器调试控制和会话级临时效果',
         examples: ['browser_release', 'browser_release --browser chrome-a'],
     },
@@ -882,13 +950,22 @@ export const COMMANDS = [
         name: 'page_upload',
         description: '向 <input type="file"> 元素上传一个或多个文件',
         params: [
+            {
+                name: 'files',
+                type: 'object[]',
+                description: '调用方绝对路径 {filePath} 或浏览器产物 {artifactId}；与 filePaths 二选一',
+            },
             {
                 name: 'selector',
                 type: 'string',
                 required: true,
                 description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀），必须指向 input[type=file]',
             },
-            { name: 'filePaths', type: 'string[]', required: true, description: '本地文件路径数组' },
+            {
+                name: 'filePaths',
+                type: 'string[]',
+                description: '浏览器宿主上的绝对路径数组；与 files 二选一',
+            },
             PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },

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

@@ -173,7 +173,7 @@ export interface BrowserInfoBase {
 }
 export type BrowserScreenshotKind = 'native' | 'reconstructed' | 'none';
 /** Browser-targeted actions that an external provider may implement. */
-export type BrowserCapabilityAction = ExtensionBrowserAction;
+export type BrowserCapabilityAction = ExtensionBrowserAction | 'page_download';
 /** Capabilities advertised by an external browser-control provider. */
 export interface BrowserCapabilities {
     actions: BrowserCapabilityAction[];
@@ -222,6 +222,52 @@ export interface BrowserReleaseResult {
     affectedTabIds: number[];
     failures?: BrowserReleaseFailure[];
 }
+export interface ControlSessionInfo {
+    sessionId: string;
+    browserId: string;
+    transport: BrowserTransport;
+    status: 'active' | 'user' | 'releasing' | 'released';
+    generation: number;
+    tabs: Array<{
+        tabId: number;
+        source: 'created' | 'attached';
+        title?: string;
+        url?: string;
+    }>;
+    reason?: string;
+}
+export interface BrowserReleaseParams {
+    /** Close only session-created pages; attached user pages are protected. */
+    closeCreatedTabs?: boolean;
+    keepTabIds?: number[];
+    /** Preserve the browser environment by default for a scoped release. */
+    preserveEnvironment?: boolean;
+    keepArtifactIds?: string[];
+}
+export interface BrowserControlParams {
+    operation: 'handoff' | 'resume';
+    tabId?: number;
+    reason?: string;
+}
+export interface BrowserArtifact {
+    artifactId: string;
+    filename: string;
+    bytes: number;
+    location: 'browser';
+    /** Global browser route is attached by the unified client. */
+    browserId?: string;
+}
+export interface PageDownloadParams {
+    tabId: number;
+    trigger: Omit<PageClickParams, 'tabId'>;
+    /** Restrict the expected download URL; useful when the browser cannot identify its source. */
+    url?: string;
+    timeout?: number;
+}
+export interface PageDownloadResult {
+    download: BrowserArtifact;
+    action: unknown;
+}
 export interface CookieCopyScope {
     /** Maintained authentication-domain presets to include. */
     presets?: Array<'mearl-services'>;
@@ -595,7 +641,14 @@ export interface PageNavigateParams {
 export interface PageUploadParams {
     tabId: number;
     selector: string;
-    filePaths: string[];
+    /** Absolute paths available to the browser host. */
+    filePaths?: string[];
+    /** SDK/CLI stages caller-local files before dispatch. Mutually exclusive with filePaths. */
+    files?: Array<{
+        filePath: string;
+    } | {
+        artifactId: string;
+    }>;
     observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
 }
@@ -719,9 +772,19 @@ export interface BrowserActionMap {
         response: SelectBrowserResult;
     };
     browser_release: {
-        request: undefined;
+        request: BrowserReleaseParams;
         response: BrowserReleaseResult;
     };
+    browser_control: {
+        request: BrowserControlParams;
+        response: {
+            session: ControlSessionInfo;
+        };
+    };
+    page_download: {
+        request: PageDownloadParams;
+        response: PageDownloadResult;
+    };
     browser_launch: {
         request: BrowserLaunchParams;
         response: ManagedBrowserInfo;
@@ -833,10 +896,12 @@ export interface BrowserActionMap {
 }
 export type BrowserAction = keyof BrowserActionMap;
 export type BrowserActionRequest<A extends BrowserAction> = BrowserActionMap[A]['request'];
-export type BrowserActionResponse<A extends BrowserAction> = BrowserActionMap[A]['response'];
+export type BrowserActionResponse<A extends BrowserAction> = BrowserActionMap[A]['response'] & {
+    session?: ControlSessionInfo;
+};
 export type BrowserCommandAction = Exclude<BrowserAction, 'browser_select_browser'>;
-export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list' | 'browser_launch' | 'browser_close'>;
-export declare const TAB_ID_REQUIRED_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "page_screenshot", "tab_close", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_inspect", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "run_actions"];
+export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list' | 'browser_launch' | 'browser_close' | 'browser_control' | 'page_download'>;
+export declare const TAB_ID_REQUIRED_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "page_screenshot", "tab_close", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_inspect", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_download", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "run_actions"];
 export type TabIdRequiredAction = (typeof TAB_ID_REQUIRED_ACTIONS)[number];
 export declare function actionRequiresTabId(action: unknown): action is TabIdRequiredAction;
 export declare function validateRequiredActionTabId(action: string, data: unknown): void;
@@ -857,6 +922,8 @@ export declare const BROWSER_ACTIONS: {
     readonly browser_list: true;
     readonly browser_select_browser: true;
     readonly browser_release: true;
+    readonly browser_control: true;
+    readonly page_download: true;
     readonly browser_launch: true;
     readonly browser_close: true;
     readonly page_screenshot: true;
@@ -899,6 +966,8 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly send_mtop_request: true;
     readonly browser_list: true;
     readonly browser_release: true;
+    readonly browser_control: true;
+    readonly page_download: true;
     readonly browser_launch: true;
     readonly browser_close: true;
     readonly page_screenshot: true;
@@ -966,6 +1035,46 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
     readonly request_domain_permission: true;
     readonly run_actions: true;
 };
+export declare const BROWSER_CAPABILITY_ACTIONS: {
+    readonly page_download: true;
+    readonly tab_checkpoint: true;
+    readonly capture_checkpoint: true;
+    readonly get_requests: true;
+    readonly get_logs: true;
+    readonly get_events: true;
+    readonly set_mock: true;
+    readonly get_mocks: true;
+    readonly set_rule: true;
+    readonly get_rules: true;
+    readonly send_request: true;
+    readonly send_mtop_request: true;
+    readonly browser_release: true;
+    readonly page_screenshot: true;
+    readonly tab_open: true;
+    readonly tab_close: true;
+    readonly tab_list: true;
+    readonly tab_group: true;
+    readonly page_click: true;
+    readonly page_drag: true;
+    readonly page_type: true;
+    readonly page_scroll: true;
+    readonly page_hover: true;
+    readonly page_eval: true;
+    readonly page_inspect: true;
+    readonly page_snapshot: true;
+    readonly page_press: true;
+    readonly page_wait: true;
+    readonly page_navigate: true;
+    readonly page_upload: true;
+    readonly page_frames: true;
+    readonly set_device_emulation: true;
+    readonly set_app_profile: true;
+    readonly set_timezone: true;
+    readonly get_cookie: true;
+    readonly set_cookie: true;
+    readonly request_domain_permission: true;
+    readonly run_actions: true;
+};
 export declare function isBrowserAction(value: unknown): value is BrowserAction;
 export declare function isBrowserCommandAction(value: unknown): value is BrowserCommandAction;
 export declare function isBrowserCapabilityAction(value: unknown): value is BrowserCapabilityAction;

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 inlineAgentPanels.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);
@@ -469,6 +503,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) {

package/package.json

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