@mearl/client 2.4.0 → 2.5.1

package/README.md

@@ -62,6 +62,7 @@ mearl <action> --help
 mearl browser_launch --payload '{"name":"account-a","accountId":12345}'
 mearl browser_launch --payload '{"name":"account-b","query":"test_account"}'
 mearl browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
+mearl browser_launch --payload '{"name":"cloud-login","provider":"agentbay","persistent":true,"userAgentMode":"desktop","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'
 mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
 mearl browser_list
 mearl browser_release
@@ -104,7 +105,7 @@ mearl browser_release
 
 `browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时使用，不作为普通任务收尾。它会释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。
 
-托管浏览器使用独立 Profile 和动态 CDP 端口。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，新实例可以使用 `headless: true`（默认）完成测试账号登录。`copyCookieDomains` 可把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会出现在命令结果或日志中；`userAgentMode: "desktop"` 可让实例使用匹配本机 Chrome 版本的桌面 UA。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
+托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`persistent: true` 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。`deleteProfile: true` 会显式删除对应 Profile 或 Context。`copyCookieDomains` 可在首次启动或需要刷新登录态时把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 通过 `agentbayImageId`、`agentbayContextId` 和 `agentbayContextName` 返回 AgentBay 实例配置；当服务返回无影浏览器串流入口时，还会通过 `agentbayAccessUrl` 暴露，该地址可能包含临时访问凭据，应按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 
 ## 架构
 

package/dist/actionTimeouts.js

@@ -1,5 +1,7 @@
 import { PAGE_ACT_ACTIONS } from './generated-browser-action-protocol.js';
 const SEND_REQUEST_FILE_TRANSFER_TIMEOUT_MS = 120_000;
+// AgentBay context sync can poll for about 12 minutes before session deletion waits up to 5 more.
+const BROWSER_CLOSE_TIMEOUT_SEC = 18 * 60;
 function boundedNumber(value, fallback, minimum, maximum) {
     const numeric = Number(value);
     if (!Number.isFinite(numeric))
@@ -35,7 +37,9 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
         return Math.max(fallback, 40);
     if (action === 'browser_launch')
         return Math.max(fallback, 90);
-    if (action === 'browser_close' || action === 'tdbank_account')
+    if (action === 'browser_close')
+        return Math.max(fallback, BROWSER_CLOSE_TIMEOUT_SEC);
+    if (action === 'tdbank_account')
         return Math.max(fallback, 20);
     if (action === 'run_actions') {
         const actions = Array.isArray(data.actions) ? data.actions : [{}];

package/dist/browserRegistry.js

@@ -68,9 +68,14 @@ export function findBrowser(browsers, selector) {
     const byId = browsers.find(b => b.browserId.toLowerCase() === sel);
     if (byId)
         return byId;
-    const byExactName = browsers.find(b => b.browserName.toLowerCase() === sel);
-    if (byExactName)
-        return byExactName;
+    const exactNameMatches = browsers.filter(b => b.browserName.toLowerCase() === sel);
+    if (exactNameMatches.length > 1) {
+        throw new Error(`Browser name "${selector.trim()}" is ambiguous. Use a full browserId: ${exactNameMatches
+            .map(browser => browser.browserId)
+            .join(', ')}`);
+    }
+    if (exactNameMatches[0])
+        return exactNameMatches[0];
     return (browsers.find(b => b.browserId.toLowerCase().includes(sel) || b.browserName.toLowerCase().includes(sel)) ?? null);
 }
 /** Human-readable one-line label for a browser, used in listings and errors. */

package/dist/commands.d.ts

@@ -294,7 +294,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["tdbank_account --payload '{\"operation\":\"current\"}'", "tdbank_account --payload '{\"operation\":\"list\",\"refresh\":true}'", "tdbank_account --payload '{\"operation\":\"switch\",\"accountId\":12345}'", "tdbank_account --payload '{\"operation\":\"borrow\",\"query\":\"test_account\"}'"];
 }, {
     readonly name: "browser_list";
-    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息";
+    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像、持久化 Context 和串流地址";
     readonly examples: ["browser_list"];
 }, {
     readonly name: "browser_release";
@@ -302,24 +302,32 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
-    readonly description: "启动独立 Chrome，可在新实例中通过 TDBank 登录指定账号";
+    readonly description: "启动本地 Chrome 或 AgentBay 云浏览器，并通过 CDP 接入 Mearl";
     readonly params: [{
         readonly name: "name";
         readonly type: "string";
         readonly required: true;
         readonly description: "实例名称，最多 64 个字符";
+    }, {
+        readonly name: "provider";
+        readonly type: "\"local\" | \"agentbay\"";
+        readonly description: "运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器";
+    }, {
+        readonly name: "imageId";
+        readonly type: "string";
+        readonly description: "AgentBay 镜像别名或具体镜像 ID；默认使用已验证的 Linux Browser Use 内网镜像";
     }, {
         readonly name: "headless";
         readonly type: "boolean";
-        readonly description: "是否无头运行，默认 true";
+        readonly description: "本地 provider 是否无头运行，默认 true；AgentBay 固定为 false，不支持 true";
     }, {
         readonly name: "userAgentMode";
         readonly type: "\"default\" | \"desktop\"";
-        readonly description: "UA 模式：default 使用 Chrome 默认 UA，desktop 使用匹配本机版本的桌面 UA";
+        readonly description: "UA 模式：default 使用 provider 默认 UA；desktop 本地使用匹配本机版本的 UA，AgentBay 复用控制浏览器的桌面 UA";
     }, {
         readonly name: "persistent";
         readonly type: "boolean";
-        readonly description: "关闭后是否保留独立 Profile，默认 false";
+        readonly description: "关闭后是否保留浏览器状态，默认 false；本地保留 Profile，AgentBay 同名实例复用云端 Context";
     }, {
         readonly name: "url";
         readonly type: "string";
@@ -351,12 +359,12 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "copyCookieDomains";
         readonly type: "string[]";
-        readonly description: "从控制浏览器复制到新实例的 Cookie 域名列表，可与 TDBank 登录组合";
+        readonly description: "从控制浏览器复制到本地或 AgentBay 新实例的 Cookie 域名列表，可与本地 TDBank 登录组合";
     }];
-    readonly examples: ["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 '{\"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\":\"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";
+    readonly description: "关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context";
     readonly params: [{
         readonly name: "browser";
         readonly type: "string";
@@ -365,9 +373,9 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "deleteProfile";
         readonly type: "boolean";
-        readonly description: "强制删除持久化 Profile，默认 false";
+        readonly description: "强制删除持久化本地 Profile 或 AgentBay Context，默认 false";
     }];
-    readonly examples: ["browser_close --payload '{\"browser\":\"managed:account-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
+    readonly examples: ["browser_close --payload '{\"browser\":\"managed:account-a\"}'", "browser_close --payload '{\"browser\":\"managed:agentbay:cloud-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
 }, {
     readonly name: "tab_open";
     readonly description: "打开或按 URL 规则复用 Tab，并等待新页面加载完成";

package/dist/commands.js

@@ -210,7 +210,7 @@ export const COMMANDS = [
     // ── 浏览器 ────────────────────────────────────────────────────────────────
     {
         name: 'browser_list',
-        description: '列出所有浏览器及其连接状态、类型和托管实例信息',
+        description: '列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像、持久化 Context 和串流地址',
         examples: ['browser_list'],
     },
     {
@@ -220,19 +220,33 @@ export const COMMANDS = [
     },
     {
         name: 'browser_launch',
-        description: '启动独立 Chrome，可在新实例中通过 TDBank 登录指定账号',
+        description: '启动本地 Chrome 或 AgentBay 云浏览器，并通过 CDP 接入 Mearl',
         params: [
             { name: 'name', type: 'string', required: true, description: '实例名称，最多 64 个字符' },
-            { name: 'headless', type: 'boolean', description: '是否无头运行，默认 true' },
+            {
+                name: 'provider',
+                type: '"local" | "agentbay"',
+                description: '运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器',
+            },
+            {
+                name: 'imageId',
+                type: 'string',
+                description: 'AgentBay 镜像别名或具体镜像 ID；默认使用已验证的 Linux Browser Use 内网镜像',
+            },
+            {
+                name: 'headless',
+                type: 'boolean',
+                description: '本地 provider 是否无头运行，默认 true；AgentBay 固定为 false，不支持 true',
+            },
             {
                 name: 'userAgentMode',
                 type: '"default" | "desktop"',
-                description: 'UA 模式：default 使用 Chrome 默认 UA，desktop 使用匹配本机版本的桌面 UA',
+                description: 'UA 模式：default 使用 provider 默认 UA；desktop 本地使用匹配本机版本的 UA，AgentBay 复用控制浏览器的桌面 UA',
             },
             {
                 name: 'persistent',
                 type: 'boolean',
-                description: '关闭后是否保留独立 Profile，默认 false',
+                description: '关闭后是否保留浏览器状态，默认 false；本地保留 Profile，AgentBay 同名实例复用云端 Context',
             },
             { name: 'url', type: 'string', description: '登录完成后打开的初始页面' },
             { name: 'executablePath', type: 'string', description: '自定义 Chrome 可执行文件路径' },
@@ -252,10 +266,13 @@ export const COMMANDS = [
             {
                 name: 'copyCookieDomains',
                 type: 'string[]',
-                description: '从控制浏览器复制到新实例的 Cookie 域名列表，可与 TDBank 登录组合',
+                description: '从控制浏览器复制到本地或 AgentBay 新实例的 Cookie 域名列表，可与本地 TDBank 登录组合',
             },
         ],
         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":"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"}'`,
