@mearl/client 2.18.0 → 2.19.0

package/README.md

@@ -127,7 +127,29 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 | `--server <url>`         | 覆盖自动读取的 cloud-server 地址      |
 
 `browser_list --help` 和 `browser_launch --help` 会按场景展示宿主选择参数；连接或传输排障运行
-`mearl check --help`。其中 `--json` 仅用于输出机器可读的检查结果。
+`mearl check --help`。`mearl check` 检查连接与浏览器状态；`mearl check --updates` 还会并发查询
+client、native-host、cloud-connector 和扩展的最新发布版本。发布版本查询最长等待约 1.5 秒，
+无法访问发布源时会提示无法确认更新，不影响浏览器可用性检查。`--json` 输出机器可读的检查结果，
+与 `--updates` 同用时包含更新状态。发现更新时会提示适用的命令：client/native-host 使用
+`npx @mearl/setup update`，setup 管理的扩展使用 `npx @mearl/setup extension`。
+
+全局安装的 `mearl` CLI 默认在每天首次使用后启动独立后台进程，查询最新发布版本，并比较
+client、native-host、cloud-server 和 MCP server 的已安装版本。发现更新时调用
+`@mearl/setup update --yes --skip-skill` 更新版本落后的运行环境及其共享 client，也支持独立安装的 CLI。
+当前命令不等待网络或安装；检查和安装结果记录在
+`~/.mearl/cli-auto-update-state.json`。项目依赖和临时 `npx` 副本不会被自动修改。
+浏览器扩展沿用其独立的更新入口。
+在 `~/.mearl/config.json` 中设置间隔天数或关闭自动更新：
+
+```json
+{ "cliAutoUpdate": { "intervalDays": 7 } }
+```
+
+```json
+{ "cliAutoUpdate": false }
+```
+
+间隔按本地日历日计算。需要立即检查各组件的发布版本时，仍可运行 `mearl check --updates`。
 
 ## Skill 插件
 
@@ -136,7 +158,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 ```bash
 npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
 npx @mearl/setup plugin install trip/mearl --skill buc-request --yes
-npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
+npx @mearl/setup plugin /absolute/path/to/yuque-doc-fetch
 npx @mearl/setup plugin uninstall yuque
 mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
 mearl yuque --payload '{"command":"read","input":{"url":"https://aliyuque.antfin.com/group/book/doc"}}'
@@ -151,7 +173,7 @@ Provider 与插件仍可独立安装、更新和卸载，帮助聚合不会启
 目录默认使用 `scripts/main.mjs` 或 `scripts/main.py`；两者同时存在时使用 JavaScript 入口。JavaScript 入口默认导出 `register(app)`，Python 入口导出 `register(app)` 函数；两种入口都可声明简短的 `name` 和 `description`，并通过 `app.command(signature, handler, description?)`
 注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。JavaScript 插件还可传入 `{ message, data }`，让工具页通过可 JSON 序列化的 `data` 获取稳定的阶段、对象 ID 等机器信息；CLI 仍只显示 `message`。Python 的 `app.invoke` 是同步调用，handler 可以是普通函数或 `async def`。Python 插件要求 `python3 >= 3.9`，可用 `MEARL_PYTHON` 指定解释器路径；Mearl 不安装 Python 或执行 `pip install`。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
 `--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
-自动注册默认以 skill 安装目录名作为命令名，也可在入口声明 `name` 指定短名称。
+注册名优先使用显式名称，其次读取入口的 `name` metadata，最后回退到 skill 目录名；常规注册只传路径。
 setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
 
 需要单独检查插件时运行 `mearl <name> --version`。命令会解析注册记录并加载入口，但不连接浏览器；
@@ -176,7 +198,7 @@ const result = await invokePlugin(
 );
 ```
 
-MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用尚未注册的 `buc` 或 `tdbank` 时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
+MCP Server 通过固定工具 `plugin_invoke` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用尚未注册的 `buc` 或 `tdbank` 时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
 
 注册记录在 `~/.mearl/plugins/<name>.json`，保存入口路径和可选的简短描述；skill 业务代码原地更新直接生效，换路径或更新描述后重新注册。
 `plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 `ali-skills remove --global --yes`，
