@mearl/client 2.22.1 → 2.22.2

package/README.md

@@ -72,6 +72,77 @@ mearl browser_list
 mearl browser_release
 ```
 
+### Agent 脚本
+
+`mearl run` 从 stdin 或 `--file <path>` 读取 JavaScript，预注入 `mearl` SDK，支持顶层 `await`、条件、循环和数据处理，无需在任务目录安装依赖：
+
+```bash
+mearl run --session new <<'JS'
+const tab = await mearl.tabOpen({ url: 'https://example.com', reuse: 'prefer' });
+console.log({ tabId: tab.tabId, session: mearl.session });
+console.log(await mearl.pageSnapshot({ tabId: tab.tabId, mode: 'viewport' }));
+JS
+
+mearl run --session '<sessionId>' --file /absolute/path/next-step.mjs
+```
+
+方法名与 SDK 一致，例如 `mearl.pageClick(params, options?)`、`mearl.getRequests(params, options?)`、
+`mearl.tabList(options?)`，通用调用使用 `mearl.invoke(action, payload, options?)`。
+参数和返回值沿用普通 action，可查 `mearl <action> --help`；动作失败仍以 `action.success`、
+`stage` 和 `attempt` 表达，由脚本判断后续逻辑。`console.log` 输出必要结果，`console.error` 输出诊断；
+返回数据不会自动打印。`run_actions` 适合无需判断的紧密序列；脚本适合结果可由代码判断的组合流程。
+需要模型理解页面时，输出最小观察并在下一轮继续。
+
+脚本用 `help` 查询现有命令定义，返回文本由调用方按需输出；CLI `--help` 与脚本共用同一份参数、结果说明、约束和示例。
+
+```javascript
+console.log(await mearl.help()); // 方法与已注册插件清单
+console.log(await mearl.help('pageClick')); // 也接受 page_click
+console.log(await mearl.help({ plugin: 'yuque', command: 'read' }));
+
+const result = await mearl.invokePlugin('yuque', { command: 'read', input: { url: '文档链接' } });
+console.log(mearl.structure(result));
+```
+
+`structure(value, options?)` 同步提取已取得结果的结构，叶子值替换为类型；默认深度 5、每对象 50 个字段、
+每数组 1 个样本、总计 2000 个节点，可通过 `maxDepth`、`maxKeys`、`arraySamples`、`maxNodes` 调整。
+输出包含数组总长度与样本，遇到循环引用、访问器或资源限制会标记；样本不保证覆盖所有可选字段或不同数组元素，
+业务含义以命令帮助为准。普通 SDK 同样导出 `structure`，它与请求 `keysOnly` 使用相同的提取逻辑；
+`keysOnly` 也遵循上述默认字段和节点上限，超出部分会标记截断。
+插件帮助在隔离进程中加载注册信息，不执行所查询的业务命令。
+
+已注册 Skill 命令也可直接组合，命令名和输入来自该插件的 `--help`：
+
+```javascript
+const result = await mearl.invokePlugin('yuque', {
+  command: 'read',
+  input: { url: 'https://aliyuque.antfin.com/group/book/doc' },
+});
+console.log(result);
+```
+
+脚本的 `--browser`、`--session`、`--connector`、`--local`、`--cdp` 由浏览器 API 和插件调用继承；
+单次调用的 `options` 可覆盖。`--server` 指定 cloud-server。`--session new` 成功建立会话后，
+后续调用自动使用返回的 ID，`mearl.session` 和 CLI stderr 同时提供会话信息。
+先 await 建立会话的浏览器调用，再执行并发或 Skill 命令。脚本结束断开 SDK 连接，控制会话保留；
+按任务生命周期显式调用 `mearl.browserRelease`。每轮重建 JS 变量，使用已返回的 `sessionId` 和 `tabId` 继续任务。
+
+每次脚本在独立 Node.js 进程运行，继承调用方的工作目录和环境，拥有该宿主的 Node.js 权限；
+它不是安全沙箱。用 `await import('node:fs/promises')` 等动态 import 加载模块；
+`--file` 的内容也作为脚本函数执行，不支持静态 `import` / `export`。本地模块建议使用绝对文件 URL。
+`window` / `document` 仅在 `mearl.pageEval` 的页面表达式中可用。插件 registry、本地文件和身份认证均属于运行 CLI 的宿主。
+
+`--timeout <seconds>` 限制整个脚本，默认 60 秒；单次 API 的 `options.timeoutSec` 限制该调用。
+stdout 与 stderr 合计最多 256 KiB，源码最多 1 MiB。await 所有 SDK 调用；漏写 await、超时、取消或脚本异常以退出码 1 结束，
+输入错误以 2 结束。取消和超时停止脚本及其进程组，并向仍在等待的 Skill 调用传递取消信号；已派发的浏览器或业务操作可能继续生效，
+错误中的 `pendingActions` / `mayHaveLateEffects` 用于判断是否需要核验现场，不能直接重跑整段脚本。
+Skill 命令使用既有隔离执行器，stdout/stderr 计入脚本输出上限；异常诊断也会按大小裁剪。
+执行结果的 `success` 仅表示脚本正常完成，动作结果与业务成功仍需由代码检查。
+
+SDK 宿主可从 `@mearl/client/script` 导入 `executeScript(code, options)`，得到
+`{ success, stdout, stderr, session?, error?, executionStopped, mayHaveLateEffects, pendingActions }`。
+它支持 `signal` 取消和 `executionTimeoutSec`，与 CLI、MCP 共用执行器。
+
 ### 控制会话与文件
 
 多步骤任务首次 `tab_open` 或 `page_snapshot` 使用 `--session new`，响应在原结果旁附带 `session`，后续用其 `sessionId` 自动路由，无需额外创建/查询 action。Session 绑定一个浏览器与传输；页面首次使用自动关联，复用页面与新建页面分别记录。同一页面只允许一个会话控制，旧调用不能绕过占用；Session 不隔离 Cookie 或存储。

package/dist/cli.js

@@ -6,6 +6,7 @@ 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 { formatCommandHelp } from './commandHelp.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
 import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugins/sdk/plugin.js';
@@ -59,6 +60,11 @@ const CATEGORIES = [
     },
 ];
 const BUILTIN_COMMANDS = [
+    {
+        name: 'run',
+        description: '执行预注入 mearl SDK 的 Node.js 脚本',
+        examples: ['run --file task.mjs'],
+    },
     {
         name: 'check',
         description: '检查指定浏览器，未指定时检查全部已连接浏览器',
@@ -120,6 +126,7 @@ function printUsage(commandName, version) {
         `  ${commandName} <action> [选项]`,
         `  ${commandName} <action> --help`,
         `  ${commandName} check [选项]`,
+        `  ${commandName} run [--file <path>] [选项]`,
         '',
         '常用选项：',
         '  --payload <json>      直接传入 JSON 参数',
@@ -135,6 +142,7 @@ function printUsage(commandName, version) {
         '  -v, --version         查看版本',
         '',
         '内置命令：',
+        `  ${'run'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}执行 Node.js 脚本，支持浏览器 API 与 Skill 命令`,
         `  ${'check'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}检查指定浏览器，未指定时检查全部已连接浏览器`,
     ];
     for (const category of CATEGORIES) {
@@ -300,46 +308,6 @@ function printAdvancedCommandHelp(commandName, action) {
         '结果包含 count 与 connectors；每项包含 ID、名称、可选版本、连接时间和最后心跳。',
     ].join('\n'));
 }
-function printCommandHelp(commandName, command) {
-    const payloadUsage = command.params?.length ? ' [--payload <json> | --payload-file <path>]' : '';
-    const lines = [
-        `${command.name}`,
-        `  ${command.description}`,
-        '',
-        '用法：',
-        `  ${commandName} ${command.name}${payloadUsage} [常用选项]`,
-        '',
-    ];
-    if (command.params?.length) {
-        lines.push('参数（--payload JSON 字段）：');
-        for (const parameter of command.params) {
-            const required = parameter.required ? '必填' : '可选';
-            lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
-            for (const detail of parameter.details ?? [])
-                lines.push(`    ${detail}`);
-        }
-        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.notes?.length) {
-        lines.push('约束与行为：', ...command.notes.map(note => `  ${note}`), '');
-    }
-    if (command.result?.length) {
-        lines.push('结果：', ...command.result.map(line => `  ${line}`), '');
-    }
-    if (command.examples?.length) {
-        lines.push('示例：');
-        for (const example of command.examples)
-            lines.push(`  ${commandName} ${example}`);
-    }
-    lines.push('', `运行 ${commandName} --help 查看常用选项。`);
-    console.error(lines.join('\n'));
-}
 function printUnknownCommand(commandName, args) {
     const input = commandInput(args) || args[0] || '';
     const suggestions = findCommandSuggestions(args, SUGGESTABLE_COMMANDS);
@@ -605,6 +573,10 @@ function writeOutput(action, result, outputPath) {
 export async function runMearlCli(args, options = {}) {
     const commandName = options.commandName ?? 'mearl';
     const clientVersion = options.clientVersion ?? CLIENT_VERSION;
+    if (args[0] === 'run') {
+        const { runScriptCli } = await import('./scriptCli.js');
+        return runScriptCli(args.slice(1), commandName);
+    }
     if (args[0] === 'capture_checkpoint')
         args = ['tab_checkpoint', ...args.slice(1)];
     const provider = installedProvider(args[0]);
@@ -641,7 +613,7 @@ export async function runMearlCli(args, options = {}) {
     if (args.includes('--help') || args.includes('-h')) {
         const command = COMMAND_MAP.get(args[0]);
         if (command)
-            printCommandHelp(commandName, command);
+            console.error(formatCommandHelp(commandName, command));
         else if (args[0] === 'check')
             printCheckHelp(commandName);
         else if (ADVANCED_BUILTIN_COMMANDS.has(args[0])) {

package/dist/commandHelp.d.ts

@@ -0,0 +1,3 @@
+import { type CommandDef } from './commands.js';
+export declare function getCommandHelp(target?: string): string;
+export declare function formatCommandHelp(commandName: string, command: CommandDef): string;

package/dist/commandHelp.js

@@ -0,0 +1,79 @@
+import { COMMANDS, COMMAND_MAP } from './commands.js';
+import { SDK_METHOD_ACTIONS, SDK_OPTIONS_ONLY_METHODS } from './sdkMethods.js';
+import { listPluginNames } from './plugins/pluginRegistry.js';
+const HELPER_HELP = {
+    invoke: 'invoke(action, payload?, options?) — 调用浏览器 action，返回普通 action 的原始结果',
+    invokePlugin: 'invokePlugin(name, { command, input }, options?) — 调用已注册 Skill 命令，返回该命令的原始结果',
+    help: 'help(methodOrAction?) / help({ plugin, command? }) — 返回共享命令帮助文本；无参数时列出方法；用 console.log 输出',
+    structure: 'structure(value, { maxDepth=5, maxKeys=50, arraySamples=1, maxNodes=2000 }?) — 同步返回有界结构样本；叶子值替换为类型，标注数组样本、循环引用和截断；不能证明未采样内容或业务语义',
+    saveArtifact: 'saveArtifact(artifact, absolutePath, options?) — 保存浏览器文件产物，返回保存结果',
+    selectBrowser: 'selectBrowser({ browser? }, options?) — 选择默认目标；返回 { selected }；browser 使用 browserList 返回的 ID 或名称，空字符串清除默认目标',
+};
+export function getCommandHelp(target) {
+    if (!target)
+        return [
+            ...COMMANDS.map((command) => `${[...SDK_METHOD_ACTIONS].find(([, action]) => action === command.name)?.[0] ?? command.name} (${command.name}) — ${command.summary ?? command.description}`),
+            ...Object.values(HELPER_HELP),
+            ...listPluginNames().map(plugin => `Skill ${plugin} — help({ plugin: '${plugin}' })`),
+        ].join('\n');
+    if (Object.hasOwn(HELPER_HELP, target))
+        return HELPER_HELP[target];
+    const resolved = SDK_METHOD_ACTIONS.get(target) ?? target;
+    const action = resolved === 'capture_checkpoint' ? 'tab_checkpoint' : resolved;
+    if (action === 'browser_select_browser')
+        return HELPER_HELP.selectBrowser;
+    const command = COMMAND_MAP.get(action);
+    if (!command)
+        throw new Error(`Unknown command or SDK method: ${target}`);
+    return formatCommandHelp('mearl', command);
+}
+export function formatCommandHelp(commandName, command) {
+    const payloadUsage = command.params?.length ? ' [--payload <json> | --payload-file <path>]' : '';
+    const lines = [
+        `${command.name}`,
+        `  ${command.description}`,
+        '',
+        '用法：',
+        `  ${commandName} ${command.name}${payloadUsage} [常用选项]`,
+        '',
+    ];
+    const method = [...SDK_METHOD_ACTIONS].find(([, action]) => action === command.name)?.[0];
+    if (method)
+        lines.push('SDK：', ...(method === 'browserRelease'
+            ? [
+                '  await mearl.browserRelease(options?)',
+                '  await mearl.browserRelease(params, options)',
+            ]
+            : [
+                `  await mearl.${method}(${SDK_OPTIONS_ONLY_METHODS.has(method) ? 'options?' : 'params, options?'})`,
+            ]), '');
+    if (command.params?.length) {
+        lines.push('参数（--payload JSON 字段）：');
+        for (const parameter of command.params) {
+            const required = parameter.required ? '必填' : '可选';
+            lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
+            for (const detail of parameter.details ?? [])
+                lines.push(`    ${detail}`);
+        }
+        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.notes?.length) {
+        lines.push('约束与行为：', ...command.notes.map(note => `  ${note}`), '');
+    }
+    if (command.result?.length) {
+        lines.push('结果：', ...command.result.map(line => `  ${line}`), '');
+    }
+    if (command.examples?.length) {
+        lines.push('示例：');
+        for (const example of command.examples)
+            lines.push(`  ${commandName} ${example}`);
+    }
+    lines.push('', `运行 ${commandName} --help 查看常用选项。`);
+    return lines.join('\n');
+}

package/dist/commands.d.ts

@@ -613,7 +613,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly notes: readonly ["selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。", "原生 select 可按 option 文本点击；checkbox/radio 返回 controlState.checkedBefore/checkedAfter。"];
     readonly examples: ["page_click --payload '{\"tabId\":12345,\"text\":\"提交\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\"@e3\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".submit-btn\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":336,\"y\":117}}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":196,\"y\":240},\"coordinateSpace\":\"active-frame\"}'"];
 }, {
@@ -643,7 +643,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly notes: readonly ["起点会自动滚入视口，终点必须同时位于当前视口；否则先滚动页面。隐藏页 auto 使用 DOM，不切换活动页。"];
     readonly examples: ["page_drag --payload '{\"tabId\":12345,\"from\":{\"x\":350,\"y\":80},\"to\":{\"x\":80,\"y\":80}}'", "page_drag --payload '{\"tabId\":12345,\"from\":\"@e3\",\"to\":\"#drop-zone\",\"dragMode\":\"mouse\"}'"];
 }, {
@@ -669,7 +669,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly examples: ["page_type --payload '{\"tabId\":12345,\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
 }, {
     readonly name: "page_hover";
@@ -685,7 +685,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly examples: ["page_hover --payload '{\"tabId\":12345,\"selector\":\".nav-menu\"}'"];
 }, {
     readonly name: "page_scroll";
@@ -713,7 +713,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data 返回 moved、atTop/atBottom、scrollYBefore/After、maxScrollY、resolvedContainer 和 ancestorDistance；自动发现的内部容器提供可复用 containerSelector。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data 返回 moved、atTop/atBottom、scrollYBefore/After、maxScrollY、resolvedContainer 和 ancestorDistance；自动发现的内部容器提供可复用 containerSelector。"];
     readonly examples: ["page_scroll --payload '{\"tabId\":12345,\"direction\":\"down\"}'", "page_scroll --payload '{\"tabId\":12345,\"direction\":\"bottom\"}'", "page_scroll --payload '{\"tabId\":12345,\"selector\":\".virtual-list\",\"direction\":\"down\",\"distance\":800}'", "page_scroll --payload '{\"tabId\":12345,\"selector\":\"@e8\",\"containerPolicy\":\"nearest\",\"direction\":\"bottom\"}'"];
 }, {
     readonly name: "page_runtime";
@@ -821,7 +821,7 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly notes: readonly ["隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。"];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
     readonly examples: ["page_press --payload '{\"tabId\":12345,\"key\":\"Enter\"}'"];
 }, {
     readonly name: "page_wait";
@@ -911,7 +911,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly notes: readonly ["直接写入 input[type=file]，不依赖 file chooser；隐藏的文件节点也可上传。外部 Provider 的文件中转能力查询 mearl <providerId>。"];
     readonly examples: ["page_upload --payload '{\"tabId\":12345,\"selector\":\"#file-input\",\"filePaths\":[\"/Users/me/photo.jpg\"]}'"];
 }, {

package/dist/commands.js

@@ -30,7 +30,7 @@ const PAGE_OBSERVE_PARAM = {
 const PAGE_ACTION_RESULT = [
     '默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。',
     'observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。',
-    '包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。',
+    '包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。',
     'observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。',
     'effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。',
     'fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。',

package/dist/generated/data-structure.d.ts

@@ -0,0 +1,8 @@
+export interface StructureOptions {
+    maxDepth?: number;
+    maxKeys?: number;
+    arraySamples?: number;
+    maxNodes?: number;
+}
+/** Describes a bounded sample of a value without invoking accessors or exposing leaf values. */
+export declare function getStructure(data: unknown, options?: StructureOptions): unknown;

package/dist/generated/data-structure.js

@@ -0,0 +1,58 @@
+/** Describes a bounded sample of a value without invoking accessors or exposing leaf values. */
+export function getStructure(data, options = {}) {
+    const { maxDepth = 5, maxKeys = 50, arraySamples = 1, maxNodes = 2000 } = options;
+    for (const [name, value, limit] of [
+        ['maxDepth', maxDepth, 20],
+        ['maxKeys', maxKeys, 1000],
+        ['arraySamples', arraySamples, 20],
+        ['maxNodes', maxNodes, 10000],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > limit)
+            throw new Error(`${name} must be an integer between 1 and ${limit}`);
+    }
+    const ancestors = new WeakSet();
+    let nodes = 0;
+    const visit = (value, depth) => {
+        if (++nodes > maxNodes)
+            return '<max nodes reached>';
+        if (depth >= maxDepth)
+            return '<max depth reached>';
+        if (value === null)
+            return 'null';
+        if (typeof value !== 'object')
+            return typeof value;
+        if (ancestors.has(value))
+            return '<circular>';
+        ancestors.add(value);
+        try {
+            if (Array.isArray(value)) {
+                if (!value.length)
+                    return 'array[0]';
+                const samples = Array.from({ length: Math.min(value.length, arraySamples) }, (_, index) => {
+                    const descriptor = Object.getOwnPropertyDescriptor(value, index);
+                    return descriptor && 'value' in descriptor
+                        ? visit(descriptor.value, depth + 1)
+                        : descriptor
+                            ? '<accessor>'
+                            : 'undefined';
+                });
+                return {
+                    _type: `array[${value.length}]`,
+                    ...(arraySamples === 1 ? { _sample: samples[0] } : { _samples: samples }),
+                };
+            }
+            const keys = Object.keys(value);
+            const entries = keys.slice(0, maxKeys).map(key => {
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                return [key, 'value' in descriptor ? visit(descriptor.value, depth + 1) : '<accessor>'];
+            });
+            if (keys.length > maxKeys)
+                entries.push(['<truncated keys>', keys.length - maxKeys]);
+            return Object.fromEntries(entries);
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    };
+    return visit(data, 0);
+}

package/dist/generated/plugin-host-build.d.ts

@@ -1 +1 @@
-export declare const PLUGIN_HOST_BUILD_ID = "1d85713299314f3ff82faecc749a025177411fdedd16949cee34e6712b93e1ef";
+export declare const PLUGIN_HOST_BUILD_ID = "e5c7f6cfb7a597a523293c0ea2929b4970aa9eb86e7aeb672f85a37c317bc258";

package/dist/generated/plugin-host-build.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generate-plugin-host-build.mjs.
-export const PLUGIN_HOST_BUILD_ID = '1d85713299314f3ff82faecc749a025177411fdedd16949cee34e6712b93e1ef';
+export const PLUGIN_HOST_BUILD_ID = 'e5c7f6cfb7a597a523293c0ea2929b4970aa9eb86e7aeb672f85a37c317bc258';

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSE
 export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestBinaryBody, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated/browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated/browser-action-protocol.js';
+export { getStructure as structure, type StructureOptions } from './generated/data-structure.js';
 export declare function tabCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
 /** Compatibility wrapper for tabCheckpoint. */
 export declare function captureCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;

package/dist/index.js

@@ -11,6 +11,7 @@ export { executeRegisteredPlugin, } from './plugins/sdk/plugin.js';
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated/browser-action-protocol.js';
 import { invoke } from './unified.js';
+export { getStructure as structure } from './generated/data-structure.js';
 export function tabCheckpoint(params, options) {
     return invoke('tab_checkpoint', params, options);
 }

package/dist/plugins/pluginRegistry.js

@@ -9,6 +9,7 @@ import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, PLUGIN_PAGE_RUNTIME_HAS
 import { pluginFileVersion } from './pluginSource.js';
 const RESERVED_NAMES = new Set([
     'check',
+    'run',
     'help',
     'connector_list',
     'capture_checkpoint',

package/dist/plugins/runtime/pluginCommandWorker.js

@@ -31,7 +31,7 @@ async function run(message) {
                 : message.access === 'toolbox'
                     ? invokeRegisteredToolboxPlugin
                     : invokeRegisteredPlugin;
-        const declaration = message.describe
+        const declaration = message.describe || message.help
             ? await loadPlugin(message.entry, {
                 options: {},
                 progress: () => { },
@@ -63,11 +63,13 @@ async function run(message) {
         const value = migration
             ? await migration.runMigration(message.invocation)
             : declaration
-                ? {
-                    pageRuntime: declaration.pageRuntime,
-                    stateStorage: declaration.stateStorage,
-                    taskRecovery: declaration.taskRecovery,
-                }
+                ? message.help
+                    ? declaration.help(message.help.namespace, message.help.command)
+                    : {
+                        pageRuntime: declaration.pageRuntime,
+                        stateStorage: declaration.stateStorage,
+                        taskRecovery: declaration.taskRecovery,
+                    }
                 : message.model
                     ? await (await import('@mearl/agent-runtime/codex')).runCodexModel(message.model, {
                         signal: controller.signal,

package/dist/plugins/runtime/pluginExecutor.d.ts

@@ -6,6 +6,11 @@ export interface PluginExecutorDependencies {
     registration?: PluginRegistration;
 }
 export interface PluginExecutorOptions extends PluginInvokeOptions {
+    help?: {
+        namespace: string;
+        command?: string;
+    };
+    onOutput?: (stream: 'stdout' | 'stderr', chunk: Buffer) => void;
     describe?: boolean;
     model?: PluginModelRequest;
     recovery?: boolean;

package/dist/plugins/runtime/pluginExecutor.js

@@ -8,7 +8,7 @@ import { stopPluginProcessTree } from './pluginProcessTree.js';
 import { processIdentity } from '@mearl/daemon-core';
 /** Executes registered trusted code in a process whose lifetime belongs to this invocation. */
 export async function executeRegisteredPlugin(plugin, invocation, context, options = {}, dependencies = {}) {
-    const { signal, onProgress, source, access = 'public', executionTimeoutMs, cancellationGraceMs = 1000, workerPath, cwd, environment, describe, model, recovery, migration, expectedRecovery, onExecutorStarted, onExecutorStopped, onDiagnostic, ...invokeOptions } = options;
+    const { signal, onProgress, source, access = 'public', executionTimeoutMs, cancellationGraceMs = 1000, workerPath, cwd, environment, describe, help, onOutput, model, recovery, migration, expectedRecovery, onExecutorStarted, onExecutorStopped, onDiagnostic, ...invokeOptions } = options;
     for (const [name, value] of [
         ['executionTimeoutMs', executionTimeoutMs],
         ['cancellationGraceMs', cancellationGraceMs],
@@ -25,7 +25,7 @@ export async function executeRegisteredPlugin(plugin, invocation, context, optio
     const entryVersion = pluginFileVersion(registration.entry);
     return new Promise((resolve, reject) => {
         const child = fork(workerPath ?? PLUGIN_WORKER_PATH, [], {
-            stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+            stdio: ['ignore', onOutput ? 'pipe' : 'ignore', 'pipe', 'ipc'],
             serialization: 'advanced',
             execArgv: [],
             detached: process.platform !== 'win32',
@@ -46,6 +46,18 @@ export async function executeRegisteredPlugin(plugin, invocation, context, optio
         child.stderr?.on('data', chunk => {
             stderr = `${stderr}${chunk}`.slice(-65536);
         });
+        if (onOutput) {
+            for (const stream of ['stdout', 'stderr']) {
+                child[stream]?.on('data', chunk => {
+                    try {
+                        onOutput(stream, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                    }
+                    catch (error) {
+                        stop(error instanceof Error ? error : new Error(String(error)));
+                    }
+                });
+            }
+        }
         const send = (message) => {
             if (!child.connected || exited)
                 return;
@@ -209,6 +221,7 @@ export async function executeRegisteredPlugin(plugin, invocation, context, optio
                 entryVersion,
                 access,
                 describe,
+                help,
                 model,
                 recovery,
                 migration,

package/dist/plugins/runtime/pluginExecutorProtocol.d.ts

@@ -13,6 +13,10 @@ export type PluginWorkerRequest = {
     access: 'public' | 'toolbox' | 'runtime';
     registration?: PluginRegistration;
     describe?: boolean;
+    help?: {
+        namespace: string;
+        command?: string;
+    };
     model?: PluginModelRequest;
     recovery?: boolean;
     migration?: boolean;

package/dist/plugins/runtime/pluginExecutorSupervisor.js

@@ -3,13 +3,14 @@ import { fileURLToPath } from 'node:url';
 /** Ownership monitoring runs outside the event loop that executes plugin code. */
 export function supervisePluginExecutor(workerUrl) {
     const child = fork(fileURLToPath(workerUrl), ['--command'], {
-        stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+        stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
         serialization: 'advanced',
         execArgv: [],
     });
     let ending = false;
     let forwarded = Promise.resolve();
     child.stderr?.on('data', chunk => process.stderr.write(chunk));
+    child.stdout?.on('data', chunk => process.stdout.write(chunk));
     const terminate = () => {
         if (process.platform === 'win32') {
             try {

package/dist/runtimePaths.d.ts

@@ -1,4 +1,5 @@
 export declare const CLIENT_VERSION: string;
 export declare const PLUGIN_TASK_HOST_PATH: string;
 export declare const PLUGIN_WORKER_PATH: string;
+export declare const SCRIPT_WORKER_PATH: string;
 export declare const PLUGIN_MODEL_SESSION_WORKER_PATH: string;

package/dist/runtimePaths.js

@@ -5,4 +5,5 @@ const require = createRequire(import.meta.url);
 export const CLIENT_VERSION = require('../package.json').version;
 export const PLUGIN_TASK_HOST_PATH = fileURLToPath(new URL('./plugin-task-host.js', import.meta.url));
 export const PLUGIN_WORKER_PATH = fileURLToPath(new URL('./plugin-worker.js', import.meta.url));
+export const SCRIPT_WORKER_PATH = fileURLToPath(new URL('./scriptWorker.js', import.meta.url));
 export const PLUGIN_MODEL_SESSION_WORKER_PATH = fileURLToPath(new URL('./pluginModelSessionWorker.js', import.meta.url));

package/dist/script.d.ts

@@ -0,0 +1,30 @@
+import { type UnifiedInvokeOptions } from './unified.js';
+export interface ScriptExecutionOptions extends UnifiedInvokeOptions {
+    serverUrl?: string;
+    /** Overall deadline, independent of individual action timeouts. Default: 60 seconds. */
+    executionTimeoutSec?: number;
+    /** Combined stdout/stderr limit in bytes. Default: 256 KiB; maximum: 1 MiB. */
+    maxOutputBytes?: number;
+    signal?: AbortSignal;
+    source?: 'cli' | 'mcp' | 'sdk';
+}
+export interface ScriptExecutionResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    session?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+        stack?: string;
+        details?: unknown;
+        stage?: string;
+        attempt?: unknown;
+    };
+    executionStopped: boolean;
+    /** Dispatched browser/plugin calls can finish after the script has stopped. */
+    mayHaveLateEffects: boolean;
+    pendingActions: string[];
+}
+/** Runs trusted agent code in a short-lived Node process, with one shared SDK client. */
+export declare function executeScript(code: string, options?: ScriptExecutionOptions): Promise<ScriptExecutionResult>;

package/dist/script.js

@@ -0,0 +1,260 @@
+import { spawn } from 'node:child_process';
+import { isBrowserCommandAction } from './generated/browser-action-protocol.js';
+import { exportArtifact } from './artifacts.js';
+import { UnifiedClient } from './unified.js';
+import { loadCloudServerConfig } from './unifiedConfig.js';
+import { stopPluginProcessTree } from './plugins/runtime/pluginProcessTree.js';
+import { SCRIPT_WORKER_PATH } from './runtimePaths.js';
+import { SDK_METHOD_ACTIONS as METHOD_ACTIONS, SDK_OPTIONS_ONLY_METHODS as OPTIONS_ONLY, } from './sdkMethods.js';
+import { getCommandHelp } from './commandHelp.js';
+import { executeRegisteredPlugin } from './plugins/runtime/pluginExecutor.js';
+import { findPluginRegistration } from './plugins/pluginRegistry.js';
+import { findOfficialPlugin } from './plugins/officialPluginCatalog.js';
+import { ensureOfficialPluginRegistered } from './plugins/officialPluginInstaller.js';
+import { serializeScriptError as serializeError } from './scriptErrors.js';
+const METHODS = [...METHOD_ACTIONS.keys(), 'invoke', 'invokePlugin', 'saveArtifact', 'help'];
+const MAX_SCRIPT_BYTES = 1024 * 1024;
+/** Runs trusted agent code in a short-lived Node process, with one shared SDK client. */
+export async function executeScript(code, options = {}) {
+    if (typeof code !== 'string' || !code.trim() || Buffer.byteLength(code) > MAX_SCRIPT_BYTES)
+        throw new Error('Script must be non-empty JavaScript of at most 1 MiB');
+    const { serverUrl, executionTimeoutSec = 60, maxOutputBytes = 256 * 1024, signal, source = 'sdk', ...defaults } = options;
+    if (!Number.isFinite(executionTimeoutSec) ||
+        executionTimeoutSec <= 0 ||
+        executionTimeoutSec * 1000 > 2_147_483_647)
+        throw new Error('executionTimeoutSec must be positive and within the timer range');
+    if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > 1024 * 1024)
+        throw new Error('maxOutputBytes must be an integer between 1 and 1048576');
+    const client = new UnifiedClient({
+        serverUrl: serverUrl ?? process.env.MEARL_SERVER_URL ?? loadCloudServerConfig()?.server,
+    });
+    let session = defaults.session && defaults.session !== 'new' ? { sessionId: defaults.session } : undefined;
+    let sessionId = defaults.session;
+    let uncertainEffects = false;
+    const pending = new Map();
+    const controller = new AbortController();
+    const invoke = async (action, payload, overrides = {}) => {
+        controller.signal.throwIfAborted();
+        const result = await client.invoke(action, payload, {
+            ...defaults,
+            session: sessionId,
+            ...overrides,
+        });
+        if (result?.action?.stage === 'dispatch-uncertain' || result?.stage === 'dispatch-uncertain')
+            uncertainEffects = true;
+        if (result?.session?.sessionId &&
+            (!overrides.session || overrides.session === 'new' || overrides.session === sessionId)) {
+            session = result.session;
+            if (!overrides.session || overrides.session === 'new')
+                sessionId = result.session.sessionId;
+        }
+        return result;
+    };
+    try {
+        return await new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                resolve({
+                    success: false,
+                    stdout: '',
+                    stderr: '',
+                    ...(session ? { session } : {}),
+                    error: { code: 'SCRIPT_CANCELLED', message: 'Script execution cancelled' },
+                    executionStopped: true,
+                    mayHaveLateEffects: false,
+                    pendingActions: [],
+                });
+                return;
+            }
+            const child = spawn(process.execPath, [SCRIPT_WORKER_PATH], {
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                serialization: 'advanced',
+                detached: process.platform !== 'win32',
+            });
+            const output = { stdout: [], stderr: [] };
+            let outputBytes = 0;
+            let outcome;
+            let cleanup;
+            let cleanupError;
+            let pendingActions = [];
+            let closed = false;
+            const pluginCalls = new Set();
+            const stop = (error) => {
+                if (outcome !== undefined || closed)
+                    return;
+                outcome = error ?? true;
+                pendingActions = [...pending.values()];
+                controller.abort();
+                client.disconnect();
+                if (child.pid) {
+                    cleanup = stopPluginProcessTree(child.pid).catch(error => {
+                        cleanupError = error;
+                        child.kill('SIGKILL');
+                    });
+                }
+            };
+            const abort = () => stop({ code: 'SCRIPT_CANCELLED', message: 'Script execution cancelled' });
+            const deadline = setTimeout(() => stop({ code: 'SCRIPT_TIMEOUT', message: 'Script execution deadline exceeded' }), executionTimeoutSec * 1000);
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted)
+                abort();
+            const appendOutput = (stream, chunk) => {
+                const remaining = maxOutputBytes - outputBytes;
+                output[stream].push(chunk.subarray(0, Math.max(0, remaining)));
+                outputBytes += Math.min(chunk.length, Math.max(0, remaining));
+                if (chunk.length > remaining)
+                    stop({
+                        code: 'SCRIPT_OUTPUT_LIMIT',
+                        message: `Script output exceeded ${maxOutputBytes} bytes`,
+                    });
+            };
+            for (const stream of ['stdout', 'stderr']) {
+                child[stream].on('data', (chunk) => appendOutput(stream, chunk));
+            }
+            const runPlugin = async (name, invocation, overrides = {}, help) => {
+                if (!findPluginRegistration(name) && findOfficialPlugin(name))
+                    await ensureOfficialPluginRegistered(name);
+                controller.signal.throwIfAborted();
+                const pluginOptions = { ...defaults, session: sessionId, ...overrides };
+                if (pluginOptions.session === 'new' && !help)
+                    throw new Error('Create the control session with a browser action before calling a Skill command');
+                const operation = executeRegisteredPlugin(name, invocation, {
+                    invoke: (action, payload = {}, options) => invoke(action, payload, options),
+                }, {
+                    ...pluginOptions,
+                    source,
+                    signal: controller.signal,
+                    cancellationGraceMs: 50,
+                    onOutput: appendOutput,
+                    ...(help ? { help } : {}),
+                });
+                pluginCalls.add(operation);
+                try {
+                    return await operation;
+                }
+                finally {
+                    pluginCalls.delete(operation);
+                }
+            };
+            const send = (message) => {
+                if (outcome !== undefined || !child.connected)
+                    return;
+                child.send(message, error => {
+                    if (error)
+                        stop(serializeError(error));
+                });
+            };
+            child.on('message', (message) => {
+                if (outcome !== undefined || !message || typeof message !== 'object')
+                    return;
+                if (message.type === 'done' || message.type === 'error') {
+                    stop(message.type === 'error'
+                        ? serializeError(message.error)
+                        : pending.size
+                            ? {
+                                code: 'SCRIPT_PENDING_CALLS',
+                                message: 'Script finished with unawaited SDK calls',
+                            }
+                            : undefined);
+                    return;
+                }
+                if (message.type !== 'call')
+                    return;
+                const { id, method, args } = message;
+                if (!Number.isSafeInteger(id) ||
+                    pending.has(id) ||
+                    !METHODS.includes(method) ||
+                    !Array.isArray(args)) {
+                    stop({ code: 'SCRIPT_PROTOCOL_ERROR', message: 'Invalid script SDK call' });
+                    return;
+                }
+                if (method !== 'help' && sessionId === 'new' && pending.size) {
+                    send({
+                        type: 'response',
+                        id,
+                        error: {
+                            code: 'SCRIPT_SESSION_INITIALIZING',
+                            message: 'Await the first session call before starting concurrent calls',
+                        },
+                    });
+                    return;
+                }
+                pending.set(id, method === 'invoke' || method === 'invokePlugin' ? String(args[0]) : method);
+                void Promise.resolve()
+                    .then(async () => {
+                    if (outcome !== undefined)
+                        throw new Error('Script execution stopped');
+                    if (method === 'help') {
+                        const target = args[0];
+                        if (target && typeof target === 'object') {
+                            if (typeof target.plugin !== 'string' ||
+                                !target.plugin.trim() ||
+                                (target.command !== undefined && typeof target.command !== 'string'))
+                                throw new Error('Plugin help requires { plugin, command? }');
+                            return runPlugin(target.plugin, { command: '', input: {} }, {}, { namespace: `mearl ${target.plugin}`, command: target.command });
+                        }
+                        return getCommandHelp(target);
+                    }
+                    if (method === 'invoke') {
+                        if (!isBrowserCommandAction(args[0]) && args[0] !== 'browser_select_browser')
+                            throw new Error(`Unsupported browser action: ${args[0]}; use invokePlugin for registered Skill commands`);
+                        return invoke(args[0], args[1] ?? {}, args[2]);
+                    }
+                    if (method === 'invokePlugin') {
+                        return runPlugin(args[0], args[1], args[2]);
+                    }
+                    if (method === 'saveArtifact')
+                        return exportArtifact({ invoke }, args[0], args[1], {
+                            ...defaults,
+                            session: sessionId,
+                            ...args[2],
+                        });
+                    const optionsOnly = OPTIONS_ONLY.has(method) || (method === 'browserRelease' && args.length < 2);
+                    return invoke(METHOD_ACTIONS.get(method), optionsOnly ? {} : (args[0] ?? {}), optionsOnly ? args[0] : args[1]);
+                })
+                    .then(result => send({ type: 'response', id, result, session }), error => send({ type: 'response', id, error: serializeError(error), session }))
+                    .finally(() => pending.delete(id));
+            });
+            child.once('error', error => {
+                stop(serializeError(error));
+            });
+            child.once('exit', () => {
+                if (outcome === undefined)
+                    stop({
+                        code: 'SCRIPT_EXITED',
+                        message: 'Script process exited before reporting completion',
+                    });
+            });
+            child.once('close', () => {
+                closed = true;
+                clearTimeout(deadline);
+                signal?.removeEventListener('abort', abort);
+                void Promise.allSettled([cleanup, ...pluginCalls])
+                    .then(outcomes => {
+                    if (outcomes.some(result => result.status === 'rejected' &&
+                        result.reason?.code === 'PLUGIN_EXECUTOR_CLEANUP_FAILED'))
+                        cleanupError = new Error('Unable to confirm Skill process cleanup');
+                    const error = cleanupError
+                        ? serializeError(cleanupError, 'SCRIPT_CLEANUP_FAILED')
+                        : outcome === true
+                            ? undefined
+                            : outcome;
+                    resolve({
+                        success: !error && outcome === true,
+                        stdout: Buffer.concat(output.stdout).toString('utf8'),
+                        stderr: Buffer.concat(output.stderr).toString('utf8'),
+                        ...(session ? { session } : {}),
+                        ...(error ? { error } : {}),
+                        executionStopped: !cleanupError,
+                        mayHaveLateEffects: pendingActions.length > 0 || uncertainEffects,
+                        pendingActions,
+                    });
+                })
+                    .catch(reject);
+            });
+            send({ type: 'start', code, methods: METHODS, session });
+        });
+    }
+    finally {
+        client.disconnect();
+    }
+}

package/dist/scriptCli.d.ts

@@ -0,0 +1 @@
+export declare function runScriptCli(args: string[], commandName: string): Promise<number>;

package/dist/scriptCli.js

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Command } from 'commander';
+import { executeScript } from './script.js';
+export async function runScriptCli(args, commandName) {
+    const program = new Command()
+        .name(`${commandName} run`)
+        .description('执行 Node.js 脚本；预注入 mearl SDK，支持顶层 await、条件和循环')
+        .option('--file <path>', '读取 JavaScript 文件；省略时从 stdin 读取')
+        .option('--session <new-or-id>', '首次建立或复用控制会话')
+        .option('--browser <id-or-name>', '指定浏览器')
+        .option('--connector <id-or-name>', '限制到远端 connector')
+        .option('--local', '仅使用本机浏览器')
+        .option('--cdp', '强制本机 CDP')
+        .option('--server <url>', '覆盖 cloud-server 地址')
+        .option('--timeout <seconds>', '整个脚本的执行时限（默认 60 秒）', '60')
+        .allowExcessArguments(false)
+        .exitOverride()
+        .addHelpText('after', `\n示例：\n  ${commandName} run --file task.mjs\n  ${commandName} run <<'JS'\n  console.log(await mearl.tabList());\n  JS\n\n脚本拥有当前宿主的 Node.js 权限；使用 await import() 加载模块。\n调用 Skill 命令：await mearl.invokePlugin('yuque', { command: 'read', input: { url: '...' } })。\n用 console.log(await mearl.help('pageClick')) 查询共享帮助，mearl.structure(value) 查看结果结构。\n每次运行重建 JS 变量；复用 session 和 tabId 可继续同一浏览器任务。\n`);
+    let source;
+    let options;
+    try {
+        program.parse(args, { from: 'user' });
+        options = program.opts();
+        const timeout = Number(options.timeout);
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout * 1000 > 2_147_483_647)
+            throw new Error('--timeout 必须是有效范围内的大于 0 的秒数');
+        if ((options.local || options.cdp) && options.connector)
+            throw new Error('--local/--cdp 不能与 --connector 同时使用');
+        if (options.file)
+            source = await readFile(resolve(options.file), 'utf8');
+        else {
+            if (process.stdin.isTTY)
+                throw new Error('通过 stdin 提交脚本，或使用 --file <path>');
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of process.stdin) {
+                const buffer = Buffer.from(chunk);
+                size += buffer.length;
+                if (size > 1024 * 1024)
+                    throw new Error('脚本不能超过 1 MiB');
+                chunks.push(buffer);
+            }
+            source = Buffer.concat(chunks).toString('utf8');
+        }
+        if (!source.trim() || Buffer.byteLength(source) > 1024 * 1024)
+            throw new Error('脚本必须是非空且不超过 1 MiB 的 JavaScript');
+    }
+    catch (error) {
+        if (error.code === 'commander.helpDisplayed')
+            return 0;
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once('SIGINT', abort);
+    process.once('SIGTERM', abort);
+    try {
+        const result = await executeScript(source, {
+            executionTimeoutSec: Number(options.timeout),
+            signal: controller.signal,
+            source: 'cli',
+            ...(options.session ? { session: options.session } : {}),
+            ...(options.browser ? { browser: options.browser } : {}),
+            ...(options.connector ? { connector: options.connector } : {}),
+            ...(options.local || options.cdp ? { local: true } : {}),
+            ...(options.cdp ? { transport: 'cdp' } : {}),
+            ...(options.server ? { serverUrl: options.server } : {}),
+        });
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        if (result.session)
+            console.error(JSON.stringify({ session: result.session }));
+        if (!result.success)
+            console.error(JSON.stringify({
+                error: result.error,
+                executionStopped: result.executionStopped,
+                mayHaveLateEffects: result.mayHaveLateEffects,
+                pendingActions: result.pendingActions,
+            }));
+        return result.success ? 0 : 1;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    finally {
+        process.removeListener('SIGINT', abort);
+        process.removeListener('SIGTERM', abort);
+    }
+}

package/dist/scriptErrors.d.ts

@@ -0,0 +1,8 @@
+export declare function serializeScriptError(error: unknown, fallback?: string): {
+    stack?: string | undefined;
+    attempt?: {} | null | undefined;
+    stage?: string | undefined;
+    details?: Record<string, unknown> | undefined;
+    code: string;
+    message: string;
+};

package/dist/scriptErrors.js

@@ -0,0 +1,21 @@
+import { serializePluginExecutionError } from './plugins/runtime/pluginExecutorProtocol.js';
+export function serializeScriptError(error, fallback = 'SCRIPT_ERROR') {
+    const value = error;
+    const diagnostic = serializePluginExecutionError({
+        message: typeof value?.message === 'string' ? value.message : String(error),
+        code: typeof value?.code === 'string' ? value.code : fallback,
+        details: {
+            ...value?.details,
+            ...(value?.attempt !== undefined ? { attempt: value.attempt } : {}),
+        },
+        ...(typeof value?.stage === 'string' ? { stage: value.stage } : {}),
+    });
+    return {
+        code: diagnostic.code ?? fallback,
+        message: diagnostic.message,
+        ...(diagnostic.details ? { details: diagnostic.details } : {}),
+        ...(typeof diagnostic.metadata?.stage === 'string' ? { stage: diagnostic.metadata.stage } : {}),
+        ...(diagnostic.details?.attempt !== undefined ? { attempt: diagnostic.details.attempt } : {}),
+        ...(typeof value?.stack === 'string' ? { stack: value.stack.slice(0, 16384) } : {}),
+    };
+}

package/dist/scriptWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scriptWorker.js

@@ -0,0 +1,50 @@
+import { getStructure } from './generated/data-structure.js';
+import { serializeScriptError } from './scriptErrors.js';
+const pending = new Map();
+let sequence = 0;
+let session;
+const call = (method, args) => new Promise((resolve, reject) => {
+    const id = ++sequence;
+    pending.set(id, { resolve, reject });
+    process.send({ type: 'call', id, method, args });
+});
+process.on('disconnect', () => process.exit(1));
+process.on('message', async (message) => {
+    if (message.type === 'response') {
+        const entry = pending.get(message.id);
+        if (!entry)
+            return;
+        pending.delete(message.id);
+        session = message.session ?? session;
+        if (message.error)
+            entry.reject(Object.assign(new Error(message.error.message), message.error));
+        else
+            entry.resolve(message.result);
+        return;
+    }
+    if (message.type !== 'start')
+        return;
+    session = message.session;
+    const api = Object.fromEntries(message.methods.map((method) => [method, (...args) => call(method, args)]));
+    api.structure = getStructure;
+    Object.defineProperty(api, 'session', { get: () => session, enumerable: true });
+    Object.defineProperty(globalThis, 'mearl', { value: Object.freeze(api), configurable: true });
+    let failure;
+    try {
+        const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+        const fn = new AsyncFunction('mearl', '"use strict";\n' + message.code + '\n//# sourceURL=mearl-script.js');
+        await fn(api);
+        if (pending.size)
+            throw Object.assign(new Error('Script finished with unawaited SDK calls'), {
+                code: 'SCRIPT_PENDING_CALLS',
+            });
+    }
+    catch (error) {
+        failure = serializeScriptError(error);
+    }
+    await Promise.all([
+        new Promise(resolve => process.stdout.write('', resolve)),
+        new Promise(resolve => process.stderr.write('', resolve)),
+    ]);
+    process.send(failure ? { type: 'error', error: failure } : { type: 'done' });
+});

package/dist/sdkMethods.d.ts

@@ -0,0 +1,3 @@
+/** Method names and signature exceptions shared by script dispatch and command help. */
+export declare const SDK_METHOD_ACTIONS: Map<string, string>;
+export declare const SDK_OPTIONS_ONLY_METHODS: Set<string>;

package/dist/sdkMethods.js

@@ -0,0 +1,9 @@
+import { BROWSER_COMMAND_ACTIONS } from './generated/browser-action-protocol.js';
+/** Method names and signature exceptions shared by script dispatch and command help. */
+export const SDK_METHOD_ACTIONS = new Map(Object.keys(BROWSER_COMMAND_ACTIONS).map(action => [
+    action.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase()),
+    action,
+]));
+SDK_METHOD_ACTIONS.set('selectBrowser', 'browser_select_browser');
+SDK_METHOD_ACTIONS.set('captureCheckpoint', 'tab_checkpoint');
+export const SDK_OPTIONS_ONLY_METHODS = new Set(['browserList', 'tabList', 'getRules']);

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@mearl/client",
-  "version": "2.22.1",
+  "version": "2.22.2",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
+    "./script": {
+      "types": "./dist/script.d.ts",
+      "import": "./dist/script.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -63,14 +67,15 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.22.1",
-    "@mearl/daemon-core": "2.22.1",
-    "@mearl/provider": "2.22.1",
-    "@mearl/agent-runtime": "2.22.1"
+    "@mearl/cloud-types": "2.22.2",
+    "@mearl/provider": "2.22.2",
+    "@mearl/agent-runtime": "2.22.2",
+    "@mearl/daemon-core": "2.22.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.25.12",
     "typescript": "^5.8.3"
   },
   "scripts": {