@@ -264,7 +281,7 @@ export const COMMANDS = [
     },
     {
         name: 'browser_close',
-        description: '关闭指定托管浏览器并按策略清理独立 Profile',
+        description: '关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context',
         params: [
             {
                 name: 'browser',
@@ -272,10 +289,15 @@ export const COMMANDS = [
                 required: true,
                 description: '托管浏览器的 browserId 或名称',
             },
-            { name: 'deleteProfile', type: 'boolean', description: '强制删除持久化 Profile，默认 false' },
+            {
+                name: 'deleteProfile',
+                type: 'boolean',
+                description: '强制删除持久化本地 Profile 或 AgentBay Context，默认 false',
+            },
         ],
         examples: [
             `browser_close --payload '{"browser":"managed:account-a"}'`,
+            `browser_close --payload '{"browser":"managed:agentbay:cloud-a"}'`,
             `browser_close --payload '{"browser":"account-b","deleteProfile":true}'`,
         ],
     },

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

@@ -137,9 +137,19 @@ export interface ManagedBrowserAccount {
 }
 export interface ManagedBrowserInfo extends BrowserInfoBase {
     type: 'managed';
+    provider?: 'local' | 'agentbay';
     headless: boolean;
     persistent: boolean;
-    cdpPort: number;
+    cdpPort?: number;
+    agentbaySessionId?: string;
+    /** AgentBay image used to create the session. */
+    agentbayImageId?: string;
+    /** Persistent AgentBay browser context ID when enabled for this instance. */
+    agentbayContextId?: string;
+    /** Stable AgentBay browser context name derived from the managed browser name. */
+    agentbayContextName?: string;
+    /** Browser-accessible AgentBay session URL when returned by the provider. */
+    agentbayAccessUrl?: string;
     createdAt: string;
     account?: ManagedBrowserAccount;
     copiedCookies?: {
@@ -178,7 +188,13 @@ export interface BrowserReleaseResult {
 }
 export interface BrowserLaunchParams {
     name: string;
+    /** Browser runtime provider. Defaults to local Chrome. */
+    provider?: 'local' | 'agentbay';
+    /** AgentBay image alias or concrete image ID. Only supported by the AgentBay provider. */
+    imageId?: string;
+    /** Local Chrome defaults to true. AgentBay is fixed to false and rejects true. */
     headless?: boolean;
+    /** Desktop mode uses the local Chrome UA or copies the selected control browser UA to AgentBay. */
     userAgentMode?: 'default' | 'desktop';
     persistent?: boolean;
     executablePath?: string;
@@ -188,6 +204,7 @@ export interface BrowserLaunchParams {
     site?: string | number;
     query?: string;
     tabId?: number;
+    /** Copy matching cookies from the selected control browser before opening url. */
     copyCookieDomains?: string[];
 }
 export interface BrowserCloseParams {

package/dist/socket.js

@@ -41,8 +41,16 @@ export function getDefaultBrowser() {
 function findConnectedBrowser(items, selector) {
     const normalized = selector.trim().toLowerCase();
     const connected = items.filter(item => item.status === 'connected');
-    return (connected.find(item => String(item.browserId).toLowerCase() === normalized) ??
-        connected.find(item => String(item.name).toLowerCase() === normalized) ??
+    const byId = connected.find(item => String(item.browserId).toLowerCase() === normalized);
+    if (byId)
+        return byId;
+    const exactNameMatches = connected.filter(item => String(item.name).toLowerCase() === normalized);
+    if (exactNameMatches.length > 1) {
+        throw new Error(`Browser name "${selector.trim()}" is ambiguous. Use a full browserId: ${exactNameMatches
+            .map(item => String(item.browserId))
+            .join(', ')}`);
+    }
+    return (exactNameMatches[0] ??
         connected.find(item => String(item.browserId).toLowerCase().includes(normalized) ||
             String(item.name).toLowerCase().includes(normalized)) ??
         null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "Client SDK & CLI for Mearl — communicate with Chrome Extension via Unix Socket",
   "type": "module",
   "main": "dist/index.js",