@mearl/client 2.12.0 → 2.13.0

package/README.md

@@ -77,10 +77,36 @@ mearl browser_list
 mearl browser_release
 ```
 
+### 外部浏览器 Provider
+
+Provider 浏览器与扩展、CDP 和 AgentBay 浏览器一起出现在 `browser_list` 中，并使用同一个
+全局 `browserId` 参与路由。Provider 的安装、更新和卸载由 `@mearl/setup` 管理：
+
+```bash
+npx @mearl/setup provider install @ali/mearl-provider-brow
+
+# 让 Brow 创建一个配对实例；debugId 可省略并自动生成
+mearl browser_launch --payload '{"provider":"brow","providerOptions":{"debugId":"my-device"}}'
+
+# 扫码后确认同一个实例已经连接
+mearl browser_list
+
+# 后续操作使用 browser_list 返回的全局 Browser ID
+mearl page_snapshot --browser '<browserId>'
+
+npx @mearl/setup provider update brow
+npx @mearl/setup provider uninstall brow
+```
+
+`browser_launch` 创建 `pairing` 实例时会直接返回 `pairing.url` 和可选的配对码；Agent 应把 URL 直接渲染为
+二维码交给用户，扫码后确认同一 Browser ID 变为 `connected`，再开始页面操作。在设备连入前
+该实例不会成为默认操作目标；可用 `browser_close` 删除对应 Provider 实例。每个 Provider
+只接收它为该浏览器显式声明支持的 actions，截图能力同时标明为原生截图、重建画面或不支持。
+
 输入不存在或拼写有误的 action 时，CLI 会基于可用命令和常见别名直接返回最多三个候选及调用示例，
 不连接浏览器，也不会自动执行推荐命令。例如 `mearl tab new` 会优先推荐 `mearl tab_open`。
 
-**通用选项：**
+**常用选项：**
 
 | 选项                     | 说明                     |
 | ------------------------ | ------------------------ |
@@ -90,12 +116,19 @@ mearl browser_release
 | `--compact`              | stdout 紧凑输出          |
 | `--output <path>`        | 将结果写入文件（如截图） |
 | `--browser <id\|名称>`   | 指定目标浏览器           |
-| `--connector <id\|名称>` | 限制到一台远端机器       |
-| `--local`                | 只使用当前机器           |
-| `--cdp`                  | 当前机器强制使用 CDP     |
-| `--server <url>`         | 覆盖 cloud-server 地址   |
 
-`check` 有独立的选项说明，运行 `mearl check --help` 查看。其中 `--json` 仅用于输出机器可读的检查结果。
+Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通过 `browser_list` 返回的全局
+`browserId` 自动路由。以下覆盖参数仅在限定宿主或连接、传输排障时使用，因此不出现在默认 help：
+
+| 选项                     | 说明                                  |
+| ------------------------ | ------------------------------------- |
+| `--connector <id\|名称>` | 限制到一台远端机器                    |
+| `--local`                | 只使用当前机器                        |
+| `--cdp`                  | 当前机器强制使用 CDP，并隐含 `--local` |
+| `--server <url>`         | 覆盖自动读取的 cloud-server 地址      |
+
+`browser_list --help` 和 `browser_launch --help` 会按场景展示宿主选择参数；连接或传输排障运行
+`mearl check --help`。其中 `--json` 仅用于输出机器可读的检查结果。
 
 ## Skill CLI 插件
 
@@ -111,7 +144,8 @@ mearl yuque --help
 mearl yuque --version
 ```
 
-目录默认使用 `scripts/main.mjs`。入口默认导出 `register(app)`，通过 `app.command(signature, handler, description?)`
+目录默认使用 `scripts/main.mjs`。入口默认导出 `register(app)`，可导出简短的 `description`
+显示在 `mearl` 插件列表中，并通过 `app.command(signature, handler, description?)`
 注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。CLI 默认只输出最终结果，传入
 `--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
 自动注册默认以 skill 安装目录名作为命令名，也可在入口导出 `name` 指定短名称。
@@ -124,7 +158,7 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 插件接受位置参数或包含 command/input 的 `--payload`，两种形式不能混用。JSON 保留业务字段类型；正文等文件输入
 按具体 skill 的字段约定处理。插件不使用上表中内置 action 的 `--payload-file` 入口。
 
-注册记录在 `~/.mearl/plugins/<name>.json`，只引用入口路径；skill 原地更新直接生效，换路径后重新注册。
+注册记录在 `~/.mearl/plugins/<name>.json`，保存入口路径和可选的简短描述；skill 业务代码原地更新直接生效，换路径或更新描述后重新注册。
 `plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 `ali-skills remove --global --yes`，
 成功后清除相关注册；即使入口目录已被手动删除，也会完成 Ali Skills 跟踪记录的清理。
 手工路径只解除注册并保留源码。
