@mearl/setup 2.3.0 → 2.5.0

package/README.md

@@ -1,11 +1,21 @@
 # @mearl/setup
 
-Mearl 环境的一次性安装、更新与卸载工具。无需先全局安装 setup：
+Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
 ```bash
 npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
 ```
 
+配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
+重复执行会更新现有 Key，并保留 `~/.mearl/.env` 中的其他配置：
+
+```bash
+npx @mearl/setup agentbay
+```
+
+无交互环境可使用 `--stdin` 或 `--key-file <path>`。为避免 Key 进入 shell history 和
+进程参数，不接受把 Key 直接写在命令行中。
+
 ## 行为
 
 - `install` 未指定环境时默认 `--local`。
@@ -14,10 +24,24 @@ npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
   多个已安装环境。
 - 显式传入 `--local`、`--cloud` 或 `--mcp` 时只处理指定环境。
 - 已有环境沿用其原包管理器和全局安装前缀；首次安装沿用启动 setup 的包管理器。
+- cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/cloud-client`：首次安装后启动
+  Server，更新后仅在 Server 原本运行时重启，卸载前停止。
 - local/cloud 共用的全局 mearl skill 通过 `ali-skills` 的 JSON 清单定位，只处理一次。
 - 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
 
+## 跟随浏览器扩展自动更新
+
+浏览器扩展与 Native Host 首次建联时会交换版本。每次扩展后台启动只检查一次；当扩展
+进入更高的 `major.minor` release line 时，旧 Host 会在保持当前连接可用的前提下，调用
+对应 `major.minor.x` 范围内最新的 `@mearl/setup`，把 `@mearl/native-host` 与
+`@mearl/client` 一起更新到该范围内的最新版本。成功后 Host 退出，扩展通过已有重连机制
+启动新版本。只有两个本地 CLI 版本一致且都属于扩展的 release line 时，更新才会被视为成功。
+
+自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
+目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
+生命周期可重新尝试，也可手动执行 `npx @mearl/setup update --local`。
+
 ## 人工与 Agent 使用
 
 - 人工在终端执行时不加 `--yes`，需要选择 Skill 安装目标或 MCP 客户端时会显示交互提示。
@@ -47,6 +71,12 @@ npx @mearl/setup uninstall --local
 
 # 自动检测并无交互卸载
 npx @mearl/setup uninstall --yes
+
+# 配置或更新 AgentBay API Key
+npx @mearl/setup agentbay
+
+# 无交互配置（从权限受控的文件读取）
+npx @mearl/setup agentbay --key-file ./agentbay.key
 ```
 
 原有的 npm/npx 安装方式和各包 CLI 保持可用；setup 只是统一的便利入口。

package/dist/agentBay.d.ts

@@ -0,0 +1,23 @@
+export interface AgentBayConfigurationOptions {
+    envFile?: string;
+}
+export interface AgentBayConfigurationResult {
+    envFile: string;
+    updated: boolean;
+}
+export interface AgentBaySecretInput {
+    isRaw?: boolean;
+    isTTY?: boolean;
+    on(event: 'data', listener: (chunk: Buffer | string) => void): unknown;
+    pause(): unknown;
+    removeListener(event: 'data', listener: (chunk: Buffer | string) => void): unknown;
+    resume(): unknown;
+    setRawMode?(mode: boolean): unknown;
+}
+export interface AgentBaySecretOutput {
+    write(value: string): unknown;
+}
+export declare function readAgentBayApiKeyFile(file: string): string;
+export declare function readAgentBayApiKeyStdin(input?: NodeJS.ReadableStream): Promise<string>;
+export declare function promptAgentBayApiKey(input?: AgentBaySecretInput, output?: AgentBaySecretOutput): Promise<string>;
+export declare function configureAgentBayApiKey(apiKey: string, options?: AgentBayConfigurationOptions): AgentBayConfigurationResult;

