@mearl/client 2.19.3 → 2.20.1

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'>;
@@ -277,6 +323,12 @@ export type BrowserProviderInputSchema = (BrowserProviderSchemaBase & {
     maxLength?: number;
     pattern?: string;
     placeholder?: string;
+    options?: readonly {
+        value: string;
+        label: string;
+        description?: string;
+        disabled?: boolean;
+    }[];
 }) | (BrowserProviderSchemaBase & {
     type: 'number';
     integer?: boolean;
@@ -307,8 +359,29 @@ export interface BrowserProviderDefinition {
         configuration?: {
             inputSchema: BrowserProviderObjectSchema;
         };
+        dynamicLaunchForm?: boolean;
+        launchForm?: BrowserProviderLaunchForm;
     };
 }
+export interface BrowserProviderLaunchFormVariant {
+    id: string;
+    title: string;
+    description?: string;
+    inputSchema?: BrowserProviderObjectSchema;
+    values?: Record<string, BrowserJsonValue>;
+    refreshOn?: readonly string[];
+    dynamicFields?: readonly string[];
+}
+export interface BrowserProviderLaunchForm {
+    inputSchema: BrowserProviderObjectSchema;
+    variants?: readonly BrowserProviderLaunchFormVariant[];
+    variant?: string;
+    values?: Record<string, BrowserJsonValue>;
+    refreshOn?: readonly string[];
+    dynamicFields?: readonly string[];
+    message?: string;
+    blocked?: boolean;
+}
 export interface BrowserProviderListResult {
     providers: BrowserProviderDefinition[];
 }
@@ -595,7 +668,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 +799,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 +923,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 +949,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 +993,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 +1062,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;