@@ -155,7 +189,9 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 
 重复文本点击可用 `page_click.scope` 限定 CSS / ref 子树；浏览器扩展后端中，容器或 iframe 内的点坐标使用 `coordinateSpace: "active-frame"`，CSS/text 查询可用 `frameId` 显式指定 frame。点击结果通过 `requestedTarget`、`resolvedTarget`、`dispatchTarget`、`hitTarget` 和 `coordinates` 区分请求语义、DOM 解析、派发节点与可信输入实际命中；ref 指向滚动容器内的子节点时，可用 `page_scroll.containerPolicy: "nearest"` 自动解析最近可滚动祖先。
 
-`browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
+`browser_list` 统一列出普通浏览器、Provider 浏览器和托管浏览器。`type` 区分
+`regular` / `managed`，`status` 区分 `connected` / `pairing` / `running_disconnected` /
+`stopped`；只有 `connected` 的浏览器可作为常规操作目标。
 
 按 `sessionId` 接入的 AgentBay 浏览器用 `browser_release` 收尾：它会移除本机 attachment 并退出对应宿主，但不会关闭云端 Session。其他浏览器仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页，后续浏览器操作可自动重新建立控制。
 
@@ -166,8 +202,10 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 ```
 @mearl/client (CLI / SDK)
   ├─ 本机 → @mearl/native-host → Chrome Extension / CDP
+  ├─ 本机 → @mearl/provider runtime → External Provider
   └─ WebSocket → @mearl/cloud-server → @mearl/cloud-connector