package/dist/agentBay.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const AGENTBAY_ENV_KEY = 'AGENTBAY_KEY';
+const AGENTBAY_ENV_LINE = /^\s*(?:export\s+)?AGENTBAY_KEY\s*=/;
+function normalizeApiKey(apiKey) {
+    const value = apiKey.trim();
+    if (!value)
+        throw new Error('AgentBay API key is required.');
+    if (/[\r\n\0]/.test(value)) {
+        throw new Error('AgentBay API key must be a single-line value.');
+    }
+    return value;
+}
+export function readAgentBayApiKeyFile(file) {
+    const resolved = path.resolve(file);
+    return normalizeApiKey(fs.readFileSync(resolved, 'utf8'));
+}
+export async function readAgentBayApiKeyStdin(input = process.stdin) {
+    let value = '';
+    for await (const chunk of input)
+        value += chunk.toString();
+    return normalizeApiKey(value);
+}
+export function promptAgentBayApiKey(input = process.stdin, output = process.stderr) {
+    if (!input.isTTY || !input.setRawMode) {
+        return Promise.reject(new Error('A TTY is required to enter the AgentBay API key securely.'));
+    }
+    const setRawMode = input.setRawMode.bind(input);
+    return new Promise((resolvePrompt, rejectPrompt) => {
+        const wasRaw = input.isRaw === true;
+        let value = '';
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            input.removeListener('data', onData);
+            setRawMode(wasRaw);
+            input.pause();
+            output.write('\n');
+            if (error)
+                rejectPrompt(error);
+            else {
+                try {
+                    resolvePrompt(normalizeApiKey(value));
+                }
+                catch (validationError) {
+                    rejectPrompt(validationError instanceof Error ? validationError : new Error(String(validationError)));
+                }
+            }
+        };
+        const onData = (chunk) => {
+            for (const character of chunk.toString()) {
+                if (character === '\u0003') {
+                    finish(new Error('AgentBay API key input cancelled.'));
+                    return;
+                }
+                if (character === '\r' || character === '\n') {
+                    finish();
+                    return;
+                }
+                if (character === '\u007f' || character === '\b') {
+                    value = Array.from(value).slice(0, -1).join('');
+                    continue;
+                }
+                if (character >= ' ')
+                    value += character;
+            }
+        };
+        output.write('AgentBay API key: ');
+        setRawMode(true);
+        input.resume();
+        input.on('data', onData);
+    });
+}
+function updateEnvContent(content, apiKey) {
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content ? content.split(/\r?\n/) : [];
+    if (lines.at(-1) === '')
+        lines.pop();
+    const entry = `${AGENTBAY_ENV_KEY}=${apiKey}`;
+    const output = [];
+    let updated = false;
+    for (const line of lines) {
+        if (!AGENTBAY_ENV_LINE.test(line)) {
+            output.push(line);
+            continue;
+        }
+        if (!updated)
+            output.push(entry);
+        updated = true;
+    }
+    if (!updated)
+        output.push(entry);
+    return { content: `${output.join(newline)}${newline}`, updated };
+}
+export function configureAgentBayApiKey(apiKey, options = {}) {
+    const value = normalizeApiKey(apiKey);
+    const envFile = options.envFile ?? path.join(os.homedir(), '.mearl', '.env');
+    let current = '';
+    try {
+        current = fs.readFileSync(envFile, 'utf8');
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const next = updateEnvContent(current, value);
+    fs.mkdirSync(path.dirname(envFile), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(envFile, next.content, { encoding: 'utf8', mode: 0o600 });
+    fs.chmodSync(envFile, 0o600);
+    return { envFile, updated: next.updated };
+}

package/dist/cli.d.ts

@@ -1,12 +1,23 @@
 #!/usr/bin/env node
+import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin } from './agentBay.js';
 import { type MearlLifecycleOperation } from './lifecycle.js';
 import type { MearlProfile } from './profiles.js';
 interface ParsedArgs {
+    agentBayKeyFile?: string;
+    agentBayReadStdin: boolean;
     help: boolean;
-    operation?: MearlLifecycleOperation;
+    operation?: MearlLifecycleOperation | 'agentbay';
     profile?: MearlProfile;
+    skipSkill: boolean;
+    targetLine?: string;
     yes: boolean;
 }
+export interface SetupCliDependencies {
+    configureAgentBay?: typeof configureAgentBayApiKey;
+    promptAgentBayKey?: typeof promptAgentBayApiKey;
+    readAgentBayKeyFile?: typeof readAgentBayApiKeyFile;
+    readAgentBayKeyStdin?: typeof readAgentBayApiKeyStdin;
+}
 export declare function parseSetupArgs(argv: string[]): ParsedArgs;
-export declare function main(argv?: string[], interactiveTerminal?: boolean): Promise<number>;
+export declare function main(argv?: string[], interactiveTerminal?: boolean, dependencies?: SetupCliDependencies): Promise<number>;
 export {};

package/dist/cli.js

@@ -1,22 +1,71 @@
 #!/usr/bin/env node
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 import { runMearlLifecycle } from './lifecycle.js';
+import { isMearlReleaseLine } from './version.js';
 export function parseSetupArgs(argv) {
     if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
-        return { help: true, yes: false };
+        return { agentBayReadStdin: false, help: true, skipSkill: false, yes: false };
     }
     const operation = argv[0];
+    if (operation === 'agentbay') {
+        if (argv.length === 1) {
+            return {
+                agentBayReadStdin: false,
+                help: false,
+                operation,
+                skipSkill: false,
+                yes: false,
+            };
+        }
+        if (argv.length === 2 && argv[1] === '--stdin') {
+            return {
+                agentBayReadStdin: true,
+                help: false,
+                operation,
+                skipSkill: false,
+                yes: false,
+            };
+        }
+        if (argv.length === 3 && argv[1] === '--key-file' && argv[2]?.trim()) {
+            return {
+                agentBayKeyFile: argv[2],
+                agentBayReadStdin: false,
+                help: false,
+                operation,
+                skipSkill: false,
+                yes: false,
+            };
+        }
+        throw new Error('Usage: npx @mearl/setup agentbay [--stdin | --key-file <path>]. API keys are not accepted as command-line arguments.');
+    }
     if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
         throw new Error(`Unknown operation: ${operation}`);
     }
     let profile;