@@ -223,8 +245,14 @@ export default function register(app) {
 ```
 
 声明 `agent` 后工具页可以把任务交给对话 Agent；`layout` 默认为 `drawer`，宿主会提供顶部入口。
-页面也可在 `setAgentPanelVisible` 或 `runAgentTask` 中为单次交互指定 `drawer` / `workspace`。带固定
+页面也可在 `setAgentPanelVisible` 或 `runAgentTask` 中为单次交互指定 `drawer` / `workspace` / `inline`；
+Agent 对话会保存在 Codex 会话历史中。带固定
 18rem 左侧导航的工作台可默认使用 `workspace`，由导航项切换 Agent，并占满导航栏以外的主内容区；详情页仍可按需唤起右侧抽屉。
+`inline` 用于把 Agent 嵌入工具页中的卡片或分区，调用时同时传入作为占位区域的 `anchor` 元素和稳定的
+`key`；宿主会跟随该元素的滚动与尺寸变化同步面板位置。`key` 也可用于抽屉或工作区布局，为不同业务对象
+隔离会话与输入草稿；`setAgentPanelVisible` 可同时传入绝对路径 `cwd`，让首次创建的会话直接绑定该目录。
+传入 `context` 可为面板提供不显示为聊天消息的背景上下文；它会在用户首次发送消息、创建会话时作为
+developer instructions 交给 Agent。
 
 页面通过 `await window.mearl.ready()` 取得 `{ locale, theme, title, fontSize }`，通过
 `window.mearl.invoke(command, input?)` 调用 `commands` 白名单中的同一插件命令。页面运行在无扩展

package/dist/autoUpdate.d.ts

@@ -0,0 +1,33 @@
+export type InstalledMearlEnvironment = {
+    profile: 'local' | 'cloud' | 'mcp';
+    version: string;
+};
+interface ScheduleOptions {
+    intervalDays?: number | null;
+    packageRoot?: string | null;
+    now?: Date;
+    statePath?: string;
+    lockPath?: string;
+    workerPath?: string;
+    launch?: (worker: string, installedVersion: string, packageRoot: string, token: string) => void;
+}
+interface WorkerOptions {
+    fetchLatestVersion?: () => Promise<string>;
+    getInstalledEnvironments?: () => InstalledMearlEnvironment[];
+    update?: (version: string, packageRoot: string, profiles: InstalledMearlEnvironment['profile'][], updateClient: boolean) => Promise<void>;
+    now?: Date;
+    statePath?: string;
+    lockPath?: string;
+}
+export declare function isCliUpdateDue(lastCheckDate: string | undefined, now: Date, intervalDays: number): boolean;
+export declare function isGlobalClientPackageRoot(packageRoot: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): boolean;
+/** Queue a detached check after the CLI command has finished. */
+export declare function scheduleCliAutoUpdate(installedVersion: string, options?: ScheduleOptions): void;
+export declare function setupUpdateCommand(version: string, packageRoot: string, profiles: InstalledMearlEnvironment['profile'][], updateClient: boolean): {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+};
+/** Runs only in the detached worker process. */
+export declare function runCliAutoUpdate(installedVersion: string, packageRoot: string, token: string, options?: WorkerOptions): Promise<void>;
+export {};

package/dist/autoUpdate.js

@@ -0,0 +1,359 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join, resolve, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isNewerRelease, parseReleaseVersion } from './check.js';
+import { loadCliAutoUpdateIntervalDays } from './unifiedConfig.js';
+const CONFIG_DIR = join(homedir(), '.mearl');
+const STATE_PATH = join(CONFIG_DIR, 'cli-auto-update-state.json');
+const LOCK_PATH = join(CONFIG_DIR, 'cli-auto-update.lock');
+const LOCK_STALE_MS = 10 * 60_000;
+const UPDATE_TIMEOUT_MS = 5 * 60_000;
+const VERSION_URL = 'https://registry.npmjs.org/@mearl%2Fclient/latest';
+function localDate(date) {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+function dayNumber(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const timestamp = Date.UTC(year, month - 1, day);
+    const date = new Date(timestamp);
+    return date.getUTCFullYear() === year &&
+        date.getUTCMonth() + 1 === month &&
+        date.getUTCDate() === day
+        ? timestamp / 86_400_000
+        : null;
+}
+export function isCliUpdateDue(lastCheckDate, now, intervalDays) {
+    const previous = typeof lastCheckDate === 'string' ? dayNumber(lastCheckDate) : null;
+    const today = dayNumber(localDate(now));
+    return (previous === null || today === null || today < previous || today - previous >= intervalDays);
+}
+export function isGlobalClientPackageRoot(packageRoot, platform = process.platform, env = process.env) {
+    const resolvedRoot = platform === 'win32' ? win32.resolve(packageRoot) : resolve(packageRoot);
+    const normalized = resolvedRoot.replaceAll('\\', '/').toLowerCase();
+    if (!normalized.endsWith('/node_modules/@mearl/client'))
+        return false;
+    const pnpmGlobalRoot = /\/global\/\d+\/(?:\.pnpm\/.*\/)?node_modules\//.exec(normalized);
+    if (pnpmGlobalRoot) {
+        const pnpmHome = resolvedRoot.slice(0, pnpmGlobalRoot.index);
+        return existsSync(join(pnpmHome, platform === 'win32' ? 'mearl.cmd' : 'mearl'));
+    }
+    if (normalized.includes('/.volta/tools/image/packages/'))
+        return true;
+    const npmSuffix = '/lib/node_modules/@mearl/client';
+    if (platform !== 'win32' && normalized.endsWith(npmSuffix)) {
+        const prefix = resolvedRoot.slice(0, -npmSuffix.length);
+        try {
+            return (realpathSync(join(prefix, 'bin', 'mearl')) ===
+                realpathSync(join(packageRoot, 'dist', 'bin.js')));
+        }
+        catch {
+            return false;
+        }
+    }
+    const windowsNpmRoot = platform === 'win32' && env.APPDATA
+        ? `${win32.resolve(env.APPDATA).replaceAll('\\', '/').toLowerCase()}/npm/node_modules/@mearl/client`
+        : null;
+    return (normalized.includes('/.bun/install/global/') ||
+        /\/(?:\.config\/yarn|\.yarn|yarn\/data|yarn)\/global\//.test(normalized) ||
+        (platform === 'win32' && normalized === windowsNpmRoot));
+}
+function globalSearchPath(pathValue) {
+    return pathValue
+        ?.split(delimiter)
+        .filter(directory => !/(?:^|[\\/])node_modules[\\/]\.bin[\\/]?$/i.test(directory))
+        .join(delimiter);
+}
+function currentGlobalClientRoot() {
+    let directory = dirname(realpathSync(fileURLToPath(import.meta.url)));
+    for (let depth = 0; depth < 12; depth += 1) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'));
+            if (manifest.name === '@mearl/client') {
+                return isGlobalClientPackageRoot(directory) ? directory : null;
+            }
+        }
+        catch {
+            // Continue toward the package root.
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return null;
+}
+function readState(statePath) {
+    try {
+        const value = JSON.parse(readFileSync(statePath, 'utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeState(statePath, state) {
+    mkdirSync(dirname(statePath), { recursive: true, mode: 0o700 });
+    const temporary = `${statePath}.${process.pid}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, statePath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* No temporary file to remove. */
+        }
+        throw error;
+    }
+}
+function acquireLock(lockPath, token) {
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const descriptor = openSync(lockPath, 'wx', 0o600);
+            try {
+                writeFileSync(descriptor, token);
+            }
+            finally {
+                closeSync(descriptor);
+            }
+            return true;
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'EEXIST')
+                throw error;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs <= LOCK_STALE_MS)
+                    return false;
+                unlinkSync(lockPath);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    return false;
+}
+function releaseLock(lockPath, token) {
+    try {
+        if (readFileSync(lockPath, 'utf8') === token)
+            unlinkSync(lockPath);
+    }
+    catch {
+        // A missing lock does not affect the current command or update result.
+    }
+}
+function launchWorker(worker, version, packageRoot, token) {
+    const child = spawn(process.execPath, [worker, version, packageRoot, token], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.once('error', () => releaseLock(LOCK_PATH, token));
+    child.unref();
+}
+/** Queue a detached check after the CLI command has finished. */
+export function scheduleCliAutoUpdate(installedVersion, options = {}) {
+    try {
+        const intervalDays = options.intervalDays === undefined ? loadCliAutoUpdateIntervalDays() : options.intervalDays;
+        if (intervalDays === null)
+            return;
+        const packageRoot = options.packageRoot === undefined ? currentGlobalClientRoot() : options.packageRoot;
+        if (!packageRoot)
+            return;
+        const now = options.now ?? new Date();
+        const statePath = options.statePath ?? STATE_PATH;
+        const lockPath = options.lockPath ?? LOCK_PATH;
+        if (!isCliUpdateDue(readState(statePath).lastCheckDate, now, intervalDays))
+            return;
+        const token = randomUUID();
+        if (!acquireLock(lockPath, token))
+            return;
+        let launched = false;
+        try {
+            if (!isCliUpdateDue(readState(statePath).lastCheckDate, now, intervalDays))
+                return;
+            const worker = options.workerPath ?? fileURLToPath(new URL('./autoUpdateWorker.js', import.meta.url));
+            if (!existsSync(worker))
+                return;
+            (options.launch ?? launchWorker)(worker, installedVersion, packageRoot, token);
+            launched = true;
+        }
+        finally {
+            if (!launched)
+                releaseLock(lockPath, token);
+        }
+    }
+    catch {
+        // Update scheduling must never change CLI behavior.
+    }
+}
+export function setupUpdateCommand(version, packageRoot, profiles, updateClient) {
+    if (profiles.length === 0 && !updateClient) {
+        throw new Error('An update target is required');
+    }
+    if (!parseReleaseVersion(version))
+        throw new Error('A valid Mearl release is required');
+    const [major, minor] = version.split('.');
+    const env = { ...process.env };
+    delete env.MEARL_AUTO_UPDATE_CLIENT_ROOT;
+    delete env.MEARL_AUTO_UPDATE_CLIENT_ONLY;
+    delete env.MEARL_AUTO_UPDATE_PROFILES;
+    env.MEARL_AUTO_UPDATE_SEARCH_PATH = globalSearchPath(env.PATH);
+    if (updateClient || profiles.some(profile => profile === 'local' || profile === 'cloud')) {
+        env.MEARL_AUTO_UPDATE_CLIENT_ROOT = packageRoot;
+    }
+    if (profiles.length === 0)
+        env.MEARL_AUTO_UPDATE_CLIENT_ONLY = '1';
+    else
+        env.MEARL_AUTO_UPDATE_PROFILES = profiles.join(',');
+    return {
+        command: 'npx',
+        args: [
+            '--yes',
+            `@mearl/setup@${version}`,
+            'update',
+            '--yes',
+            '--target-line',
+            `${major}.${minor}.x`,
+            '--skip-skill',
+        ],
+        env,
+    };
+}
+function updateWithSetup(version, packageRoot, profiles, updateClient) {
+    const { command, args, env } = setupUpdateCommand(version, packageRoot, profiles, updateClient);
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            env,
+            stdio: 'ignore',
+            windowsHide: true,
+            shell: process.platform === 'win32',
+        });
+        const timeout = setTimeout(() => child.kill(), UPDATE_TIMEOUT_MS);
+        child.once('error', error => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.once('close', code => {
+            clearTimeout(timeout);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`Setup exited with code ${code ?? 'unknown'}`));
+        });
+    });
+}
+function installedEnvironments() {
+    const versions = [];
+    const env = { ...process.env, PATH: globalSearchPath(process.env.PATH) };
+    const executables = [
+        { profile: 'local', executable: 'mearl-native-host' },
+        { profile: 'cloud', executable: 'mearl-cloud-server' },
+        { profile: 'mcp', executable: 'mearl-mcp-server' },
+    ];
+    for (const { profile, executable } of executables) {
+        try {
+            const result = spawnSync(executable, ['--version'], {
+                encoding: 'utf8',
+                timeout: 5_000,
+                maxBuffer: 1_024,
+                windowsHide: true,
+                shell: process.platform === 'win32',
+                env,
+            });
+            const version = result.stdout?.trim();
+            if (result.status === 0 && typeof version === 'string' && parseReleaseVersion(version)) {
+                versions.push({ profile, version });
+            }
+        }
+        catch {
+            // Other installed environments can still be checked and updated.
+        }
+    }
+    return versions;
+}
+async function fetchLatestClientVersion() {
+    const response = await fetch(VERSION_URL, { signal: AbortSignal.timeout(2_000) });
+    if (!response.ok)
+        throw new Error(`Registry returned HTTP ${response.status}`);
+    const payload = (await response.json());
+    const version = payload.version;
+    if (typeof version !== 'string') {
+        throw new Error('Registry returned an invalid release version');
+    }
+    return version;
+}
+/** Runs only in the detached worker process. */
+export async function runCliAutoUpdate(installedVersion, packageRoot, token, options = {}) {
+    const statePath = options.statePath ?? STATE_PATH;
+    const lockPath = options.lockPath ?? LOCK_PATH;
+    try {
+        writeState(statePath, {
+            ...readState(statePath),
+            lastCheckDate: localDate(options.now ?? new Date()),
+        });
+    }
+    catch {
+        releaseLock(lockPath, token);
+        return;
+    }
+    let result;
+    try {
+        const version = await (options.fetchLatestVersion ?? fetchLatestClientVersion)();
+        if (!parseReleaseVersion(version))
+            throw new Error('Registry returned an invalid release version');
+        const environments = (options.getInstalledEnvironments ?? installedEnvironments)();
+        const installedVersions = [
+            installedVersion,
+            ...environments.map(environment => environment.version),
+        ];
+        const updateClient = isNewerRelease(version, installedVersion);
+        const staleProfiles = environments
+            .filter(environment => isNewerRelease(version, environment.version))
+            .map(environment => environment.profile);
+        const updateAvailable = updateClient || staleProfiles.length > 0;
+        const newerInstalled = installedVersions.some(installed => isNewerRelease(installed, version));
+        if (updateAvailable && newerInstalled) {
+            result = {
+                checkedAt: new Date().toISOString(),
+                status: 'skipped',
+                version,
+                error: 'An installed component is newer than the latest published release',
+            };
+        }
+        else if (updateAvailable) {
+            await (options.update ?? updateWithSetup)(version, packageRoot, staleProfiles, updateClient);
+            result = { checkedAt: new Date().toISOString(), status: 'updated', version };
+        }
+        else {
+            result = { checkedAt: new Date().toISOString(), status: 'current', version };
+        }
+    }
+    catch (error) {
+        result = {
+            checkedAt: new Date().toISOString(),
+            status: 'failed',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        writeState(statePath, { ...readState(statePath), lastResult: result });
+    }
+    catch {
+        /* The result is best effort. */
+    }
+    releaseLock(lockPath, token);
+}

package/dist/autoUpdateWorker.d.ts

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

package/dist/autoUpdateWorker.js

@@ -0,0 +1,5 @@
+import { runCliAutoUpdate } from './autoUpdate.js';
+const [installedVersion, packageRoot, token] = process.argv.slice(2);
+if (installedVersion && packageRoot && token) {
+    await runCliAutoUpdate(installedVersion, packageRoot, token);
+}

package/dist/bin.js

@@ -1,3 +1,6 @@
 #!/usr/bin/env node
 import { runMearlCli } from './cli.js';
+import { CLIENT_VERSION } from './socket.js';
+import { scheduleCliAutoUpdate } from './autoUpdate.js';
 process.exitCode = await runMearlCli(process.argv.slice(2));
+scheduleCliAutoUpdate(CLIENT_VERSION);

package/dist/check.d.ts

@@ -67,6 +67,13 @@ export interface UnifiedCheckResult {
     connectors: CloudConnectorInfo[];
     environment: CheckItem[];
     ok: boolean;
+    updates?: UnifiedCheckUpdate[];
+}
+export interface UnifiedCheckUpdate {
+    component: string;
+    installed: string;
+    latest?: string;
+    status: 'current' | 'available' | 'unavailable';
 }
 interface CheckClient {
     invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
@@ -82,12 +89,16 @@ export interface UnifiedCheckOptions {
     local?: boolean;
     transport?: 'cdp';
     json?: boolean;
+    checkUpdates?: boolean;
 }
 export interface UnifiedCheckDependencies {
     createClient?: (options: UnifiedClientOptions) => CheckClient;
     writeJson?: (json: string) => void;
     writeLine?: (line: string) => void;
+    fetchLatestVersion?: (component: string) => Promise<string>;
 }
+export declare function parseReleaseVersion(value: unknown): number[] | null;
+export declare function isNewerRelease(latest: string, installed: string): boolean;
 export declare function parseCheckTimeout(value: string | undefined): number | null;
 export declare function runUnifiedCheck(options: UnifiedCheckOptions & {
     json: true;

package/dist/check.js

@@ -1,4 +1,45 @@
 import { UnifiedClient, normalizeBrowserSelector, } from './unified.js';
+const UPDATE_SOURCES = {
+    client: 'https://registry.npmjs.org/@mearl%2Fclient/latest',
+    'native-host': 'https://registry.npmjs.org/@mearl%2Fnative-host/latest',
+    'cloud-connector': 'https://registry.npmjs.org/@mearl%2Fcloud-connector/latest',
+    extension: 'https://mearl.alibaba-inc.com/config.json',
+};
+export function parseReleaseVersion(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-beta\.(0|[1-9]\d*))?$/.exec(value);
+    if (!match)
+        return null;
+    const parts = [Number(match[1]), Number(match[2]), Number(match[3]), Number(match[4] ?? 0)];
+    if (!parts.every(Number.isSafeInteger))
+        return null;
+    return [...parts.slice(0, 3), match[4] === undefined ? 1 : 0, parts[3]];
+}
+export function isNewerRelease(latest, installed) {
+    const latestParts = parseReleaseVersion(latest);
+    const installedParts = parseReleaseVersion(installed);
+    if (!latestParts || !installedParts)
+        return false;
+    for (let index = 0; index < latestParts.length; index++) {
+        if (latestParts[index] !== installedParts[index]) {
+            return latestParts[index] > installedParts[index];
+        }
+    }
+    return false;
+}
+async function fetchLatestVersion(component) {
+    const response = await fetch(UPDATE_SOURCES[component], {
+        signal: AbortSignal.timeout(1500),
+    });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}`);
+    const payload = (await response.json());
+    const version = component === 'extension' ? payload.latestVersion : payload.version;
+    if (!parseReleaseVersion(version))
+        throw new Error('Invalid release version');
+    return version;
+}
 function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -98,6 +139,9 @@ export async function runUnifiedCheck(options, dependencies = {}) {
         connectTimeoutSec: timeoutSec,
         requestTimeoutSec: timeoutSec,
     });
+    const latestVersions = options.checkUpdates
+        ? Promise.allSettled(Object.keys(UPDATE_SOURCES).map(component => (dependencies.fetchLatestVersion ?? fetchLatestVersion)(component)))
+        : null;
     const environment = [
         { status: 'ok', label: `Unified client v${options.clientVersion}` },
     ];
@@ -301,6 +345,67 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 });
             }
         }));
+        let updates;
+        if (latestVersions) {
+            const latestResults = await latestVersions;
+            const components = Object.keys(UPDATE_SOURCES);
+            const installed = new Map();
+            const addInstalled = (component, version) => {
+                if (!version)
+                    return;
+                const versions = installed.get(component) ?? new Set();
+                versions.add(version);
+                installed.set(component, versions);
+            };
+            addInstalled('client', options.clientVersion);
+            for (const check of browserChecks) {
+                addInstalled('native-host', check.versions?.nativeHost);
+                addInstalled('extension', check.versions?.extension);
+            }
+            for (const connector of connectors)
+                addInstalled('cloud-connector', connector.version);
+            updates = components.flatMap((component, index) => {
+                const result = latestResults[index];
+                return [...(installed.get(component) ?? [])].map(version => ({
+                    component,
+                    installed: version,
+                    ...(result.status === 'fulfilled' ? { latest: result.value } : {}),
+                    status: result.status === 'rejected' ||
+                        !parseReleaseVersion(version) ||
+                        !parseReleaseVersion(result.value)
+                        ? 'unavailable'
+                        : isNewerRelease(result.value, version)
+                            ? 'available'
+                            : 'current',
+                }));
+            });
+            const available = updates.filter(update => update.status === 'available');
+            const unavailable = updates.filter(update => update.status === 'unavailable');
+            const packageUpdateAvailable = available.some(update => update.component === 'client' || update.component === 'native-host');
+            const extensionUpdateAvailable = available.some(update => update.component === 'extension');
+            const connectorUpdateAvailable = available.some(update => update.component === 'cloud-connector');
+            environment.push({
+                status: available.length || unavailable.length ? 'warning' : 'ok',
+                label: available.length
+                    ? `${available.length} Mearl update${available.length === 1 ? '' : 's'} available`
+                    : unavailable.length
+                        ? 'Mearl update check incomplete'
+                        : 'Mearl packages are current',
+                details: [
+                    ...available.map(update => `${update.component}: ${update.installed} → ${update.latest}`),
+                    ...(packageUpdateAvailable
+                        ? ['Update on the affected machine: npx @mearl/setup update']
+                        : []),
+                    ...(extensionUpdateAvailable
+                        ? ['Update a setup-managed extension: npx @mearl/setup extension']
+                        : []),
+                    ...(connectorUpdateAvailable
+                        ? ['Update cloud-connector with its package manager on the connector machine.']
+                        : []),
+                    ...unavailable.map(update => `${update.component}: latest version unavailable`),
+                ],
+            });
+        }
         const hasError = environment.some(item => item.status === 'error') ||
             browserChecks.some(check => check.item.status === 'error');
         const listedBrowsers = browserList?.browsers ?? [];
@@ -336,6 +441,7 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 connectors,
                 environment,
                 ok: !hasError,
+                ...(updates ? { updates } : {}),
             };
             writeJson(JSON.stringify(result, null, 2));
             return result;

package/dist/cli.d.ts

@@ -10,6 +10,7 @@ export interface ParsedArgs {
     forceCdp: boolean;
     json: boolean;
     local: boolean;
+    updates: boolean;
     outputPath?: string;
     payload: Record<string, any>;
     serverUrl?: string;

package/dist/cli.js

@@ -77,6 +77,7 @@ const PLUGIN_HOST_OPTIONS = new Set([
     '--help',
     '--json',
     '--local',
+    '--updates',
     '--output',
     '--payload',
     '--payload-file',
@@ -266,6 +267,7 @@ function printCheckHelp(commandName) {
         '  --server <url>        覆盖 cloud-server WebSocket URL',
         '  --timeout <seconds>   单项检查超时时间，默认 5 秒',
         '  --json                输出机器可读 JSON',
+        '  --updates            查询已安装组件的发布版本',
         '  -h, --help            查看帮助',
     ].join('\n'));
 }
@@ -409,6 +411,7 @@ export function parseClientArgs(args, plugin = false) {
         .option('--browser <id-or-name>')
         .option('--connector <id-or-name>')
         .option('--local')
+        .option('--updates')
         .option('--cdp')
         .option('--server <url>');
     if (plugin)
@@ -442,6 +445,8 @@ export function parseClientArgs(args, plugin = false) {
     const json = options.json === true;
     if (json && action !== 'check')
         throw new Error('--json 仅适用于 check');
+    if (options.updates && action !== 'check')
+        throw new Error('--updates 仅适用于 check');
     const parsedPayload = parsePayload(options.payload, options.payloadFile);
     const { payload, outputPath } = normalizeScreenshotOutput(action, parsedPayload, options.output);
     const fallbackTimeout = resolveActionTimeoutSec(action, payload, 60);
@@ -459,6 +464,7 @@ export function parseClientArgs(args, plugin = false) {
         forceCdp,
         json,
         local,
+        updates: options.updates === true,
         ...(outputPath ? { outputPath } : {}),
         ...(options.browser ? { browser: options.browser } : {}),
         ...(connector ? { connector } : {}),
@@ -645,6 +651,7 @@ export async function runMearlCli(args, options = {}) {
             ...(parsed.connector ? { connector: parsed.connector } : {}),
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
+            ...(parsed.updates ? { checkUpdates: true } : {}),
         };
         if (parsed.json) {
             const result = await runUnifiedCheck({ ...checkOptions, json: true });

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

@@ -348,7 +348,7 @@ export interface PageScreenshotParams {
     format?: 'png' | 'jpeg';
     quality?: number;
 }
-export declare const BROWSER_DEVICE_PRESET_NAMES: readonly ["iphone-17-pro", "iphone-17e", "pixel-11", "ipad-mini-a17-pro", "galaxy-s26", "pura-x-max", "iphone-15-pro", "iphone-se", "pixel-8", "ipad-mini", "galaxy-s23"];
+export declare const BROWSER_DEVICE_PRESET_NAMES: readonly ["iphone-duo-folded", "iphone-duo-unfolded", "iphone-17-pro", "iphone-17e", "pixel-11", "ipad-mini-a17-pro", "galaxy-s26", "pura-x-max", "iphone-15-pro", "iphone-se", "pixel-8", "ipad-mini", "galaxy-s23"];
 export type BrowserDevicePresetName = (typeof BROWSER_DEVICE_PRESET_NAMES)[number];
 export interface BrowserEmulationOptions {
     preset?: BrowserDevicePresetName;
@@ -365,7 +365,7 @@ export interface BrowserEmulationOptions {
     /** App 容器横屏时将根页面与业务页面分置左右 WebView；仅与 deviceShell、App 档案同时生效。 */
     splitScreen?: boolean;
 }
-export type AppBridgeConfigBehavior = 'navigate' | 'closeAll' | 'closeBackData' | 'postMessage' | 'notifySubscribe' | 'notifyUnsubscribe' | 'notifyPost' | 'sharedFileRead' | 'sharedFileWrite' | 'sharedDataGet' | 'sharedDataSet' | 'legacyBroadcastCreate' | 'legacyBroadcastPost' | 'legacyBroadcastClose' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'networkInfo' | 'geolocation' | 'permission' | 'imagePicker' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest' | 'voiceRecognition';
+export type AppBridgeConfigBehavior = 'navigate' | 'closeAll' | 'closeBackData' | 'postMessage' | 'notifySubscribe' | 'notifyUnsubscribe' | 'notifyPost' | 'sharedFileRead' | 'sharedFileWrite' | 'sharedDataGet' | 'sharedDataSet' | 'legacyBroadcastCreate' | 'legacyBroadcastPost' | 'legacyBroadcastClose' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'authCode' | 'networkInfo' | 'geolocation' | 'permission' | 'imagePicker' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest' | 'voiceRecognition';
 /** 单个桥方法的声明式覆盖；行为、固定回包、成功空实现三选一。 */
 export interface AppBridgeMethodConfig {
     behavior?: AppBridgeConfigBehavior;
@@ -421,6 +421,8 @@ export interface SetAppProfileParams {
     profile?: AppProfileName;
     os?: 'ios' | 'android';
     appVersion?: string;
+    /** 支付宝容器语言；其他容器忽略。 */
+    language?: 'zh-CN' | 'zh-TW' | 'zh-HK' | 'en-US';
     deviceModel?: string;
     /** 按方法覆盖档案内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现 */
     bridgeConfig?: AppBridgeConfig;

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

@@ -7,6 +7,8 @@ export const SEND_REQUEST_MAX_TOTAL_FILE_BYTES = 40 * 1024 * 1024;
 // the 10 MiB cloud message limit.
 export const SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES = 7 * 1024 * 1024;
 export const BROWSER_DEVICE_PRESET_NAMES = [
+    'iphone-duo-folded',
+    'iphone-duo-unfolded',
     'iphone-17-pro',
     'iphone-17e',
     'pixel-11',

package/dist/pluginPageBundle.js

@@ -84,6 +84,32 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     await requestHost('clipboard-write', { text });
   };
 
+  const openExternalLink = async url => {
+    if (typeof url !== 'string' || !url || url.length > 8192) {
+      throw new Error('External link must be a non-empty URL no longer than 8192 characters');
+    }
+    await requestHost('open-external-link', { url });
+  };
+
+  const handleExternalLinkClick = event => {
+    if (event.defaultPrevented || event.button !== 0) return;
+    const link = event.target?.closest?.('a[href]');
+    if (!link || String(link.target).toLowerCase() !== '_blank' || link.hasAttribute?.('download')) {
+      return;
+    }
+    let url;
+    try {
+      url = new URL(link.href);
+    } catch {
+      return;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return;
+    event.preventDefault();
+    void openExternalLink(url.href).catch(error => {
+      console.error('Failed to open external link', error);
+    });
+  };
+
   const toast = async (message, options = {}) => {
     if (typeof message !== 'string' || !message.trim() || message.length > 4000) {
       throw new Error('Toast message must be a non-empty string no longer than 4000 characters');
@@ -106,16 +132,213 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
       throw new Error('Agent panel options must be an object');
     }
     const layout = options.layout;
-    if (layout !== undefined && layout !== 'drawer' && layout !== 'workspace') {
-      throw new Error('Agent panel layout must be drawer or workspace');
+    if (layout !== undefined && layout !== 'drawer' && layout !== 'workspace' && layout !== 'inline') {
+      throw new Error('Agent panel layout must be drawer, workspace, or inline');
     }
     return layout;
   };
 
+  const agentPanelKey = (options, required = false) => {
+    const key = typeof options.key === 'string' ? options.key.trim() : '';
+    if ((required || options.key !== undefined) && (!key || key.length > 128)) {
+      throw new Error('Agent panel key must be a non-empty string no longer than 128 characters');
+    }
+    return key || null;
+  };
+
+  const agentPanelCwd = options => {
+    const cwd = options.cwd;
+    if (
+      cwd !== undefined &&
+      (typeof cwd !== 'string' ||
+        !cwd.trim() ||
+        cwd.length > 4096 ||
+        !/^(?:\/|[a-zA-Z]:[\\/])/.test(cwd.trim()))
+    ) {
+      throw new Error('Agent panel cwd must be an absolute path no longer than 4096 characters');
+    }
+    return cwd === undefined ? null : cwd.trim();
+  };
+
+  const agentPanelContext = options => {
+    const context = options.context;
+    if (
+      context !== undefined &&
+      (typeof context !== 'string' || !context.trim() || context.length > 65536)
+    ) {
+      throw new Error('Agent panel context must be a non-empty string no longer than 65536 characters');
+    }
+    return context === undefined ? null : context.trim();
+  };
+
+  const inlineAgentPanels = new Map();
+
+  const stopInlineAgentPanelTracking = key => {
+    if (key) {
+      inlineAgentPanels.get(key)?.cleanup();
+      inlineAgentPanels.delete(key);
+      return;
+    }
+    for (const tracked of inlineAgentPanels.values()) tracked.cleanup();
+    inlineAgentPanels.clear();
+  };
+
+  const inlineAgentPanelAnchor = (options, key) => {
+    const anchor = options.anchor;
+    if (!(anchor instanceof Element)) {
+      throw new Error('Inline Agent panel anchor must be an element');
+    }
+    const rect = anchor.getBoundingClientRect();
+    if (![rect.top, rect.left, rect.width, rect.height].every(Number.isFinite)) {
+      throw new Error('Inline Agent panel anchor returned invalid bounds');
+    }
+    return {
+      element: anchor,
+      key,
+      bounds: { top: rect.top, left: rect.left, width: rect.width, height: rect.height },
+    };
+  };
+
+  const trackInlineAgentPanel = presentation => {
+    stopInlineAgentPanelTracking(presentation.key);
+    let frame = null;
+    const update = () => {
+      frame = null;
+      if (!presentation.element.isConnected || !port) return;
+      const rect = presentation.element.getBoundingClientRect();
+      if (![rect.top, rect.left, rect.width, rect.height].every(Number.isFinite)) return;
+      const bounds = { top: rect.top, left: rect.left, width: rect.width, height: rect.height };
+      if (
+        bounds.top === presentation.bounds.top &&
+        bounds.left === presentation.bounds.left &&
+        bounds.width === presentation.bounds.width &&
+        bounds.height === presentation.bounds.height
+      ) return;
+      presentation.bounds = bounds;
+      port.postMessage({
+        type: 'agent-panel-position',
+        key: presentation.key,
+        bounds,
+      });
+    };
+    const schedule = () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(update);
+    };
+    const observer = typeof ResizeObserver === 'function' ? new ResizeObserver(schedule) : null;
+    observer?.observe(presentation.element);
+    observer?.observe(document.documentElement);
+    const mutationObserver = typeof MutationObserver === 'function'
+      ? new MutationObserver(schedule)
+      : null;
+    mutationObserver?.observe(document.documentElement, {
+      attributes: true,
+      childList: true,
+      characterData: true,
+      subtree: true,
+    });
+    window.addEventListener('resize', schedule);
+    document.addEventListener('scroll', schedule, true);
+    const cleanup = () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      observer?.disconnect();
+      mutationObserver?.disconnect();
+      window.removeEventListener('resize', schedule);
+      document.removeEventListener('scroll', schedule, true);
+    };
+    inlineAgentPanels.set(presentation.key, { presentation, cleanup });
+  };
+
+  const scrollInlineAgentPage = (presentation, deltaX, deltaY) => {
+    const scrollAxis = (axis, delta) => {
+      if (!delta) return;
+      let element = presentation.element;
+      while (element) {
+        const style = window.getComputedStyle(element);
+        const overflow = axis === 'x' ? style.overflowX : style.overflowY;
+        const scrollSize = axis === 'x' ? element.scrollWidth : element.scrollHeight;
+        const clientSize = axis === 'x' ? element.clientWidth : element.clientHeight;
+        if (/^(auto|scroll|overlay)$/.test(overflow) && scrollSize > clientSize) {
+          const scrollPosition = axis === 'x' ? element.scrollLeft : element.scrollTop;
+          const maximum = scrollSize - clientSize;
+          if ((delta < 0 && scrollPosition > 0) || (delta > 0 && scrollPosition < maximum - 1)) {
+            if (axis === 'x') element.scrollLeft += delta;
+            else element.scrollTop += delta;
+            return;
+          }
+        }
+        element = element.parentElement;
+      }
+      window.scrollBy(axis === 'x' ? delta : 0, axis === 'y' ? delta : 0);
+    };
+    scrollAxis('x', deltaX);
+    scrollAxis('y', deltaY);
+  };
+
+  const agentPanelPresentation = (options, layout, key) => {
+    if (layout !== 'inline') return null;
+    return inlineAgentPanelAnchor(options, key);
+  };
+
   const setAgentPanelVisible = async (visible, options = {}) => {
     if (typeof visible !== 'boolean') throw new Error('Agent panel visibility must be a boolean');
     const layout = agentPanelLayout(options);
-    await requestHost('agent-panel', { visible, ...(layout ? { layout } : {}) });
+    const key = agentPanelKey(options, visible && layout === 'inline');
+    const cwd = visible ? agentPanelCwd(options) : null;
+    const context = visible ? agentPanelContext(options) : null;
+    const presentation = visible ? agentPanelPresentation(options, layout, key) : null;
+    const request = requestHost('agent-panel', {
+      visible,
+      ...(layout ? { layout } : {}),
+      ...(key ? { key } : {}),
+      ...(cwd ? { cwd } : {}),
+      ...(context ? { context } : {}),
+      ...(presentation ? { bounds: presentation.bounds } : {}),
+    });
+    if (presentation) {
+      await ready;
+      trackInlineAgentPanel(presentation);
+    } else if (!visible && key) {
+      stopInlineAgentPanelTracking(key);
+    } else {
+      stopInlineAgentPanelTracking();
+    }
+    try {
+      await request;
+    } catch (error) {
+      if (presentation) stopInlineAgentPanelTracking(presentation.key);
+      throw error;
+    }
+  };
+
+  const agentGuideText = (value, label, maximumLength) => {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    if (!normalized || normalized.length > maximumLength) {
+      throw new Error(label + ' must be a non-empty string no longer than ' + maximumLength + ' characters');
+    }
+    return normalized;
+  };
+
+  const setAgentGuides = async guides => {
+    if (!Array.isArray(guides) || guides.length === 0 || guides.length > 6) {
+      throw new Error('Agent guides must contain between 1 and 6 items');
+    }
+    const normalized = guides.map((guide, index) => {
+      if (!guide || typeof guide !== 'object' || Array.isArray(guide)) {
+        throw new Error('Agent guide ' + index + ' must be an object');
+      }
+      const icon = guide.icon === undefined ? undefined : agentGuideText(guide.icon, 'Agent guide icon', 40);
+      if (icon && !/^[a-z][a-z0-9-]*$/.test(icon)) {
+        throw new Error('Agent guide icon must use kebab-case');
+      }
+      return {
+        title: agentGuideText(guide.title, 'Agent guide title', 80),
+        description: agentGuideText(guide.description, 'Agent guide description', 160),
+        prompt: agentGuideText(guide.prompt, 'Agent guide prompt', 4000),
+        ...(icon ? { icon } : {}),
+      };
+    });
+    await requestHost('agent-guides', { guides: normalized });
   };
 
   const runAgentTask = async (prompt, options = {}) => {
@@ -126,7 +349,13 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
       throw new Error('Agent task options must be an object');
     }
     const cwd = options.cwd;
+    const ephemeral = options.ephemeral;
     const layout = agentPanelLayout(options);
+    const key = agentPanelKey(options, layout === 'inline');
+    const presentation = agentPanelPresentation(options, layout, key);
+    if (ephemeral !== undefined && ephemeral !== false) {
+      throw new Error('Temporary Agent conversations are not supported');
+    }
     if (
       cwd !== undefined &&
       (typeof cwd !== 'string' ||
@@ -136,11 +365,25 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     ) {
       throw new Error('Agent task cwd must be an absolute path no longer than 4096 characters');
     }
-    await requestHost('agent-task', {
+    const request = requestHost('agent-task', {
       prompt: prompt.trim(),
       ...(cwd !== undefined ? { cwd: cwd.trim() } : {}),
       ...(layout ? { layout } : {}),
+      ...(key ? { key } : {}),
+      ...(presentation ? { bounds: presentation.bounds } : {}),
     });
+    if (presentation) {
+      await ready;
+      trackInlineAgentPanel(presentation);
+    } else {
+      stopInlineAgentPanelTracking();
+    }
+    try {
+      await request;
+    } catch (error) {
+      if (presentation) stopInlineAgentPanelTracking(presentation.key);
+      throw error;
+    }
   };
 
   const setQueryParam = async (name, value) => {
@@ -155,7 +398,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     return query;
   };
 
-  const api = { copyText, invoke, operation, ready: () => ready, runAgentTask, runningOperations, selectDirectory, setAgentPanelVisible, setQueryParam, start, toast };
+  const api = { copyText, invoke, operation, ready: () => ready, runAgentTask, runningOperations, selectDirectory, setAgentGuides, setAgentPanelVisible, setQueryParam, start, toast };
   const ui = globalThis.__mearlToolboxUi;
   if (ui !== undefined) {
     if (!ui || typeof ui !== 'object' || ui.runtime !== 'preact') {
@@ -166,6 +409,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   }
   Object.defineProperty(api, 'context', { enumerable: true, get: () => context });
   Object.defineProperty(window, 'mearl', { configurable: false, value: Object.freeze(api) });
+  document.addEventListener('click', handleExternalLinkClick);
 
   const applyContext = nextContext => {
     const theme =
@@ -198,6 +442,22 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
         applyContext(response.context);
         return;
       }
+      if (
+        response?.type === 'agent-panel-wheel' &&
+        typeof response.key === 'string' &&
+        inlineAgentPanels.has(response.key) &&
+        typeof response.deltaX === 'number' &&
+        Number.isFinite(response.deltaX) &&
+        typeof response.deltaY === 'number' &&
+        Number.isFinite(response.deltaY)
+      ) {
+        scrollInlineAgentPage(
+          inlineAgentPanels.get(response.key).presentation,
+          response.deltaX,
+          response.deltaY,
+        );
+        return;
+      }
       if (response?.type !== 'result' || typeof response.requestId !== 'string') return;
       const request = pending.get(response.requestId);
       if (!request) return;

package/dist/unifiedConfig.d.ts

@@ -1,6 +1,8 @@
 export interface CloudServerConfig {
     server: string;
 }
+/** Number of local calendar days between CLI update checks; null disables them. */
+export declare function loadCliAutoUpdateIntervalDays(configPath?: string): number | null;
 export declare function getCloudServerConfigPath(): string;
 export declare function loadCloudServerConfig(): CloudServerConfig | null;
 export declare function loadLocalConnectorId(): string | null;

package/dist/unifiedConfig.js

@@ -2,6 +2,29 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 const MEARL_CONFIG_DIR = join(homedir(), '.mearl');
+/** Number of local calendar days between CLI update checks; null disables them. */
+export function loadCliAutoUpdateIntervalDays(configPath = join(MEARL_CONFIG_DIR, 'config.json')) {
+    try {
+        const config = JSON.parse(readFileSync(configPath, 'utf8'));
+        if (config.cliAutoUpdate === false)
+            return null;
+        if (config.cliAutoUpdate === undefined)
+            return 1;
+        if (typeof config.cliAutoUpdate === 'object' &&
+            config.cliAutoUpdate !== null &&
+            !Array.isArray(config.cliAutoUpdate)) {
+            const { intervalDays } = config.cliAutoUpdate;
+            if (typeof intervalDays === 'number' &&
+                Number.isSafeInteger(intervalDays) &&
+                intervalDays > 0)
+                return intervalDays;
+        }
+    }
+    catch {
+        // A missing or invalid config uses the daily default.
+    }
+    return 1;
+}
 export function getCloudServerConfigPath() {
     return join(MEARL_CONFIG_DIR, 'cloud-server.json');
 }

package/package.json

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