-                                      → @mearl/native-host → Chrome Extension / CDP
+                                      ├─ @mearl/native-host → Chrome Extension / CDP
+                                      └─ @mearl/provider runtime → External Provider
 ```
 
 基础设施组件必须避免递归路由：`@mearl/cloud-connector` 使用 `@mearl/client/local` 子路径直连所在机器的 native-host。普通 Agent、CLI 与 MCP 集成均使用包根入口。

package/dist/browserRegistry.d.ts

@@ -8,6 +8,7 @@
  * registry directory and record shape; reading scans every *.json in the dir,
  * so it never needs to replicate daemon-core's filename hashing.
  */
+import type { BrowserCapabilities, BrowserPairingInfo, BrowserTransport } from './generated-browser-action-protocol.js';
 export interface LiveBrowser {
     pid: number;
     browserId: string;
@@ -15,7 +16,15 @@ export interface LiveBrowser {
     browserName: string;
     extensionVersion?: string;
     nativeHostVersion?: string;
-    transport?: 'extension' | 'cdp';
+    transport?: BrowserTransport;
+    providerBrowserId?: string;
+    providerId?: string;
+    providerName?: string;
+    providerVersion?: string;
+    providerProtocolVersion?: number;
+    capabilities?: BrowserCapabilities;
+    status?: 'connected' | 'pairing';
+    pairing?: BrowserPairingInfo;
     lastFocusedAt?: number;
     updatedAt?: number;
 }

package/dist/check.d.ts

@@ -1,9 +1,17 @@
 import type { CloudConnectorInfo } from '@mearl/cloud-types';
+import type { BrowserCapabilities } from './generated-browser-action-protocol.js';
 import { type UnifiedClientOptions, type UnifiedInvokeOptions } from './unified.js';
 export interface UnifiedCheckVersions {
     nativeHost?: string;
     extension?: string | null;
     browser?: string | null;
+    provider?: ProviderVersionInfo;
+}
+export interface ProviderVersionInfo {
+    providerId: string;
+    name: string;
+    version: string;
+    protocolVersion: number;
 }
 export type BrowserAccessCapability = {
     kind: 'agentbay';
@@ -25,7 +33,11 @@ interface BrowserInfo {
     status: string;
     type?: string;
     provider?: 'local' | 'agentbay';
-    transport?: 'extension' | 'cdp';
+    providerId?: string;
+    providerName?: string;
+    providerVersion?: string;
+    providerProtocolVersion?: number;
+    transport?: 'extension' | 'cdp' | 'provider';
 }
 interface CheckItem {
     status: 'ok' | 'warning' | 'error';
@@ -38,6 +50,7 @@ export interface ExtensionInstallationInfo {
 }
 export interface UnifiedCheckBrowserResult extends BrowserInfo {
     browserAccess?: BrowserAccess;
+    capabilities?: BrowserCapabilities;
     check?: {
         errors?: string[];
         label: string;

package/dist/check.js

@@ -56,7 +56,9 @@ function formatBrowser(browser, isDefault) {
         ? ' [CDP]'
         : browser.transport === 'extension'
             ? ' [Extension]'
-            : '';
+            : browser.transport === 'provider'
+                ? ` [Provider: ${browser.providerName || browser.providerId || 'external'}]`
+                : '';
     const type = browser.type === 'managed' ? ' [Managed]' : '';
     return `  ${isDefault ? '★' : ' '} ${browser.name} [${shortBrowserId(browser.browserId)}]${type}${transport}`;
 }
@@ -220,12 +222,20 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                     ...(versions.nativeHost ? { nativeHost: versions.nativeHost } : {}),
                     ...(versions.extension !== undefined ? { extension: versions.extension } : {}),
                     ...(versions.browser !== undefined ? { browser: versions.browser } : {}),
+                    ...(versions.provider ? { provider: versions.provider } : {}),
                 };
                 const details = [
                     versions.nativeHost ? `native-host v${versions.nativeHost}` : null,
                     versions.extension ? `extension v${versions.extension}` : null,
                     versions.browser ? `Chrome ${versions.browser}` : null,
+                    versions.provider
+                        ? `${versions.provider.name} v${versions.provider.version} (protocol v${versions.provider.protocolVersion})`
+                        : null,
                 ].filter((value) => value !== null);
+                const capabilities = options.browser ? versions.capabilities : undefined;
+                if (capabilities) {
+                    details.push(`capabilities (${capabilities.actions.length}): ${capabilities.actions.join(', ') || 'none'}`, `screenshot: ${capabilities.screenshot}`);
+                }
                 let extensionInstallation;
                 if (options.local &&
                     browser.transport === 'extension' &&
@@ -253,6 +263,7 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 browserChecks.push({
                     ...(browserAccess ? { browserAccess } : {}),
                     browser,
+                    ...(capabilities ? { capabilities } : {}),
                     ...(extensionInstallation ? { extensionInstallation } : {}),
                     item: {
                         status: accessUrlWarning ? 'warning' : 'ok',
@@ -302,6 +313,7 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                         ...browserIdentity,
                         selected: targets.some(target => target.browserId === browser.browserId),
                         ...(check?.browserAccess ? { browserAccess: check.browserAccess } : {}),
+                        ...(check?.capabilities ? { capabilities: check.capabilities } : {}),
                         ...(check?.item
                             ? {
                                 check: {

package/dist/cli.js

@@ -1,14 +1,16 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { Command, CommanderError } from 'commander';
+import { listInstalledProviders } from '@mearl/provider/host';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
 import { runUnifiedCheck, parseCheckTimeout } from './check.js';
 import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from './commandSuggestions.js';
 import { COMMANDS, COMMAND_MAP } from './commands.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
-import { findPluginEntry, listPluginNames, loadPlugin, PluginError } from './plugin.js';
+import { findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, PluginError, } from './plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
+const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
     {
         title: 'API 调试',
@@ -74,24 +76,20 @@ function printUsage(commandName, version) {
         '  browser_list 默认聚合当前机器及已配置 cloud-server 下的浏览器。',
         '  后续操作通过 --browser <browserId> 指定目标，客户端会自动选择本地或远端传输。',
         '',
-        '通用选项：',
+        '常用选项：',
         '  --payload <json>      直接传入 JSON 参数',
         '  --payload-file <path> 从文件读取整个 JSON 参数',
         '  --timeout <seconds>   超时时间（默认按 action 推导）',
         '  --compact             stdout 输出紧凑格式 JSON',
         '  --output <path>       保存输出或截图',
         '  --browser <id|名称>   指定 browser_list 返回的浏览器',
-        '  --connector <id|名称> 限制到一台远端 connector',
-        '  --local               只使用当前机器上的浏览器',
-        '  --cdp                 当前机器强制使用 CDP（隐含 --local）',
-        '  --server <url>        覆盖 cloud-server WebSocket URL',
         '',
         '其他选项：',
         '  -h, --help            查看帮助',
         '  -v, --version         查看版本',
         '',
         '内置命令：',
-        '  check                 检查指定浏览器，未指定时检查全部已连接浏览器',
+        `  ${'check'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}检查指定浏览器，未指定时检查全部已连接浏览器`,
     ];
     for (const category of CATEGORIES) {
         lines.push('', `  ${category.title}`);
@@ -103,12 +101,28 @@ function printUsage(commandName, version) {
     }
     try {
         const plugins = listPluginNames();
-        if (plugins.length)
-            lines.push('', '已注册插件：', ...plugins.map(name => `  ${name}`));
+        if (plugins.length) {
+            const entries = plugins.map(name => {
+                try {
+                    const description = findPluginRegistration(name)?.description;
+                    return description
+                        ? `  ${name.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}${description}`
+                        : `  ${name}`;
+                }
+                catch {
+                    return `  ${name}`;
+                }
+            });
+            lines.push('', '已注册插件：', ...entries);
+        }
     }
     catch (error) {
         lines.push('', error instanceof Error ? error.message : String(error));
     }
+    const providers = listInstalledProviders();
+    if (providers.length) {
+        lines.push('', '已注册 Provider：', ...providers.map(provider => `  ${provider.providerId.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}${provider.name} v${provider.version} (${provider.packageName})`));
+    }
     lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
@@ -149,7 +163,7 @@ function printCommandHelp(commandName, command) {
         `  ${command.description}`,
         '',
         '用法：',
-        `  ${commandName} ${command.name}${payloadUsage} [通用选项]`,
+        `  ${commandName} ${command.name}${payloadUsage} [常用选项]`,
         '',
     ];
     if (command.params?.length) {
@@ -160,12 +174,18 @@ function printCommandHelp(commandName, command) {
         }
         lines.push('');
     }
+    if (command.name === 'browser_list') {
+        lines.push('目标范围（按需）：', '  --local               只列出当前机器上的浏览器', '  --connector <id|名称> 只列出指定远端 connector 的浏览器', '');
+    }
+    else if (command.name === 'browser_launch') {
+        lines.push('宿主选择（本机与远端同时可用时）：', '  --local               在当前机器启动', '  --connector <id|名称> 在指定远端 connector 启动', '  --browser <id|名称>   在控制浏览器所在宿主启动，并可作为 Cookie/UA 来源', '');
+    }
     if (command.examples?.length) {
         lines.push('示例：');
         for (const example of command.examples)
             lines.push(`  ${commandName} ${example}`);
     }
-    lines.push('', `运行 ${commandName} --help 查看通用选项。`);
+    lines.push('', `运行 ${commandName} --help 查看常用选项。`);
     console.error(lines.join('\n'));
 }
 function printUnknownCommand(commandName, args) {
@@ -222,6 +242,31 @@ function resolveServer(explicit) {
         ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
         : {};
 }
+function normalizeScreenshotOutput(action, payload, explicitOutput) {
+    if (action !== 'page_screenshot' || !Object.hasOwn(payload, 'output')) {
+        return { payload, ...(explicitOutput ? { outputPath: explicitOutput } : {}) };
+    }
+    const payloadOutput = payload.output;
+    if (typeof payloadOutput !== 'string' || payloadOutput.trim() === '') {
+        throw new Error('page_screenshot 的 payload.output 必须是非空路径');
+    }
+    if (explicitOutput !== undefined) {
+        throw new Error('page_screenshot 的 payload.output 不能与 --output 同时使用');
+    }
+    const { output: _output, ...normalizedPayload } = payload;
+    return { payload: normalizedPayload, outputPath: payloadOutput };
+}
+function actionInvocationFailed(action, result) {
+    if (result?.action?.success === false)
+        return true;
+    if (action !== 'run_actions')
+        return false;
+    if (Number.isInteger(result?.failedStep))
+        return true;
+    return Array.isArray(result?.results)
+        ? result.results.some((step) => step?.success === false)
+        : false;
+}
 export function parseClientArgs(args, plugin = false) {
     const program = new Command()
         .name('mearl')
@@ -264,7 +309,8 @@ export function parseClientArgs(args, plugin = false) {
     const json = options.json === true;
     if (json && action !== 'check')
         throw new Error('--json 仅适用于 check');
-    const payload = parsePayload(options.payload, options.payloadFile);
+    const parsedPayload = parsePayload(options.payload, options.payloadFile);
+    const { payload, outputPath } = normalizeScreenshotOutput(action, parsedPayload, options.output);
     const fallbackTimeout = resolveActionTimeoutSec(action, payload, 60);
     const forceCdp = options.cdp === true;
     const local = forceCdp || options.local === true;
@@ -280,7 +326,7 @@ export function parseClientArgs(args, plugin = false) {
         forceCdp,
         json,
         local,
-        ...(options.output ? { outputPath: options.output } : {}),
+        ...(outputPath ? { outputPath } : {}),
         ...(options.browser ? { browser: options.browser } : {}),
         ...(connector ? { connector } : {}),
         ...resolveServer(options.server),
@@ -488,7 +534,7 @@ export async function runMearlCli(args, options = {}) {
         else {
             process.stdout.write(`${parsed.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2)}\n`);
         }
-        return result?.action?.success === false ? 1 : 0;
+        return actionInvocationFailed(parsed.action, result) ? 1 : 0;
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));

package/dist/commands.d.ts

@@ -391,15 +391,19 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
-    readonly description: "启动本地 Chrome、创建/复用同名 AgentBay 云浏览器，或用 sessionId 接入现有云端 Session";
+    readonly description: "启动本地 Chrome、创建/复用 AgentBay 云浏览器，或通过已注册 Provider 创建浏览器实例";
     readonly params: [{
         readonly name: "name";
         readonly type: "string";
         readonly description: "实例名称，创建浏览器时必填；按 sessionId 接入时可省略";
     }, {
         readonly name: "provider";
-        readonly type: "\"local\" | \"agentbay\"";
-        readonly description: "运行环境，默认 local；传 sessionId 时自动使用 agentbay，否则 agentbay 从 AGENTBAY_KEY 创建云浏览器";
+        readonly type: "string";
+        readonly description: "运行环境，默认 local；可传 agentbay 或 mearl --help 中展示的已注册 Provider ID";
+    }, {
+        readonly name: "providerOptions";
+        readonly type: "Record<string, string>";
+        readonly description: "外部 Provider 注册时声明的实例创建参数";
     }, {
         readonly name: "sessionId";
         readonly type: "string";
@@ -457,7 +461,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string[] | \"mearl-services\" | { presets?: [\"mearl-services\"]; domains?: string[] }";
         readonly description: "从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名";
     }];
-    readonly examples: ["browser_launch --payload '{\"name\":\"cloud-a\",\"provider\":\"agentbay\",\"userAgentMode\":\"desktop\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-public\",\"provider\":\"agentbay\",\"imageId\":\"browser_latest\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"persistent\":true,\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"reuse\":\"require\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --browser '<本地浏览器 browserId>' --payload '{\"sessionId\":\"<AgentBay sessionId>\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":{\"presets\":[\"mearl-services\"],\"domains\":[\"figma.com\"]}}'", "browser_launch --payload '{\"name\":\"account-a\",\"headless\":true,\"accountId\":12345}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"account-b\",\"query\":\"test_account\",\"url\":\"https://www.taobao.com\"}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
+    readonly examples: ["browser_launch --payload '{\"provider\":\"brow\",\"providerOptions\":{}}'", "browser_launch --payload '{\"name\":\"cloud-a\",\"provider\":\"agentbay\",\"userAgentMode\":\"desktop\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-public\",\"provider\":\"agentbay\",\"imageId\":\"browser_latest\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"persistent\":true,\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"reuse\":\"require\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --browser '<本地浏览器 browserId>' --payload '{\"sessionId\":\"<AgentBay sessionId>\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":{\"presets\":[\"mearl-services\"],\"domains\":[\"figma.com\"]}}'", "browser_launch --payload '{\"name\":\"account-a\",\"headless\":true,\"accountId\":12345}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"account-b\",\"query\":\"test_account\",\"url\":\"https://www.taobao.com\"}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
 }, {
     readonly name: "browser_close";
     readonly description: "关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context";

package/dist/commands.js

@@ -296,7 +296,7 @@ export const COMMANDS = [
     },
     {
         name: 'browser_launch',
-        description: '启动本地 Chrome、创建/复用同名 AgentBay 云浏览器，或用 sessionId 接入现有云端 Session',
+        description: '启动本地 Chrome、创建/复用 AgentBay 云浏览器，或通过已注册 Provider 创建浏览器实例',
         params: [
             {
                 name: 'name',
@@ -305,8 +305,13 @@ export const COMMANDS = [
             },
             {
                 name: 'provider',
-                type: '"local" | "agentbay"',
-                description: '运行环境，默认 local；传 sessionId 时自动使用 agentbay，否则 agentbay 从 AGENTBAY_KEY 创建云浏览器',
+                type: 'string',
+                description: '运行环境，默认 local；可传 agentbay 或 mearl --help 中展示的已注册 Provider ID',
+            },
+            {
+                name: 'providerOptions',
+                type: 'Record<string, string>',
+                description: '外部 Provider 注册时声明的实例创建参数',
             },
             {
                 name: 'sessionId',
@@ -360,6 +365,7 @@ export const COMMANDS = [
             },
         ],
         examples: [
+            `browser_launch --payload '{"provider":"brow","providerOptions":{}}'`,
             `browser_launch --payload '{"name":"cloud-a","provider":"agentbay","userAgentMode":"desktop","url":"https://example.com"}'`,
             `browser_launch --payload '{"name":"cloud-public","provider":"agentbay","imageId":"browser_latest","url":"https://example.com"}'`,
             `browser_launch --payload '{"name":"cloud-login","provider":"agentbay","persistent":true,"copyCookieDomains":["example.com"],"url":"https://example.com/account"}'`,

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

@@ -123,7 +123,15 @@ export interface TdbankAccountParams {
     tabId?: number;
     identityId?: string | number;
 }
-export type BrowserStatus = 'connected' | 'running_disconnected' | 'stopped';
+export type BrowserStatus = 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
+export type BrowserTransport = 'extension' | 'cdp' | 'provider';
+export interface BrowserPairingInfo {
+    kind: 'qr';
+    url: string;
+    /** Optional human-readable or provider-specific pairing code. */
+    code?: string;
+    label?: string;
+}
 export interface BrowserSource {
     kind: 'local' | 'remote';
     connectorId?: string;
@@ -139,11 +147,28 @@ export interface BrowserInfoBase {
     source?: BrowserSource;
     extensionVersion?: string;
     nativeHostVersion?: string;
-    transport?: 'extension' | 'cdp';
+    transport?: BrowserTransport;
+    /** External control-provider identity. Present only when transport is provider. */
+    providerId?: string;
+    /** Human-readable Provider name; providerId remains the stable identity. */
+    providerName?: string;
+    providerVersion?: string;
+    providerProtocolVersion?: number;
+    /** Setup information exposed by a provider while it waits for an external device. */
+    pairing?: BrowserPairingInfo;
+}
+export type BrowserScreenshotKind = 'native' | 'reconstructed' | 'none';
+/** Browser-targeted actions that an external provider may implement. */
+export type BrowserCapabilityAction = ExtensionBrowserAction;
+/** Capabilities advertised by an external browser-control provider. */
+export interface BrowserCapabilities {
+    actions: BrowserCapabilityAction[];
+    /** Pixel fidelity of page_screenshot, or none when that action is unavailable. */
+    screenshot: BrowserScreenshotKind;
 }
 export interface RegularBrowserInfo extends BrowserInfoBase {
     type: 'regular';
-    status: 'connected';
+    status: 'connected' | 'pairing';
 }
 export interface ManagedBrowserAccount {
     accountId?: string;
@@ -152,6 +177,7 @@ export interface ManagedBrowserAccount {
 }
 export interface ManagedBrowserInfo extends BrowserInfoBase {
     type: 'managed';
+    status: 'connected' | 'running_disconnected' | 'stopped';
     provider?: 'local' | 'agentbay';
     headless: boolean;
     persistent: boolean;
@@ -199,7 +225,7 @@ export interface BrowserReleaseFailure {
 export interface BrowserReleaseResult {
     released: boolean;
     hadActiveControl: boolean;
-    transports: Array<'extension' | 'cdp'>;
+    transports: BrowserTransport[];
     affectedTabIds: number[];
     /** True when browser_release also removed a sessionId-based local AgentBay attachment. */
     detached?: boolean;
@@ -217,8 +243,10 @@ export interface CookieCopyScope {
 export interface BrowserLaunchParams {
     /** Required when creating a browser; optional when attaching by AgentBay sessionId. */
     name?: string;
-    /** Browser runtime provider. Defaults to local Chrome unless sessionId is present. */
-    provider?: 'local' | 'agentbay';
+    /** Built-in runtime or the id of a registered external Provider. */
+    provider?: string;
+    /** Creation parameters declared by a registered external Provider. */
+    providerOptions?: Record<string, string>;
     /** Attach to an exact live AgentBay session without creating or owning it. */
     sessionId?: string;
     /** AgentBay running-session reuse policy. Defaults to never. */
@@ -879,5 +907,6 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
 };
 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;
 export declare function isExtensionBrowserAction(value: unknown): value is ExtensionBrowserAction;
 export {};

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

@@ -200,6 +200,9 @@ export function isBrowserAction(value) {
 export function isBrowserCommandAction(value) {
     return typeof value === 'string' && Object.hasOwn(BROWSER_COMMAND_ACTIONS, value);
 }
+export function isBrowserCapabilityAction(value) {
+    return isExtensionBrowserAction(value);
+}
 export function isExtensionBrowserAction(value) {
     return typeof value === 'string' && Object.hasOwn(EXTENSION_BROWSER_ACTIONS, value);
 }

package/dist/index.d.ts

@@ -6,8 +6,8 @@
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } 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, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
-export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.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 type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
 export declare function tabCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;

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, 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, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.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';
 import { invoke } from './unified.js';
 export function tabCheckpoint(params = {}, options) {
     return invoke('tab_checkpoint', params, options);

package/dist/plugin.d.ts

@@ -1,5 +1,5 @@
 import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginEntry, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
+export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, } from './pluginRegistry.js';
 export type PluginOptions = UnifiedInvokeOptions;
 export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
@@ -11,6 +11,7 @@ export type PluginHandler = (input: Record<string, any>) => unknown | Promise<un
 /** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
 export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
     name: string | undefined;
+    description: string | undefined;
     version: string | undefined;
     help(namespace: string, name?: string): string;
     run(positionals: string[], payload?: unknown): Promise<unknown>;

package/dist/plugin.js

@@ -3,7 +3,7 @@ import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
 import { PluginError } from './pluginRegistry.js';
-export { assertPluginName, findPluginEntry, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
+export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
 function readPluginVersion(entry) {
     try {
         const content = readFileSync(resolve(dirname(entry), '..', 'SKILL.md'), 'utf8');
@@ -42,6 +42,7 @@ export async function loadPlugin(entry, context, pluginName) {
     let executing = false;
     let registering = true;
     let name;
+    let description;
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
         command(signature, handler, description = '') {
@@ -81,6 +82,9 @@ export async function loadPlugin(entry, context, pluginName) {
         if (module.name !== undefined && typeof module.name !== 'string')
             throw new Error('入口的 name 导出必须为字符串');
         name = module.name;
+        if (module.description !== undefined && typeof module.description !== 'string')
+            throw new Error('入口的 description 导出必须为字符串');
+        description = module.description;
         if (typeof module.default !== 'function')
             throw new Error('入口必须默认导出 register(app) 函数');
         await module.default(app);
@@ -101,6 +105,7 @@ export async function loadPlugin(entry, context, pluginName) {
     };
     return {
         name,
+        description,
         version: readPluginVersion(entry),
         help(namespace, name) {
             const selected = name ? [find(name)] : [...commands.values()];
@@ -114,7 +119,8 @@ export async function loadPlugin(entry, context, pluginName) {
                 '',
                 `  ${namespace} --payload '${JSON.stringify({ command: example.name(), input })}'`,
                 '',
-                '通用选项: --browser --connector --local --cdp --server --timeout --compact --output',
+                '常用选项: --browser --timeout --compact --output',
+                '连接或传输排障运行 mearl check --help。',
                 '插件选项: --verbose; -h, --help; -v, --version',
                 'JSON input 直接传给 handler；业务字段与校验规则见对应 skill。',
             ].join('\n');

package/dist/pluginRegistry.d.ts

@@ -2,10 +2,15 @@ export declare class PluginError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+export interface PluginRegistration {
+    entry: string;
+    description?: string;
+}
 export declare function pluginDirectory(): string;
 export declare function assertPluginName(name: string): void;
 export declare function resolvePluginEntry(target: string): string;
-export declare function registerPlugin(name: string, target: string): string;
+export declare function registerPlugin(name: string, target: string, description?: string): string;
 export declare function unregisterPlugin(name: string): boolean;
+export declare function findPluginRegistration(name: string): PluginRegistration | undefined;
 export declare function findPluginEntry(name: string): string | undefined;
 export declare function listPluginNames(): string[];

package/dist/pluginRegistry.js

@@ -40,7 +40,7 @@ export function resolvePluginEntry(target) {
         throw new PluginError('PLUGIN_ENTRY_MISSING', `入口不存在: ${absolute}（目录默认使用 scripts/main.mjs）`);
     }
 }
-export function registerPlugin(name, target) {
+export function registerPlugin(name, target, description) {
     assertPluginName(name);
     const entry = resolvePluginEntry(target);
     const directory = pluginDirectory();
@@ -48,8 +48,10 @@ export function registerPlugin(name, target) {
     const file = join(directory, `${name}.json`);
     // 每个插件独立保存，多个名称并发注册不会覆盖彼此；同名注册原子替换绑定。
     const temporary = `${file}.${randomUUID()}.tmp`;
+    const summary = description?.trim();
+    const record = { entry, ...(summary ? { description: summary } : {}) };
     try {
-        writeFileSync(temporary, `${JSON.stringify({ entry })}\n`, { mode: 0o600, flag: 'wx' });
+        writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600, flag: 'wx' });
         renameSync(temporary, file);
     }
     finally {
@@ -70,7 +72,7 @@ export function unregisterPlugin(name) {
         throw new PluginError('PLUGIN_UNINSTALL_FAILED', `无法移除插件注册: ${file}`);
     }
 }
-export function findPluginEntry(name) {
+export function findPluginRegistration(name) {
     if (!/^[a-z][a-z0-9-]*$/.test(name))
         return undefined;
     const file = join(pluginDirectory(), `${name}.json`);
@@ -87,12 +89,18 @@ export function findPluginEntry(name) {
         const record = JSON.parse(content);
         if (typeof record?.entry !== 'string' || !isAbsolute(record.entry))
             throw new Error('invalid entry');
-        return record.entry;
+        const description = typeof record.description === 'string' && record.description.trim()
+            ? record.description.trim()
+            : undefined;
+        return { entry: record.entry, ...(description ? { description } : {}) };
     }
     catch {
         throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);
     }
 }
+export function findPluginEntry(name) {
+    return findPluginRegistration(name)?.entry;
+}
 export function listPluginNames() {
     try {
         return readdirSync(pluginDirectory())

package/dist/socket.js

@@ -12,8 +12,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { StringDecoder } from 'node:string_decoder';
+import { ensureInstalledProvidersRunning } from '@mearl/provider/runtime';
 import { resolveFileRefs } from './fileRefs.js';
-import { listLiveBrowsers, findBrowser, describeBrowser } from './browserRegistry.js';
+import { listLiveBrowsers, findBrowser, describeBrowser, } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
 const require = createRequire(import.meta.url);
 export const CLIENT_VERSION = require('../package.json').version;
@@ -70,6 +71,42 @@ export function decorateBrowserListResult(result) {
         defaultBrowserId: selected?.browserId ?? null,
     };
 }
+function browserListFromProviderRecords(browsers) {
+    const providerBrowsers = browsers
+        .filter(browser => browser.transport === 'provider')
+        .map(browser => ({
+        browserId: browser.browserId,
+        name: browser.browserName,
+        type: 'regular',
+        status: browser.status === 'pairing' ? 'pairing' : 'connected',
+        transport: 'provider',
+        providerId: browser.providerId,
+        providerName: browser.providerName,
+        providerVersion: browser.providerVersion,
+        providerProtocolVersion: browser.providerProtocolVersion,
+        pairing: browser.pairing,
+    }));
+    return {
+        count: providerBrowsers.length,
+        connectedCount: providerBrowsers.filter(browser => browser.status === 'connected').length,
+        browsers: providerBrowsers,
+    };
+}
+function mergeWarnings(result, warnings) {
+    const resultWarnings = Array.isArray(result?.warnings)
+        ? result.warnings.filter((warning) => typeof warning === 'string')
+        : [];
+    const merged = [...new Set([...resultWarnings, ...warnings])];
+    return { ...result, ...(merged.length > 0 ? { warnings: merged } : {}) };
+}
+function supportsAction(browser, action) {
+    if (browser.transport === 'provider' &&
+        (action === 'get_versions' || action === 'browser_close')) {
+        return true;
+    }
+    return (browser.transport !== 'provider' ||
+        browser.capabilities?.actions.some(capability => capability === action) === true);
+}
 function selectBrowserResult(data) {
     const selector = typeof data.browser === 'string' ? data.browser.trim() : '';
     if (!selector) {
@@ -80,7 +117,8 @@ function selectBrowserResult(data) {
         };
     }
     const browsers = listLiveBrowsers();
-    const match = findBrowser(browsers, selector);
+    const controllableBrowsers = browsers.filter(browser => browser.status !== 'pairing');
+    const match = findBrowser(controllableBrowsers, selector);
     if (!match)
         throw new Error(formatNoMatchError(selector, browsers));
     setDefaultBrowser(match.browserId);
@@ -148,7 +186,11 @@ export function invoke(action, data = {}, options = {}) {
     // 统一解析 payload 顶层字段中的 `@<path>` 文件引用（所有 action 通用）
     const resolvedData = resolveFileRefs(data);
     if (action === 'browser_list') {
-        return dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(decorateBrowserListResult);
+        const hasNativeAggregator = listLiveBrowsers().some(liveBrowser => liveBrowser.transport !== 'provider');
+        const providerStartup = hasNativeAggregator
+            ? Promise.resolve([])
+            : ensureInstalledProvidersRunning();
+        return providerStartup.then(providerWarnings => dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(result => decorateBrowserListResult(mergeWarnings(result, providerWarnings))));
     }
     const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
     return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector, controlSource);
@@ -176,14 +218,24 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
         }
     }
     const browsers = listLiveBrowsers();
+    const controllableBrowsers = browsers.filter(browser => browser.status !== 'pairing');
     // Explicit target: must match a live browser; do not silently fall back.
     if (selector) {
         const match = findBrowser(browsers, selector);
         if (!match) {
             throw new Error(formatNoMatchError(selector, browsers));
         }
+        if (match.status === 'pairing' && action !== 'get_versions' && action !== 'browser_close') {
+            throw new Error(`Browser ${describeBrowser(match)} is waiting for device pairing`);
+        }
+        if (transport === 'cdp' && match.transport === 'provider') {
+            throw new Error(`Browser ${describeBrowser(match)} does not support the CDP transport`);
+        }
+        if (!supportsAction(match, action)) {
+            throw new Error(`Browser ${describeBrowser(match)} does not support ${action}`);
+        }
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource);
+            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource, match.providerBrowserId);
         }
         catch (error) {
             if (isConnError(error) || isSocketSandboxError(error)) {
@@ -196,18 +248,25 @@ 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.
-    if (browsers.length > 0) {
+    const routableBrowsers = controllableBrowsers.filter(browser => !(transport === 'cdp' && browser.transport === 'provider') && supportsAction(browser, action));
+    if (routableBrowsers.length > 0) {
+        const target = routableBrowsers[0];
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, browsers[0].socketPath, controlSource);
+            return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.providerBrowserId);
         }
         catch (error) {
             if (isSocketSandboxError(error)) {
-                throw new Error(formatConnectError(error, browsers[0].socketPath), { cause: error });
+                throw new Error(formatConnectError(error, target.socketPath), {
+                    cause: error,
+                });
             }
             if (!isConnError(error))
                 throw error;
         }
     }
+    if (action === 'browser_list' && browsers.some(browser => browser.transport === 'provider')) {
+        return browserListFromProviderRecords(browsers);
+    }
     return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, /* isRetry */ false);
 }
 /** Legacy well-known socket, auto-spawning a native-host on ENOENT and retrying once. */
@@ -229,8 +288,11 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
                     /* isRetry */ true);
                 }
                 const browsers = listLiveBrowsers();
-                if (browsers.length > 0) {
-                    return invokeOnce(action, data, timeoutSec, transport, browsers[0].socketPath, controlSource);
+                const target = browsers.find(browser => browser.status !== 'pairing' &&
+                    !(transport === 'cdp' && browser.transport === 'provider') &&
+                    supportsAction(browser, action));
+                if (target) {
+                    return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.providerBrowserId);
                 }
                 return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, 
                 /* isRetry */ true);
@@ -241,7 +303,7 @@ 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) {
+function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource, providerBrowserId) {
     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) {
@@ -282,6 +344,8 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSour
             };
             if (transport)
                 message.transport = transport;
+            if (providerBrowserId)
+                message.browserId = providerBrowserId;
             socket.write(JSON.stringify(message) + '\n');
         });
         socket.on('data', chunk => {

package/dist/unified.js

@@ -302,6 +302,9 @@ export class UnifiedClient {
             ? result.browsers
             : [];
         const browsers = rawBrowsers.map(browser => decorateBrowser(browser, source));
+        const resultWarnings = Array.isArray(result?.warnings)
+            ? result.warnings.filter((warning) => typeof warning === 'string')
+            : [];
         return {
             count: browsers.length,
             connectedCount: browsers.filter(browser => browser.status === 'connected').length,
@@ -312,6 +315,7 @@ export class UnifiedClient {
                 })
                 : null,
             browsers,
+            ...(resultWarnings.length > 0 ? { warnings: resultWarnings } : {}),
         };
     }
     applyConfiguredDefault(listing) {
@@ -374,6 +378,8 @@ export class UnifiedClient {
                 connectorName: connector.name,
             }));
         }
+        for (const listing of listings)
+            warnings.push(...(listing.warnings ?? []));
         const browsers = listings.flatMap(listing => listing.browsers);
         const defaults = listings
             .map(listing => listing.defaultBrowserId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,8 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.12.0"
+    "@mearl/cloud-types": "2.13.0",
+    "@mearl/provider": "2.13.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",