+    let skipSkill = false;
+    let targetLine;
     let yes = false;
-    for (const arg of argv.slice(1)) {
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
         if (arg === '--yes' || arg === '-y' || arg === '--non-interactive') {
             yes = true;
             continue;
         }
+        if (arg === '--skip-skill') {
+            skipSkill = true;
+            continue;
+        }
+        if (arg === '--target-line') {
+            const value = argv[index + 1];
+            if (!isMearlReleaseLine(value)) {
+                throw new Error('--target-line requires a valid Mearl release line such as 2.3.x');
+            }
+            targetLine = value;
+            index += 1;
+            continue;
+        }
         const candidate = arg === '--local'
             ? 'local'
             : arg === '--cloud'
@@ -31,23 +80,41 @@ export function parseSetupArgs(argv) {
         }
         profile = candidate;
     }
-    return { help: false, operation, profile, yes };
+    if (operation === 'uninstall' && targetLine) {
+        throw new Error('--target-line is not available for uninstall');
+    }
+    return {
+        agentBayReadStdin: false,
+        help: false,
+        operation,
+        profile,
+        skipSkill,
+        targetLine,
+        yes,
+    };
 }
 function printHelp() {
     console.error(`Mearl Setup
 
 Usage:
   npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
+  npx @mearl/setup agentbay [--stdin | --key-file <path>]
 
 Behavior:
   install      Defaults to --local when no environment is specified
   update       Auto-detects installed environments from the current PATH
   uninstall    Auto-detects installed environments and asks for confirmation
+  agentbay     Save or update AGENTBAY_KEY without changing other Mearl settings
 
 Options:
   --local      Manage @mearl/native-host and @mearl/client
-  --cloud      Manage @mearl/cloud-client
+  --cloud      Manage @mearl/cloud-server and @mearl/cloud-client
   --mcp        Manage @mearl/mcp-server and its configuration
+  --stdin      Read the AgentBay API key from standard input
+  --key-file   Read the AgentBay API key from a local file
+  --target-line <major.minor.x>
+               Install the latest packages from one release line, such as 2.3.x
+  --skip-skill Keep the independently managed Mearl Skill unchanged
   --yes, -y    Run without prompts and accept detected defaults
   --non-interactive
                Alias for --yes, intended for Agents and CI
@@ -58,9 +125,11 @@ Examples:
   npx @mearl/setup install --yes
   npx @mearl/setup install --cloud
   npx @mearl/setup update
+  npx @mearl/setup agentbay
+  npx @mearl/setup update --local --target-line 2.3.x --skip-skill
   npx @mearl/setup uninstall --local`);
 }
