@mearl/client 2.5.0 → 2.5.1

package/README.md

@@ -62,7 +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","userAgentMode":"desktop","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'
+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
@@ -105,7 +105,7 @@ mearl browser_release
 
 `browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时使用，不作为普通任务收尾。它会释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。
 
-托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`copyCookieDomains` 可把控制浏览器指定域的 Cookie 复制到本地或 AgentBay 新实例，Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 通过 `agentbayImageId` 返回实例的实际镜像；当服务返回无影浏览器串流入口时，还会通过 `agentbayAccessUrl` 暴露，该地址可能包含临时访问凭据，应按敏感信息处理。完整设计见 [托管浏览器与 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/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: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含 agentbayImageId 和 agentbayAccessUrl";
+    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像、持久化 Context 和串流地址";
     readonly examples: ["browser_list"];
 }, {
     readonly name: "browser_release";
@@ -327,7 +327,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "persistent";
         readonly type: "boolean";
-        readonly description: "关闭后是否保留独立 Profile，默认 false";
+        readonly description: "关闭后是否保留浏览器状态，默认 false；本地保留 Profile，AgentBay 同名实例复用云端 Context";
     }, {
         readonly name: "url";
         readonly type: "string";
@@ -361,10 +361,10 @@ export declare const COMMANDS: readonly [{
         readonly type: "string[]";
         readonly description: "从控制浏览器复制到本地或 AgentBay 新实例的 Cookie 域名列表，可与本地 TDBank 登录组合";
     }];
-    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\",\"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 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";
@@ -373,7 +373,7 @@ 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\":\"managed:agentbay:cloud-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
 }, {

package/dist/commands.js

@@ -210,7 +210,7 @@ export const COMMANDS = [
     // ── 浏览器 ────────────────────────────────────────────────────────────────
     {
         name: 'browser_list',
-        description: '列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含 agentbayImageId 和 agentbayAccessUrl',
+        description: '列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像、持久化 Context 和串流地址',
         examples: ['browser_list'],
     },
     {
@@ -246,7 +246,7 @@ export const COMMANDS = [
             {
                 name: 'persistent',
                 type: 'boolean',
-                description: '关闭后是否保留独立 Profile，默认 false',
+                description: '关闭后是否保留浏览器状态，默认 false；本地保留 Profile，AgentBay 同名实例复用云端 Context',
             },
             { name: 'url', type: 'string', description: '登录完成后打开的初始页面' },
             { name: 'executablePath', type: 'string', description: '自定义 Chrome 可执行文件路径' },
@@ -272,7 +272,7 @@ export const COMMANDS = [
         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","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'`,
+            `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"}'`,
@@ -281,7 +281,7 @@ export const COMMANDS = [
     },
     {
         name: 'browser_close',
-        description: '关闭指定托管浏览器并按策略清理独立 Profile',
+        description: '关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context',
         params: [
             {
                 name: 'browser',
@@ -289,7 +289,11 @@ 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"}'`,

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

@@ -144,6 +144,10 @@ export interface ManagedBrowserInfo extends BrowserInfoBase {
     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;

package/package.json

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