-export async function main(argv = process.argv.slice(2), interactiveTerminal = process.stdin.isTTY === true && process.stdout.isTTY === true) {
+export async function main(argv = process.argv.slice(2), interactiveTerminal = process.stdin.isTTY === true && process.stdout.isTTY === true, dependencies = {}) {
     let parsed;
     try {
         parsed = parseSetupArgs(argv);
@@ -74,6 +143,31 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
         printHelp();
         return 0;
     }
+    if (parsed.operation === 'agentbay') {
+        try {
+            const configureAgentBay = dependencies.configureAgentBay ?? configureAgentBayApiKey;
+            let apiKey;
+            if (parsed.agentBayKeyFile) {
+                apiKey = (dependencies.readAgentBayKeyFile ?? readAgentBayApiKeyFile)(parsed.agentBayKeyFile);
+            }
+            else if (parsed.agentBayReadStdin) {
+                apiKey = await (dependencies.readAgentBayKeyStdin ?? readAgentBayApiKeyStdin)();
+            }
+            else {
+                if (!interactiveTerminal) {
+                    throw new Error('Interactive input is unavailable. Re-run with --stdin or --key-file <path>.');
+                }
+                apiKey = await (dependencies.promptAgentBayKey ?? promptAgentBayApiKey)();
+            }
+            const result = configureAgentBay(apiKey);
+            console.error(`AgentBay API key saved to ${result.envFile}.`);
+            return 0;
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
     if (!interactiveTerminal && !parsed.yes && parsed.operation !== 'update') {
         console.error('Non-interactive input detected. Re-run with --yes or --non-interactive.');
         return 2;
@@ -82,6 +176,8 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
         const ok = await runMearlLifecycle({
             operation: parsed.operation,
             profile: parsed.profile,
+            skipSkill: parsed.skipSkill,
+            targetLine: parsed.targetLine,
             yes: parsed.yes,
         });
         return ok ? 0 : 1;

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
+export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
+export type { AgentBayConfigurationOptions, AgentBayConfigurationResult, AgentBaySecretInput, AgentBaySecretOutput, } from './agentBay.js';
 export type { DetectedGlobalPackage, GlobalPackageCommand, GlobalPackageManager, PackageManagerInstallation, PackageOperation, PackageDetectionOptions, } from './packageManager.js';
 export { runMearlLifecycle } from './lifecycle.js';
 export type { MearlLifecycleDependencies, MearlLifecycleOperation, MearlLifecycleOptions, } from './lifecycle.js';
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export type { DetectedMearlProfiles, MearlProfile, MearlProfileConfig } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
+export { compareMearlReleaseLines, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
+export type { MearlReleaseLine, MearlReleaseVersion } from './version.js';
 export type { NativeHostCleanupDependencies, NativeHostCleanupOptions, NativeHostIntegrationMode, } from './nativeHost.js';

package/dist/index.js

@@ -1,4 +1,6 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
+export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 export { runMearlLifecycle } from './lifecycle.js';
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
+export { compareMearlReleaseLines, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';

package/dist/lifecycle.d.ts

@@ -8,6 +8,8 @@ export interface MearlLifecycleOptions {
     operation: MearlLifecycleOperation;
     profile?: MearlProfile;
     yes?: boolean;
+    targetLine?: string;
+    skipSkill?: boolean;
     env?: NodeJS.ProcessEnv;
 }
 export interface MearlLifecycleDependencies {

package/dist/lifecycle.js

@@ -7,6 +7,7 @@ import { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageM
 import { MEARL_PROFILES, detectMearlProfiles, } from './profiles.js';
 import { uninstallNativeHostArtifacts } from './nativeHost.js';
 import { executableNames, prependCommandPath, runCommand, } from './process.js';
+import { isMearlReleaseLine } from './version.js';
 async function confirmInTerminal(message) {
     if (!input.isTTY || !output.isTTY)
         return false;
@@ -27,10 +28,10 @@ function siblingExecutable(anchor, name, existsSync) {
     }
     return null;
 }
-async function runLifecycleCommand(runner, command, args, env, label, writeLine) {
+async function runLifecycleCommand(runner, command, args, env, label, writeLine, capture = false) {
     try {
         return await runner(command, args, {
-            capture: false,
+            capture,
             env: prependCommandPath(command, env),
         });
     }
@@ -58,6 +59,31 @@ async function runHook(profile, operation, detected, runner, existsSync, env, wr
         executable = siblingExecutable(detected.executable, 'mearl-mcp-configure', existsSync);
         args = ['--skip-mcp', '--global-install'];
     }
+    else if (profile === 'cloud') {
+        executable = siblingExecutable(detected.executable, 'mearl-cloud-server', existsSync);
+        if (!executable) {
+            writeLine(`Hook: ${profile} ${operation} command was not found.`);
+            return false;
+        }
+        if (operation === 'uninstall') {
+            args = ['stop'];
+        }
+        else {
+            const status = await runLifecycleCommand(runner, executable, ['status'], env, 'Hook: cloud status', writeLine, true);
+            if (!status)
+                return false;
+            if (status.code !== 0) {
+                writeLine(`Hook: cloud status failed (exit ${status.code}).`);
+                return false;
+            }
+            const running = /\[CloudServer\]\s+Status:\s+running\b/.test(status.stdout);
+            if (operation === 'update' && !running) {
+                writeLine('Hook: cloud update skipped because cloud-server is not running.');
+                return true;
+            }
+            args = [running ? 'restart' : 'start'];
+        }
+    }
     else {
         return true;
     }
@@ -85,6 +111,9 @@ function operationVerb(operation) {
     return operation === 'uninstall' ? 'uninstall' : operation === 'update' ? 'update' : 'install';
 }
 export async function runMearlLifecycle(options, dependencies = {}) {
+    if (options.targetLine && !isMearlReleaseLine(options.targetLine)) {
+        throw new Error('targetLine must be a valid Mearl release line such as 2.3.x');
+    }
     const env = options.env ?? process.env;
     const writeLine = dependencies.writeLine ?? (line => console.error(line));
     const existsSync = dependencies.existsSync ?? fs.existsSync;
@@ -158,7 +187,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             continue;
         }
         const packageOperation = options.operation === 'uninstall' ? 'uninstall' : options.operation;
-        const command = buildGlobalPackageCommand(installation, packageOperation, config.packages);
+        const command = buildGlobalPackageCommand(installation, packageOperation, config.packages, options.targetLine);
         writeLine(`Packages (${profile}): ${command.manager}`);
         const result = await runLifecycleCommand(runner, command.command, command.args, env, `Packages (${profile})`, writeLine);
         if (!result) {
@@ -170,7 +199,8 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             packagesOk = false;
             continue;
         }
-        if (options.operation !== 'uninstall' && (profile === 'local' || profile === 'mcp')) {
+        if (options.operation !== 'uninstall' &&
+            (profile === 'local' || profile === 'cloud' || profile === 'mcp')) {
             const refreshed = detectPackage(config.anchorPackage, config.anchorBins, {
                 env: prependCommandPath(command.command, env),
             }) ?? current;
@@ -182,7 +212,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
     }
     let skillOk = true;
     const selectedUsesSkill = selected.some(profile => MEARL_PROFILES[profile].usesSkill);
-    if (packagesOk && selectedUsesSkill) {
+    if (packagesOk && selectedUsesSkill && options.skipSkill !== true) {
         try {
             if (options.operation === 'uninstall') {
                 const remainingSkillProfiles = ['local', 'cloud'].filter(profile => detected.has(profile) && !selected.includes(profile));

package/dist/packageManager.d.ts

@@ -3,8 +3,12 @@ export type PackageOperation = 'install' | 'update' | 'uninstall';
 export interface PackageManagerInstallation {
     manager: GlobalPackageManager;
     command: string;
+    /** Directory containing globally installed package executables. */
+    binDirectory?: string;
 }
-export interface GlobalPackageCommand extends PackageManagerInstallation {
+export interface GlobalPackageCommand {
+    manager: GlobalPackageManager;
+    command: string;
     args: string[];
 }
 export interface DetectedGlobalPackage extends PackageManagerInstallation {
@@ -21,7 +25,7 @@ export interface PackageDetectionOptions {
     realpathSync?: (filePath: string) => string;
 }
 export declare function resolvePackageManagerInstallation(packageRoot: string, packageName: string, options?: PackageDetectionOptions): PackageManagerInstallation | null;
-export declare function buildGlobalPackageCommand(installation: PackageManagerInstallation, operation: PackageOperation, packages: string[]): GlobalPackageCommand;
+export declare function buildGlobalPackageCommand(installation: PackageManagerInstallation, operation: PackageOperation, packages: string[], targetSelector?: string): GlobalPackageCommand;
 export declare function resolveInvokingPackageManager(options?: {
     env?: NodeJS.ProcessEnv;
     existsSync?: (filePath: string) => boolean;

package/dist/packageManager.js

@@ -29,26 +29,48 @@ export function resolvePackageManagerInstallation(packageRoot, packageName, opti
             ...executableNames('pnpm', platform).map(name => path.join(pnpmHome, name)),
             ...executableNames('pnpm', platform).map(name => path.join(path.dirname(processExecPath), name)),
         ], existsSync) ?? fallbackCommand('pnpm', platform);
-        return { manager: 'pnpm', command };
+        return { manager: 'pnpm', command, binDirectory: pnpmHome };
     }
     const bunMarker = `/.bun/install/global/node_modules/${lowerPackageName}`;
     if (lowerRoot.endsWith(bunMarker)) {
         const bunHome = normalizedRoot.slice(0, lowerRoot.indexOf('/.bun/'));
         const command = firstExisting(executableNames('bun', platform).map(name => path.join(bunHome, '.bun', 'bin', name)), existsSync) ?? fallbackCommand('bun', platform);
-        return { manager: 'bun', command };
+        return {
+            manager: 'bun',
+            command,
+            binDirectory: path.join(bunHome, '.bun', 'bin'),
+        };
     }
     if ((lowerRoot.includes('/.config/yarn/global/node_modules/') ||
         lowerRoot.includes('/.yarn/global/node_modules/') ||
         lowerRoot.includes('/yarn/global/node_modules/') ||
         lowerRoot.includes('/yarn/data/global/node_modules/')) &&
         lowerRoot.endsWith(`/node_modules/${lowerPackageName}`)) {
-        return { manager: 'yarn', command: fallbackCommand('yarn', platform) };
+        const layout = [
+            { marker: '/.config/yarn/global/', binSegments: ['.yarn', 'bin'] },
+            { marker: '/.yarn/global/', binSegments: ['.yarn', 'bin'] },
+            { marker: '/yarn/data/global/', binSegments: ['yarn', 'bin'] },
+            { marker: '/yarn/global/', binSegments: ['yarn', 'bin'] },
+        ].find(candidate => lowerRoot.includes(candidate.marker));
+        const prefix = normalizedRoot.slice(0, lowerRoot.indexOf(layout.marker));
+        const binDirectory = path.join(prefix, ...layout.binSegments);
+        const command = firstExisting([
+            ...executableNames('yarn', platform).map(name => path.join(binDirectory, name)),
+            ...executableNames('yarn', platform).map(name => path.join(path.dirname(processExecPath), name)),
+        ], existsSync) ??
+            findExecutable('yarn', { env, existsSync, platform }) ??
+            fallbackCommand('yarn', platform);
+        return { manager: 'yarn', command, binDirectory };
     }
     if (lowerRoot.includes('/.volta/tools/image/packages/') &&
         lowerRoot.endsWith(`/lib/node_modules/${lowerPackageName}`)) {
         const voltaHome = normalizedRoot.slice(0, lowerRoot.indexOf('/.volta/'));
         const command = firstExisting(executableNames('volta', platform).map(name => path.join(voltaHome, '.volta', 'bin', name)), existsSync) ?? fallbackCommand('volta', platform);
-        return { manager: 'volta', command };
+        return {
+            manager: 'volta',
+            command,
+            binDirectory: path.join(voltaHome, '.volta', 'bin'),
+        };
     }
     const npmMarker = `/lib/node_modules/${lowerPackageName}`;
     if (lowerRoot.endsWith(npmMarker)) {
@@ -57,18 +79,25 @@ export function resolvePackageManagerInstallation(packageRoot, packageName, opti
             ...executableNames('npm', platform).map(name => path.join(prefix, 'bin', name)),
             ...executableNames('npm', platform).map(name => path.join(path.dirname(processExecPath), name)),
         ], existsSync) ?? fallbackCommand('npm', platform);
-        return { manager: 'npm', command };
+        return { manager: 'npm', command, binDirectory: path.join(prefix, 'bin') };
     }
     if (platform === 'win32' && env.APPDATA) {
         const npmRoot = normalizePath(path.join(env.APPDATA, 'npm', 'node_modules', packageName));
         if (lowerRoot === npmRoot.toLowerCase()) {
-            return { manager: 'npm', command: fallbackCommand('npm', platform) };
+            const binDirectory = path.join(env.APPDATA, 'npm');
+            const command = firstExisting([
+                ...executableNames('npm', platform).map(name => path.join(binDirectory, name)),
+                ...executableNames('npm', platform).map(name => path.join(path.dirname(processExecPath), name)),
+            ], existsSync) ?? fallbackCommand('npm', platform);
+            return { manager: 'npm', command, binDirectory };
         }
     }
     return null;
 }
-export function buildGlobalPackageCommand(installation, operation, packages) {
-    const targets = operation === 'uninstall' ? packages : packages.map(packageName => `${packageName}@latest`);
+export function buildGlobalPackageCommand(installation, operation, packages, targetSelector = 'latest') {
+    const targets = operation === 'uninstall'
+        ? packages
+        : packages.map(packageName => `${packageName}@${targetSelector}`);
     let args;
     switch (installation.manager) {
         case 'npm':
@@ -91,7 +120,7 @@ export function buildGlobalPackageCommand(installation, operation, packages) {
             args = operation === 'uninstall' ? ['uninstall', ...targets] : ['install', ...targets];
             break;
     }
-    return { ...installation, args };
+    return { manager: installation.manager, command: installation.command, args };
 }
 export function resolveInvokingPackageManager(options = {}) {
     const env = options.env ?? process.env;
@@ -194,7 +223,13 @@ export function detectGlobalPackage(packageName, binNames, options = {}) {
         });
         if (!installation)
             continue;
-        return { packageName, packageRoot, executable, ...installation };
+        return {
+            packageName,
+            packageRoot,
+            executable,
+            ...installation,
+            binDirectory: path.dirname(executable),
+        };
     }
     return null;
 }

package/dist/process.d.ts

@@ -26,6 +26,7 @@ export declare function versionManagerExecutableCandidates(home: string, names:
 export declare function resolveSpawnCommand(executable: string, args: string[], platform?: NodeJS.Platform, commandInterpreter?: string | undefined): SpawnCommand;
 export declare function prependCommandPath(command: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function prependNodePath(env?: NodeJS.ProcessEnv, nodeExecutable?: string): NodeJS.ProcessEnv;
+export declare function prependPathDirectory(directory: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function findExecutable(name: string, options?: {
     env?: NodeJS.ProcessEnv;
     existsSync?: (filePath: string) => boolean;

package/dist/process.js

@@ -57,12 +57,12 @@ export function resolveSpawnCommand(executable, args, platform = process.platfor
 export function prependCommandPath(command, env = process.env) {
     if (!path.isAbsolute(command))
         return env;
-    return prependPath(path.dirname(command), env);
+    return prependPathDirectory(path.dirname(command), env);
 }
 export function prependNodePath(env = process.env, nodeExecutable = process.execPath) {
-    return prependPath(path.dirname(nodeExecutable), env);
+    return prependPathDirectory(path.dirname(nodeExecutable), env);
 }
-function prependPath(directory, env) {
+export function prependPathDirectory(directory, env = process.env) {
     const pathKey = Object.keys(env).find(key => key.toLowerCase() === 'path') || 'PATH';
     const inherited = env[pathKey] || '';
     const entries = inherited.split(path.delimiter).filter(Boolean);

package/dist/profiles.js

@@ -13,7 +13,7 @@ export const MEARL_PROFILES = {
         label: 'cloud agent',
         anchorPackage: '@mearl/cloud-client',
         anchorBins: ['mearl-cloud'],
-        packages: ['@mearl/cloud-client'],
+        packages: ['@mearl/cloud-server', '@mearl/cloud-client'],
         usesSkill: true,
     },
     mcp: {

package/dist/version.d.ts

@@ -0,0 +1,21 @@
+export declare const MEARL_RELEASE_VERSION_MAX_LENGTH = 64;
+export interface MearlReleaseVersion {
+    raw: string;
+    major: number;
+    minor: number;
+    patch: number;
+    channel: 'stable' | 'beta';
+    beta?: number;
+}
+export interface MearlReleaseLine {
+    raw: string;
+    major: number;
+    minor: number;
+}
+export declare function parseMearlReleaseVersion(value: unknown): MearlReleaseVersion | null;
+export declare function isMearlReleaseVersion(value: unknown): value is string;
+export declare function parseMearlReleaseLine(value: unknown): MearlReleaseLine | null;
+export declare function isMearlReleaseLine(value: unknown): value is string;
+export declare function mearlReleaseLineForVersion(version: string): string;
+export declare function isMearlReleaseVersionInLine(version: string, releaseLine: string): boolean;
+export declare function compareMearlReleaseLines(leftVersion: string, rightVersion: string): -1 | 0 | 1;

package/dist/version.js

@@ -0,0 +1,77 @@
+export const MEARL_RELEASE_VERSION_MAX_LENGTH = 64;
+const RELEASE_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-beta\.(0|[1-9]\d*))?$/;
+const RELEASE_LINE_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.x$/;
+const RELEASE_COMPONENT_MAXIMUM = 65_535;
+function parseComponent(value) {
+    const component = Number(value);
+    return Number.isSafeInteger(component) && component <= RELEASE_COMPONENT_MAXIMUM
+        ? component
+        : null;
+}
+export function parseMearlReleaseVersion(value) {
+    if (typeof value !== 'string' || value.length > MEARL_RELEASE_VERSION_MAX_LENGTH)
+        return null;
+    const match = RELEASE_VERSION_PATTERN.exec(value);
+    if (!match)
+        return null;
+    const major = parseComponent(match[1]);
+    const minor = parseComponent(match[2]);
+    const patch = parseComponent(match[3]);
+    const beta = match[4] === undefined ? undefined : parseComponent(match[4]);
+    if (major === null || minor === null || patch === null || beta === null)
+        return null;
+    return {
+        raw: value,
+        major,
+        minor,
+        patch,
+        channel: beta === undefined ? 'stable' : 'beta',
+        ...(beta === undefined ? {} : { beta }),
+    };
+}
+export function isMearlReleaseVersion(value) {
+    return parseMearlReleaseVersion(value) !== null;
+}
+export function parseMearlReleaseLine(value) {
+    if (typeof value !== 'string' || value.length > MEARL_RELEASE_VERSION_MAX_LENGTH)
+        return null;
+    const match = RELEASE_LINE_PATTERN.exec(value);
+    if (!match)
+        return null;
+    const major = parseComponent(match[1]);
+    const minor = parseComponent(match[2]);
+    if (major === null || minor === null)
+        return null;
+    return { raw: value, major, minor };
+}
+export function isMearlReleaseLine(value) {
+    return parseMearlReleaseLine(value) !== null;
+}
+export function mearlReleaseLineForVersion(version) {
+    const parsed = parseMearlReleaseVersion(version);
+    if (!parsed)
+        throw new Error('A valid Mearl release version is required');
+    return `${parsed.major}.${parsed.minor}.x`;
+}
+export function isMearlReleaseVersionInLine(version, releaseLine) {
+    const parsedVersion = parseMearlReleaseVersion(version);
+    const parsedLine = parseMearlReleaseLine(releaseLine);
+    return (parsedVersion !== null &&
+        parsedLine !== null &&
+        parsedVersion.major === parsedLine.major &&
+        parsedVersion.minor === parsedLine.minor);
+}
+export function compareMearlReleaseLines(leftVersion, rightVersion) {
+    const left = parseMearlReleaseVersion(leftVersion);
+    const right = parseMearlReleaseVersion(rightVersion);
+    if (!left || !right) {
+        throw new Error('Mearl release-line comparison requires valid release versions');
+    }
+    for (const key of ['major', 'minor']) {
+        if (left[key] < right[key])
+            return -1;
+        if (left[key] > right[key])
+            return 1;
+    }
+    return 0;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mearl/setup",
-  "version": "2.3.0",
-  "description": "One-shot installer, updater, and uninstaller for Mearl environments",
+  "version": "2.5.0",
+  "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,9 +18,21 @@
       "types": "./dist/process.d.ts",
       "import": "./dist/process.js"
     },
+    "./package-manager": {
+      "types": "./dist/packageManager.d.ts",
+      "import": "./dist/packageManager.js"
+    },
     "./native-host": {
       "types": "./dist/nativeHost.d.ts",
       "import": "./dist/nativeHost.js"
+    },
+    "./agentbay": {
+      "types": "./dist/agentBay.d.ts",
+      "import": "./dist/agentBay.js"
+    },
+    "./version": {
+      "types": "./dist/version.d.ts",
+      "import": "./dist/version.js"
     }
   },
   "bin": {