@xfxstudio/claworld 0.2.16 → 0.2.18

package/src/openclaw/installer/core.js

@@ -1,2115 +0,0 @@
-import { accessSync, constants as FS_CONSTANTS } from 'fs';
-import fs from 'fs/promises';
-import os from 'os';
-import path from 'path';
-import { spawnSync } from 'child_process';
-import vm from 'vm';
-import {
-  applyClaworldBootstrapConfig,
-  DEFAULT_CLAWORLD_ACCOUNT_ID,
-  DEFAULT_CLAWORLD_AGENT_ID,
-  DEFAULT_CLAWORLD_SERVER_URL,
-  ensureObject,
-  expandUserPath,
-  findClaworldManagedRuntimeBackup,
-  normalizeText,
-  resolveClaworldManagedRuntimeOptions,
-  setClaworldManagedRuntimeBackupState,
-  stripClaworldManagedRuntimeConfig,
-} from '../plugin/managed-config.js';
-import {
-  defaultClaworldAccountId,
-  inspectClaworldChannelAccount,
-  listClaworldAccountIds,
-} from '../plugin/config-schema.js';
-import {
-  CLAWORLD_INSTALLER_COMMAND,
-  CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
-  CLAWORLD_INSTALLER_PACKAGE_NAME,
-  CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
-  CLAWORLD_UNINSTALL_COMMAND,
-  CLAWORLD_UPDATE_COMMAND,
-} from './constants.js';
-import { seedManagedWorkspaceContract } from './workspace-contract.js';
-
-export const DEFAULT_OPENCLAW_BIN = 'openclaw';
-const DEFAULT_NPM_BIN = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-export const DEFAULT_OPENCLAW_CONFIG_PATH = '~/.openclaw/openclaw.json';
-export const DEFAULT_OPENCLAW_STATE_DIR = null;
-export const DEFAULT_INSTALL_TIMEOUT_MS = 15_000;
-export const DEFAULT_VERIFICATION_ATTEMPTS = 6;
-export const DEFAULT_VERIFICATION_DELAY_MS = 1_000;
-export const seedManagedWorkspace = seedManagedWorkspaceContract;
-const TRACKED_PLUGIN_UPDATEABLE_SOURCES = new Set(['npm', 'marketplace']);
-
-function resolveRequireGatewayRunning(env = process.env) {
-  const normalized = normalizeText(env?.CLAWORLD_INSTALLER_REQUIRE_GATEWAY_RUNNING, null);
-  if (!normalized) return true;
-  const lowered = normalized.toLowerCase();
-  if (['0', 'false', 'no', 'off'].includes(lowered)) return false;
-  if (['1', 'true', 'yes', 'on'].includes(lowered)) return true;
-  return true;
-}
-
-function normalizeComparablePath(value) {
-  if (!value) return null;
-  return path.resolve(String(value));
-}
-
-function splitPackageNameSegments(packageName = CLAWORLD_INSTALLER_PACKAGE_NAME) {
-  const normalized = String(packageName || '').trim();
-  if (!normalized) return ['claworld'];
-  return normalized.split('/').filter(Boolean);
-}
-
-function resolveInstallerManagedPluginInstallRoot(configPath = DEFAULT_OPENCLAW_CONFIG_PATH) {
-  const resolvedConfigPath = path.resolve(expandUserPath(configPath, os.homedir()));
-  return path.join(path.dirname(resolvedConfigPath), 'extensions', 'claworld');
-}
-
-function resolveInstallerManagedPluginSourcePath(installRoot, packageName = CLAWORLD_INSTALLER_PACKAGE_NAME) {
-  return path.join(installRoot, 'node_modules', ...splitPackageNameSegments(packageName));
-}
-
-async function readJsonFile(filePath) {
-  return JSON.parse(await fs.readFile(filePath, 'utf8'));
-}
-
-async function resolveLocalPluginInstallTarget({
-  installMode = 'npm',
-  installSource = CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
-  repoRoot = null,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  if (installMode === 'npm') {
-    return {
-      installSource,
-      managedRepoRoot: repoRoot,
-      stagedPackageRoot: null,
-    };
-  }
-
-  const resolvedRepoRoot = normalizeComparablePath(repoRoot);
-  const resolvedInstallSource = normalizeComparablePath(installSource);
-  const derivedRepoRoot = resolvedRepoRoot
-    || (
-      resolvedInstallSource?.endsWith(`${path.sep}packages${path.sep}openclaw-plugin`)
-        ? path.resolve(resolvedInstallSource, '..', '..')
-        : null
-    );
-  const shouldStageRepo = Boolean(
-    derivedRepoRoot
-    && (
-      resolvedInstallSource === derivedRepoRoot
-      || resolvedInstallSource === path.join(derivedRepoRoot, 'packages', 'openclaw-plugin')
-      || resolvedInstallSource === CLAWORLD_INSTALLER_PACKAGE_NAME
-      || resolvedInstallSource === CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE
-    ),
-  );
-
-  if (!shouldStageRepo) {
-    return {
-      installSource,
-      managedRepoRoot: installMode === 'link' ? installSource : repoRoot,
-      stagedPackageRoot: null,
-    };
-  }
-
-  const stagedPackageRoot = path.join(derivedRepoRoot, '.tmp', 'openclaw-plugin-package');
-  const buildScriptPath = path.join(derivedRepoRoot, 'scripts', 'build-openclaw-plugin-package.mjs');
-  if (!dryRun) {
-    await executeCommand({
-      commandRunner,
-      bin: process.execPath,
-      args: [buildScriptPath, '--output-dir', stagedPackageRoot],
-      cwd,
-      env,
-      dryRun,
-    });
-  }
-  return {
-    installSource: stagedPackageRoot,
-    managedRepoRoot: stagedPackageRoot,
-    stagedPackageRoot,
-  };
-}
-
-function listBindings(config = {}) {
-  return Array.isArray(config.bindings) ? config.bindings : [];
-}
-
-function findAgentEntry(config = {}, agentId) {
-  const list = Array.isArray(config?.agents?.list) ? config.agents.list : [];
-  return list
-    .map((item) => ensureObject(item))
-    .find((item) => item.id === agentId) || null;
-}
-
-export function hasManagedBinding(config = {}, { agentId, accountId } = {}) {
-  return listBindings(config).some((binding) => {
-    const candidate = ensureObject(binding);
-    const match = ensureObject(candidate.match);
-    return candidate.agentId === agentId
-      && match.channel === 'claworld'
-      && match.accountId === accountId;
-  });
-}
-
-export function isManagedToolAllowlistReady(config = {}, options = {}) {
-  return true;
-}
-
-export function isRelayBootstrapReady(account = {}) {
-  return Boolean(
-    account?.configured
-    && normalizeText(account?.appToken, null),
-  );
-}
-
-function parseCommandVersion(text) {
-  const match = String(text || '').match(/OpenClaw\s+([0-9]+(?:\.[0-9]+)+(?:-[0-9A-Za-z.-]+)?)/i)
-    || String(text || '').match(/([0-9]+(?:\.[0-9]+)+(?:-[0-9A-Za-z.-]+)?)/);
-  return match ? match[1] : null;
-}
-
-function parseVersionParts(version) {
-  const normalized = String(version || '')
-    .trim()
-    .replace(/^[^\d]+/, '');
-  return normalized
-    .split('.')
-    .map((value) => Number.parseInt(value, 10))
-    .filter((value) => Number.isFinite(value));
-}
-
-function compareVersionParts(leftVersion, rightVersion) {
-  const leftParts = parseVersionParts(leftVersion);
-  const rightParts = parseVersionParts(rightVersion);
-  const length = Math.max(leftParts.length, rightParts.length);
-  for (let index = 0; index < length; index += 1) {
-    const left = leftParts[index] ?? 0;
-    const right = rightParts[index] ?? 0;
-    if (left > right) return 1;
-    if (left < right) return -1;
-  }
-  return 0;
-}
-
-function normalizeRelayHttpBaseUrl(serverUrl) {
-  const parsed = new URL(serverUrl);
-  if (parsed.protocol === 'ws:') parsed.protocol = 'http:';
-  if (parsed.protocol === 'wss:') parsed.protocol = 'https:';
-  parsed.pathname = '';
-  parsed.search = '';
-  parsed.hash = '';
-  return parsed.toString().replace(/\/$/, '');
-}
-
-function buildFetchHeaders({ apiKey = null, appToken = null, body = false } = {}) {
-  return {
-    accept: 'application/json',
-    ...(body ? { 'content-type': 'application/json' } : {}),
-    ...(apiKey ? { 'x-api-key': apiKey } : {}),
-    ...(appToken ? { authorization: `Bearer ${appToken}` } : {}),
-  };
-}
-
-function createInstallerError(code, message, context = {}) {
-  const error = new Error(message);
-  error.code = code;
-  error.context = context;
-  return error;
-}
-
-function cloneObject(value = {}) {
-  return JSON.parse(JSON.stringify(ensureObject(value)));
-}
-
-function isExplicitCommandPath(command = '') {
-  const normalized = String(command || '').trim();
-  if (!normalized) return false;
-  return normalized.includes('/') || normalized.includes('\\') || path.isAbsolute(normalized);
-}
-
-function splitPathEnvEntries(pathValue = '') {
-  return String(pathValue || '')
-    .split(path.delimiter)
-    .map((entry) => entry.trim())
-    .filter(Boolean);
-}
-
-function isNodeModulesBinEntry(entry = '') {
-  const normalized = path.resolve(String(entry || ''));
-  return path.basename(normalized) === '.bin'
-    && path.basename(path.dirname(normalized)) === 'node_modules';
-}
-
-function resolveCommandNameCandidates(command = '', env = process.env) {
-  const normalized = String(command || '').trim();
-  if (!normalized) return [];
-  if (process.platform !== 'win32' || path.extname(normalized)) {
-    return [normalized];
-  }
-
-  const pathExt = splitPathEnvEntries(env?.PATHEXT || process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
-    .map((ext) => ext.toLowerCase());
-  return [...new Set([normalized, ...pathExt.map((ext) => `${normalized}${ext}`)])];
-}
-
-function hasExecutableAccess(filePath = '') {
-  try {
-    accessSync(filePath, FS_CONSTANTS.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function resolveOpenclawCliBinary({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  env = process.env,
-} = {}) {
-  const requestedBin = normalizeText(openclawBin, DEFAULT_OPENCLAW_BIN);
-  if (
-    requestedBin !== DEFAULT_OPENCLAW_BIN
-    || isExplicitCommandPath(requestedBin)
-  ) {
-    return {
-      requestedBin,
-      binaryPath: requestedBin,
-      binarySource: isExplicitCommandPath(requestedBin) ? 'explicit_path' : 'explicit_command',
-      skippedLocalBinaryPaths: [],
-    };
-  }
-
-  const candidates = [];
-  for (const entry of splitPathEnvEntries(env?.PATH || process.env.PATH || '')) {
-    for (const name of resolveCommandNameCandidates(requestedBin, env)) {
-      const candidatePath = path.join(entry, name);
-      if (hasExecutableAccess(candidatePath)) {
-        candidates.push(candidatePath);
-      }
-    }
-  }
-
-  const uniqueCandidates = [...new Set(candidates)];
-  const hostCandidates = uniqueCandidates.filter((candidate) => !isNodeModulesBinEntry(path.dirname(candidate)));
-  const localCandidates = uniqueCandidates.filter((candidate) => isNodeModulesBinEntry(path.dirname(candidate)));
-  const binaryPath = hostCandidates[0] || uniqueCandidates[0] || requestedBin;
-
-  return {
-    requestedBin,
-    binaryPath,
-    binarySource: hostCandidates[0]
-      ? 'host_path'
-      : uniqueCandidates[0]
-        ? 'package_local_path'
-        : 'default_command',
-    skippedLocalBinaryPaths: localCandidates.filter((candidate) => candidate !== binaryPath),
-  };
-}
-
-function parseJson(text, fallback = null) {
-  try {
-    return JSON.parse(String(text || '').trim());
-  } catch {
-    return fallback;
-  }
-}
-
-export function parseJsonDocument(text, fallback = null) {
-  const source = String(text || '').trim();
-  const direct = parseJson(source, null);
-  if (direct) return direct;
-
-  const lines = source.split('\n');
-  for (let index = 0; index < lines.length; index += 1) {
-    const candidate = lines.slice(index).join('\n').trim();
-    if (!candidate.startsWith('{') && !candidate.startsWith('[')) continue;
-    const parsed = parseJson(candidate, null);
-    if (parsed) return parsed;
-  }
-
-  return fallback;
-}
-
-function parseCommandJsonOutput(result = {}, fallback = null) {
-  const stdout = String(result?.stdout || '').trim();
-  const stderr = String(result?.stderr || '').trim();
-  const combined = [stdout, stderr].filter(Boolean).join('\n');
-  const reversed = [stderr, stdout].filter(Boolean).join('\n');
-  return (
-    parseJsonDocument(stdout, null)
-    || parseJsonDocument(stderr, null)
-    || parseJsonDocument(combined, null)
-    || parseJsonDocument(reversed, null)
-    || fallback
-  );
-}
-
-function readClaworldAccountStatus(channelsStatus, accountId) {
-  const items = Array.isArray(channelsStatus?.channelAccounts?.claworld)
-    ? channelsStatus.channelAccounts.claworld
-    : [];
-  return items.find((item) => item?.accountId === accountId) || null;
-}
-
-function synthesizeChannelStatusFromConfig(config = {}) {
-  const claworldChannel = config?.channels?.claworld;
-  const configuredAccounts = claworldChannel?.accounts && typeof claworldChannel.accounts === 'object'
-    ? Object.entries(claworldChannel.accounts)
-    : [];
-  if (configuredAccounts.length === 0) {
-    return null;
-  }
-
-  const accounts = configuredAccounts.map(([entryKey, entryValue]) => {
-    const entry = entryValue && typeof entryValue === 'object' ? entryValue : {};
-    const accountId = String(entry.accountId || entryKey || '').trim();
-    const hasToken = Boolean(
-      entry.appToken
-      || entry.apiKey
-      || entry?.relay?.appToken
-      || entry?.relay?.credentialToken,
-    );
-    return {
-      accountId,
-      enabled: entry.enabled !== false,
-      configured: true,
-      tokenSource: hasToken ? 'config' : 'missing',
-      tokenStatus: hasToken ? 'available' : 'missing',
-      lastInboundAt: null,
-      lastOutboundAt: null,
-    };
-  }).filter((entry) => entry.accountId);
-
-  if (accounts.length === 0) {
-    return null;
-  }
-
-  const defaultAccountId = String(claworldChannel?.defaultAccount || accounts[0]?.accountId || '').trim() || null;
-
-  return {
-    ts: Date.now(),
-    channelOrder: ['claworld'],
-    channelLabels: {
-      claworld: 'Claworld',
-    },
-    channelDetailLabels: {
-      claworld: 'Claworld A2A Relay Channel',
-    },
-    channelSystemImages: {},
-    channelMeta: [
-      {
-        id: 'claworld',
-        label: 'Claworld',
-        detailLabel: 'Claworld A2A Relay Channel',
-      },
-    ],
-    channels: {
-      claworld: {
-        configured: true,
-      },
-    },
-    channelAccounts: {
-      claworld: accounts,
-    },
-    channelDefaultAccountId: defaultAccountId
-      ? { claworld: defaultAccountId }
-      : {},
-  };
-}
-
-function parsePluginInfo(text = '') {
-  const source = String(text || '');
-  const status = source.match(/^\s*Status:\s+(.+)$/m)?.[1]?.trim() || null;
-  const install = source.match(/^\s*Install:\s+(.+)$/m)?.[1]?.trim() || null;
-  const sourcePath = source.match(/^\s*Source path:\s+(.+)$/m)?.[1]?.trim() || null;
-  const version = source.match(/^\s*Version:\s+(.+)$/m)?.[1]?.trim()
-    || source.match(/^\s*Recorded version:\s+(.+)$/m)?.[1]?.trim()
-    || null;
-  return {
-    installed: Boolean(source.trim()),
-    loaded: status === 'loaded',
-    status,
-    install,
-    sourcePath,
-    version,
-    raw: source,
-  };
-}
-
-function parseBindingLine(text = '', { agentId, accountId } = {}) {
-  return String(text || '')
-    .split('\n')
-    .map((line) => line.trim())
-    .find((line) => line === `- ${agentId} <- claworld accountId=${accountId}`) || null;
-}
-
-function normalizePathSuffix(value = '') {
-  return String(value || '').replace(/\\/g, '/').replace(/\/+$/, '');
-}
-
-function isInstallerManagedLocalSourceRecord(installRecord = {}) {
-  const source = normalizeText(installRecord.source, null);
-  if (source !== 'path') {
-    return false;
-  }
-  const spec = normalizeText(installRecord.spec, null) || normalizeText(installRecord.resolvedSpec, null);
-  if (!spec || !spec.startsWith('@xfxstudio/claworld@')) {
-    return false;
-  }
-  const installPath = normalizePathSuffix(installRecord.installPath);
-  const sourcePath = normalizePathSuffix(installRecord.sourcePath);
-  return (
-    installPath.endsWith('/extensions/claworld')
-    && sourcePath.endsWith('/extensions/claworld/node_modules/@xfxstudio/claworld')
-  );
-}
-
-function inspectTrackedClaworldPluginInstall(config = {}) {
-  const installRecord = ensureObject(config?.plugins?.installs?.claworld);
-  const tracked = Object.keys(installRecord).length > 0;
-  const recordedSource = normalizeText(installRecord.source, null);
-  const source = isInstallerManagedLocalSourceRecord(installRecord)
-    ? 'installer_npm'
-    : recordedSource;
-  return {
-    tracked,
-    updateable: tracked && TRACKED_PLUGIN_UPDATEABLE_SOURCES.has(source),
-    source,
-    recordedSource,
-    spec: normalizeText(installRecord.spec, null),
-    resolvedSpec: normalizeText(installRecord.resolvedSpec, null),
-    resolvedVersion: normalizeText(installRecord.resolvedVersion, null),
-    installPath: normalizeText(installRecord.installPath, null),
-    sourcePath: normalizeText(installRecord.sourcePath, null),
-    record: tracked ? installRecord : null,
-  };
-}
-
-function needsPluginBootstrapConfig(config = {}) {
-  if (config?.channels?.claworld) {
-    return true;
-  }
-  return listBindings(config).some((binding) => ensureObject(binding).match?.channel === 'claworld');
-}
-
-function buildPluginBootstrapConfig(config = {}) {
-  const next = cloneObject(config);
-
-  const channels = ensureObject(next.channels);
-  if (Object.prototype.hasOwnProperty.call(channels, 'claworld')) {
-    delete channels.claworld;
-  }
-  if (Object.keys(channels).length > 0) {
-    next.channels = channels;
-  } else {
-    delete next.channels;
-  }
-
-  if (Array.isArray(next.bindings)) {
-    next.bindings = next.bindings.filter((binding) => ensureObject(binding).match?.channel !== 'claworld');
-  }
-
-  return next;
-}
-
-async function preparePluginBootstrapConfig({
-  configPath = null,
-  config = {},
-  dryRun = false,
-} = {}) {
-  if (!configPath || !needsPluginBootstrapConfig(config)) {
-    return null;
-  }
-
-  if (dryRun) {
-    return {
-      configPath,
-      pluginConfig: ensureObject(config.plugins),
-      cleanup: async () => {},
-    };
-  }
-
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'claworld-plugin-bootstrap-'));
-  const tempConfigPath = path.join(tempRoot, path.basename(configPath || 'openclaw.json'));
-  await writeConfig(tempConfigPath, buildPluginBootstrapConfig(config));
-  return {
-    configPath: tempConfigPath,
-    pluginConfig: null,
-    cleanup: async () => {
-      await fs.rm(tempRoot, { recursive: true, force: true });
-    },
-  };
-}
-
-function mergePluginMetadata(config = {}, pluginConfig = {}) {
-  const extraPlugins = ensureObject(pluginConfig);
-  if (Object.keys(extraPlugins).length === 0) {
-    return cloneObject(config);
-  }
-
-  const next = cloneObject(config);
-  const existingPlugins = ensureObject(next.plugins);
-  next.plugins = {
-    ...existingPlugins,
-    ...extraPlugins,
-    entries: {
-      ...ensureObject(existingPlugins.entries),
-      ...ensureObject(extraPlugins.entries),
-    },
-    installs: {
-      ...ensureObject(existingPlugins.installs),
-      ...ensureObject(extraPlugins.installs),
-    },
-  };
-  return next;
-}
-
-async function installPublishedClaworldPackageToLocalSource({
-  installSource = CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
-  configPath = DEFAULT_OPENCLAW_CONFIG_PATH,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-  refresh = false,
-} = {}) {
-  const installRoot = resolveInstallerManagedPluginInstallRoot(configPath);
-  const sourcePath = resolveInstallerManagedPluginSourcePath(installRoot);
-  if (!dryRun && refresh) {
-    await fs.rm(installRoot, { recursive: true, force: true });
-  }
-  if (!dryRun) {
-    await fs.mkdir(installRoot, { recursive: true });
-  }
-
-  await executeCommand({
-    commandRunner,
-    bin: DEFAULT_NPM_BIN,
-    args: [
-      'install',
-      '--ignore-scripts',
-      '--no-package-lock',
-      '--omit=dev',
-      '--prefix',
-      installRoot,
-      installSource,
-    ],
-    cwd,
-    env,
-    dryRun,
-    capture: false,
-  });
-
-  let resolvedVersion = null;
-  if (!dryRun) {
-    const sourcePackageJson = await readJsonFile(path.join(sourcePath, 'package.json'));
-    resolvedVersion = normalizeText(sourcePackageJson?.version, null);
-  }
-
-  return {
-    installRoot,
-    sourcePath,
-    resolvedVersion,
-    pluginConfig: {
-        installs: {
-          claworld: {
-          source: 'path',
-          spec: installSource,
-          resolvedSpec: installSource,
-          ...(resolvedVersion ? { resolvedVersion } : {}),
-          installPath: installRoot,
-          sourcePath,
-        },
-      },
-    },
-  };
-}
-
-function defaultCommandRunner({
-  bin,
-  args,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-  capture = true,
-} = {}) {
-  const resolvedBin = resolveOpenclawCliBinary({
-    openclawBin: bin,
-    env,
-  });
-  const effectiveBin = resolvedBin.binaryPath;
-  const rendered = [effectiveBin, ...args].join(' ');
-  if (dryRun) {
-    return {
-      status: 0,
-      stdout: '',
-      stderr: '',
-      rendered,
-      dryRun: true,
-      requestedBin: bin,
-      resolvedBin: effectiveBin,
-      binSource: resolvedBin.binarySource,
-      skippedBinCandidates: resolvedBin.skippedLocalBinaryPaths,
-    };
-  }
-
-  const useShell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(effectiveBin);
-  const result = spawnSync(effectiveBin, args, {
-    cwd,
-    env,
-    shell: useShell,
-    windowsHide: true,
-    stdio: capture ? 'pipe' : 'inherit',
-    encoding: 'utf8',
-  });
-
-  if (result.error) {
-    const error = createInstallerError(
-      'openclaw_command_failed',
-      `Failed to run "${rendered}": ${result.error.message}`,
-      { rendered },
-    );
-    error.cause = result.error;
-    throw error;
-  }
-
-    return {
-      status: result.status ?? 0,
-      stdout: result.stdout || '',
-      stderr: result.stderr || '',
-      rendered,
-      requestedBin: bin,
-      resolvedBin: effectiveBin,
-      binSource: resolvedBin.binarySource,
-      skippedBinCandidates: resolvedBin.skippedLocalBinaryPaths,
-    };
-}
-
-async function executeCommand({
-  commandRunner = defaultCommandRunner,
-  bin,
-  args,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-  capture = true,
-  allowFailure = false,
-} = {}) {
-  const result = await Promise.resolve(commandRunner({
-    bin,
-    args,
-    cwd,
-    env,
-    dryRun,
-    capture,
-  }));
-  if (!allowFailure && result.status !== 0) {
-    throw createInstallerError(
-      'openclaw_command_failed',
-      `Command failed (${result.status}): ${result.rendered || [bin, ...args].join(' ')}`,
-      { result },
-    );
-  }
-  return result;
-}
-
-export function parseConfigObject(sourceText, sourceLabel = 'openclaw config') {
-  const text = String(sourceText || '').replace(/^\uFEFF/, '').trim();
-  if (!text) return {};
-
-  try {
-    const parsed = JSON.parse(text);
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      throw new Error('config root must be an object');
-    }
-    return parsed;
-  } catch {}
-
-  try {
-    const expression = text.replace(/;\s*$/, '');
-    const script = new vm.Script(`(${expression}\n)`, { filename: sourceLabel });
-    const result = script.runInNewContext(Object.create(null), { timeout: 1000 });
-    if (!result || typeof result !== 'object' || Array.isArray(result)) {
-      throw new Error('config root must evaluate to an object');
-    }
-    return JSON.parse(JSON.stringify(result));
-  } catch (error) {
-    throw createInstallerError(
-      'invalid_openclaw_config',
-      `Failed to parse ${sourceLabel}: ${error.message}`,
-      { sourceLabel },
-    );
-  }
-}
-
-export async function loadConfigFromDisk(configPath) {
-  try {
-    const raw = await fs.readFile(configPath, 'utf8');
-    return { existed: true, config: parseConfigObject(raw, configPath) };
-  } catch (error) {
-    if (error && error.code === 'ENOENT') {
-      return { existed: false, config: {} };
-    }
-    throw error;
-  }
-}
-
-export function resolveClaworldInstallerStatePath(configPath) {
-  const resolvedConfigPath = path.resolve(String(configPath || DEFAULT_OPENCLAW_CONFIG_PATH));
-  return path.join(path.dirname(resolvedConfigPath), '.claworld-installer-state.json');
-}
-
-export async function loadInstallerStateFromDisk(installerStatePath) {
-  try {
-    const raw = await fs.readFile(installerStatePath, 'utf8');
-    return { existed: true, state: parseConfigObject(raw, installerStatePath) };
-  } catch (error) {
-    if (error && error.code === 'ENOENT') {
-      return { existed: false, state: {} };
-    }
-    throw error;
-  }
-}
-
-export async function backupConfigIfPresent(configPath, existed, dryRun = false) {
-  if (!existed) return null;
-  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, '').replace('T', '-');
-  const backupPath = `${configPath}.bak.${stamp}`;
-  if (dryRun) return backupPath;
-  await fs.copyFile(configPath, backupPath);
-  return backupPath;
-}
-
-export async function writeConfig(configPath, config, dryRun = false) {
-  const rendered = `${JSON.stringify(config, null, 2)}\n`;
-  if (dryRun) return rendered;
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.writeFile(configPath, rendered, 'utf8');
-  return rendered;
-}
-
-export async function writeInstallerState(installerStatePath, installerState, dryRun = false) {
-  const renderedState = ensureObject(installerState);
-  if (Object.keys(renderedState).length === 0) {
-    if (dryRun) return '';
-    await fs.rm(installerStatePath, { force: true });
-    return '';
-  }
-  const rendered = `${JSON.stringify(renderedState, null, 2)}\n`;
-  if (dryRun) return rendered;
-  await fs.mkdir(path.dirname(installerStatePath), { recursive: true });
-  await fs.writeFile(installerStatePath, rendered, 'utf8');
-  return rendered;
-}
-
-export function buildOpenclawCommandEnv({ configPath, stateDir = null, env = process.env } = {}) {
-  return {
-    ...env,
-    ...(configPath ? { OPENCLAW_CONFIG_PATH: configPath } : {}),
-    ...(stateDir ? { OPENCLAW_STATE_DIR: stateDir } : {}),
-  };
-}
-
-export function inspectManagedClaworldInstall({
-  cfg = {},
-  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
-  input = {},
-  overrides = {},
-  installerState = {},
-} = {}) {
-  const configuredAccountIds = listClaworldAccountIds(cfg);
-  const hasAnyConfig = configuredAccountIds.length > 0 || cfg?.channels?.claworld != null;
-  const managedOptions = resolveClaworldManagedRuntimeOptions({
-    cfg,
-    accountId,
-    input,
-    overrides,
-    installerState,
-  });
-  const managedAgentPresent = Boolean(findAgentEntry(cfg, managedOptions.agentId));
-  const managedBindingPresent = hasManagedBinding(cfg, managedOptions);
-  const toolsReady = isManagedToolAllowlistReady(cfg, managedOptions);
-  const managedAccountPresent = configuredAccountIds.includes(managedOptions.accountId);
-  const accountStatus = managedAccountPresent
-    ? inspectClaworldChannelAccount(cfg, managedOptions.accountId)
-    : inspectClaworldChannelAccount({}, managedOptions.accountId);
-  const managedRuntimeReady = isRelayBootstrapReady(accountStatus);
-  const managedReady = Boolean(
-    managedAccountPresent
-    && managedRuntimeReady
-    && managedBindingPresent
-    && toolsReady
-    && (managedOptions.manageAgentEntry !== true || managedAgentPresent)
-  );
-
-  let statusLabel = 'needs setup';
-  let selectionHint = 'remote relay world channel';
-  if (managedRuntimeReady) {
-    statusLabel = managedReady ? 'configured' : 'configured (managed refresh recommended)';
-    selectionHint = managedReady ? 'configured · managed runtime' : 'configured · managed refresh';
-  } else if (hasAnyConfig) {
-    statusLabel = 'configured (activation pending)';
-    selectionHint = 'configured · activation pending';
-  }
-
-  return {
-    hasAnyConfig,
-    configuredAccountIds,
-    defaultAccountId: defaultClaworldAccountId(cfg) || null,
-    managedOptions,
-    managedAccountPresent,
-    managedAgentPresent,
-    managedBindingPresent,
-    toolsReady,
-    accountStatus,
-    managedRuntimeReady,
-    managedReady,
-    reusableAppToken: normalizeText(
-      managedOptions.appToken,
-      normalizeText(accountStatus?.appToken, null),
-    ),
-    statusLabel,
-    selectionHint,
-    quickstartScore: managedRuntimeReady ? 2 : 5,
-  };
-}
-
-export function buildManagedOnboardingStatus({ cfg = {}, accountId = DEFAULT_CLAWORLD_ACCOUNT_ID } = {}) {
-  const inspection = inspectManagedClaworldInstall({ cfg, accountId });
-  const configured = inspection.configuredAccountIds.some((configuredAccountId) =>
-    isRelayBootstrapReady(inspectClaworldChannelAccount(cfg, configuredAccountId)),
-  );
-  return {
-    configured,
-    statusLines: [`Claworld: ${inspection.statusLabel}`],
-    selectionHint: inspection.selectionHint,
-    quickstartScore: configured ? 2 : inspection.quickstartScore,
-  };
-}
-
-export async function detectOpenclawHost({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  const result = await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['--version'],
-    cwd,
-    env,
-    dryRun,
-  });
-  const version = parseCommandVersion(result.stdout || result.stderr);
-  if (!version) {
-    throw createInstallerError(
-      'openclaw_version_unreadable',
-      'Unable to determine the installed OpenClaw version.',
-      { result },
-    );
-  }
-  return {
-    version,
-    raw: (result.stdout || result.stderr || '').trim(),
-    requestedBin: result.requestedBin || openclawBin,
-    binaryPath: result.resolvedBin || openclawBin,
-    binarySource: result.binSource || 'default_command',
-    skippedLocalBinaryPaths: Array.isArray(result.skippedBinCandidates)
-      ? result.skippedBinCandidates
-      : [],
-  };
-}
-
-export async function inspectClaworldPluginInstall({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  const result = await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['plugins', 'info', 'claworld'],
-    cwd,
-    env: buildOpenclawCommandEnv({ configPath, stateDir, env }),
-    dryRun,
-    allowFailure: true,
-  });
-  if (result.status !== 0) {
-    return {
-      installed: false,
-      loaded: false,
-      status: null,
-      raw: `${result.stdout || ''}${result.stderr || ''}`.trim(),
-    };
-  }
-  return parsePluginInfo(`${result.stdout || ''}${result.stderr || ''}`);
-}
-
-export async function ensureClaworldPluginInstalled({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  config = {},
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-  installMode = 'npm',
-  installSource = CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
-  refresh = false,
-} = {}) {
-  const trackedInstall = inspectTrackedClaworldPluginInstall(config);
-  const bootstrap = await preparePluginBootstrapConfig({
-    configPath,
-    config,
-    dryRun,
-  });
-  const pluginConfigPath = bootstrap?.configPath || configPath;
-
-  try {
-    const before = await inspectClaworldPluginInstall({
-      openclawBin,
-      configPath: pluginConfigPath,
-      stateDir,
-      commandRunner,
-      cwd,
-      env,
-      dryRun,
-    });
-    const reusableInstallerManagedNpmInstall = (
-      installMode === 'npm'
-      && trackedInstall.tracked
-      && trackedInstall.source === 'installer_npm'
-      && trackedInstall.recordedSource === 'path'
-      && normalizeText(trackedInstall.sourcePath, null)
-    );
-    if (
-      before.installed
-      && !refresh
-      && (installMode !== 'npm' || reusableInstallerManagedNpmInstall)
-    ) {
-      return {
-        changed: false,
-        action: 'reused_existing_plugin_install',
-        plugin: before,
-        pluginConfig: bootstrap?.pluginConfig || null,
-      };
-    }
-
-    if (installMode === 'skip') {
-      return {
-        changed: false,
-        action: 'skipped_plugin_install',
-        plugin: before,
-        pluginConfig: bootstrap?.pluginConfig || null,
-      };
-    }
-
-    if (installMode === 'npm') {
-      const localInstall = await installPublishedClaworldPackageToLocalSource({
-        installSource,
-        configPath,
-        commandRunner,
-        cwd,
-        env,
-        dryRun,
-        refresh,
-      });
-      return {
-        changed: true,
-        action: reusableInstallerManagedNpmInstall ? 'refreshed_local_plugin_source' : 'staged_local_plugin_source',
-        plugin: before,
-        pluginConfig: {
-          ...ensureObject(bootstrap?.pluginConfig),
-          ...ensureObject(localInstall.pluginConfig),
-          entries: {
-            ...ensureObject(bootstrap?.pluginConfig?.entries),
-            ...ensureObject(localInstall.pluginConfig?.entries),
-          },
-          installs: {
-            ...ensureObject(bootstrap?.pluginConfig?.installs),
-            ...ensureObject(localInstall.pluginConfig?.installs),
-          },
-        },
-        installSource,
-        managedRepoRoot: localInstall.sourcePath,
-      };
-    }
-
-    if (before.installed && refresh && installMode === 'copy') {
-      await executeCommand({
-        commandRunner,
-        bin: openclawBin,
-        args: ['plugins', 'uninstall', 'claworld', '--force'],
-        cwd,
-        env: buildOpenclawCommandEnv({ configPath: pluginConfigPath, stateDir, env }),
-        dryRun,
-        capture: false,
-      });
-    }
-
-    const args = ['plugins', 'install', '--dangerously-force-unsafe-install'];
-    if (installMode === 'link') args.push('--link');
-    args.push(installSource);
-    await executeCommand({
-      commandRunner,
-      bin: openclawBin,
-      args,
-      cwd,
-      env: buildOpenclawCommandEnv({ configPath: pluginConfigPath, stateDir, env }),
-      dryRun,
-      capture: false,
-    });
-
-    const after = await inspectClaworldPluginInstall({
-      openclawBin,
-      configPath: pluginConfigPath,
-      stateDir,
-      commandRunner,
-      cwd,
-      env,
-      dryRun,
-    });
-    if (!after.installed) {
-      throw createInstallerError(
-        'claworld_plugin_install_failed',
-        'OpenClaw did not report the claworld plugin as installed after plugin install.',
-        { installMode, installSource, before, after },
-      );
-    }
-
-    const pluginConfig = pluginConfigPath
-      ? (await loadConfigFromDisk(pluginConfigPath)).config?.plugins || null
-      : null;
-
-    return {
-      changed: true,
-      action: before.installed ? 'refreshed_plugin_install' : 'installed_plugin',
-      plugin: after,
-      pluginConfig,
-      installSource,
-    };
-  } finally {
-    if (bootstrap) {
-      await bootstrap.cleanup();
-    }
-  }
-}
-
-export async function updateTrackedClaworldPluginInstall({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  config = {},
-  installSource = null,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  const trackedInstall = inspectTrackedClaworldPluginInstall(config);
-  const before = await inspectClaworldPluginInstall({
-    openclawBin,
-    configPath,
-    stateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-
-  if (!before.installed) {
-    throw createInstallerError(
-      'claworld_plugin_not_installed',
-      'The Claworld plugin is not installed or not discoverable. Run the install command before update.',
-      { plugin: before, trackedInstall },
-    );
-  }
-
-  if (trackedInstall.source === 'installer_npm') {
-    const localInstall = await installPublishedClaworldPackageToLocalSource({
-      installSource: normalizeText(
-        installSource,
-        trackedInstall.spec || CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
-      ),
-      configPath,
-      commandRunner,
-      cwd,
-      env,
-      dryRun,
-      refresh: true,
-    });
-    return {
-      changed: true,
-      action: dryRun ? 'dry_run_updated_local_plugin_source' : 'updated_local_plugin_source',
-      trackedInstall,
-      plugin: before,
-      pluginConfig: localInstall.pluginConfig,
-      managedRepoRoot: localInstall.sourcePath,
-    };
-  }
-
-  if (!trackedInstall.tracked) {
-    return {
-      changed: false,
-      action: 'skipped_untracked_plugin_update',
-      reason: 'plugins.installs.claworld_missing',
-      trackedInstall,
-      plugin: before,
-    };
-  }
-
-  if (!trackedInstall.updateable) {
-    return {
-      changed: false,
-      action: 'skipped_untracked_plugin_update',
-      reason: `plugins.installs.claworld_source_${trackedInstall.source || 'unknown'}_is_not_host_updateable`,
-      trackedInstall,
-      plugin: before,
-    };
-  }
-
-  await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['plugins', 'update', 'claworld'],
-    cwd,
-    env: buildOpenclawCommandEnv({ configPath, stateDir, env }),
-    dryRun,
-    capture: false,
-  });
-
-  const after = await inspectClaworldPluginInstall({
-    openclawBin,
-    configPath,
-    stateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-
-  if (!after.installed) {
-    throw createInstallerError(
-      'claworld_plugin_update_failed',
-      'OpenClaw no longer reported the claworld plugin as installed after plugin update.',
-      { before, after, trackedInstall },
-    );
-  }
-
-  return {
-    changed: true,
-    action: dryRun ? 'dry_run_tracked_plugin_update' : 'updated_tracked_plugin',
-    trackedInstall,
-    plugin: after,
-  };
-}
-
-async function fetchJson(fetchImpl, url, init = {}) {
-  let response;
-  try {
-    response = await fetchImpl(url, init);
-  } catch (error) {
-    throw createInstallerError(
-      'installer_fetch_failed',
-      `Failed to reach ${url}: ${error?.message || String(error)}`,
-      { url, method: init?.method || 'GET' },
-    );
-  }
-
-  const text = await response.text();
-  return {
-    ok: response.ok,
-    status: response.status,
-    body: parseJsonDocument(text, null),
-    text,
-  };
-}
-
-export async function fetchInstallManifest({
-  serverUrl = DEFAULT_CLAWORLD_SERVER_URL,
-  apiKey = null,
-  fetchImpl = globalThis.fetch?.bind(globalThis),
-} = {}) {
-  if (typeof fetchImpl !== 'function') {
-    throw createInstallerError('missing_fetch', 'Install manifest fetch requires a fetch implementation.');
-  }
-  const url = `${normalizeRelayHttpBaseUrl(serverUrl)}/v1/meta/install`;
-  const response = await fetchJson(fetchImpl, url, {
-    method: 'GET',
-    headers: buildFetchHeaders({ apiKey }),
-  });
-  if (!response.ok || !response.body) {
-    throw createInstallerError(
-      'install_manifest_unavailable',
-      `Failed to read Claworld install contract from ${url}.`,
-      { url, response },
-    );
-  }
-  return response.body;
-}
-
-export async function activateInstall({
-  serverUrl = DEFAULT_CLAWORLD_SERVER_URL,
-  apiKey = null,
-  appToken = null,
-  displayName = null,
-  fetchImpl = globalThis.fetch?.bind(globalThis),
-} = {}) {
-  if (typeof fetchImpl !== 'function') {
-    throw createInstallerError('missing_fetch', 'Install activation requires a fetch implementation.');
-  }
-  const url = `${normalizeRelayHttpBaseUrl(serverUrl)}/v1/onboarding/activate`;
-  const body = {};
-  if (displayName) {
-    body.displayName = displayName;
-  }
-  const response = await fetchJson(fetchImpl, url, {
-    method: 'POST',
-    headers: buildFetchHeaders({ apiKey, appToken, body: true }),
-    body: JSON.stringify(body),
-  });
-  if (!response.ok || !response.body) {
-    throw createInstallerError(
-      'install_activation_failed',
-      `Failed to activate Claworld install via ${url}.`,
-      { url, response },
-    );
-  }
-  return response.body;
-}
-
-export async function readGatewayStatus({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  const result = await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['gateway', 'status', '--json', '--no-probe'],
-    cwd,
-    env: buildOpenclawCommandEnv({ configPath, stateDir, env }),
-    dryRun,
-  });
-  const payload = parseCommandJsonOutput(result, null);
-  if (!payload) {
-    throw createInstallerError(
-      'invalid_gateway_status',
-      'OpenClaw gateway status did not produce JSON output.',
-      { result },
-    );
-  }
-  return payload;
-}
-
-export async function readChannelStatus({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  const result = await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['channels', 'status', '--json'],
-    cwd,
-    env: buildOpenclawCommandEnv({ configPath, stateDir, env }),
-    dryRun,
-  });
-  const payload = parseCommandJsonOutput(result, null);
-  if (!payload) {
-    const configFromDisk = configPath
-      ? await loadConfigFromDisk(configPath).catch(() => ({ existed: false, config: null }))
-      : { existed: false, config: null };
-    const synthesizedPayload = synthesizeChannelStatusFromConfig(configFromDisk?.config || null);
-    if (synthesizedPayload) {
-      return synthesizedPayload;
-    }
-    throw createInstallerError(
-      'invalid_channel_status',
-      'OpenClaw channel status did not produce JSON output.',
-      { result },
-    );
-  }
-  return payload;
-}
-
-export async function readAgentBindings({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  return await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['agents', 'bindings'],
-    cwd,
-    env: buildOpenclawCommandEnv({ configPath, stateDir, env }),
-    dryRun,
-    allowFailure: true,
-  });
-}
-
-export async function validateOpenclawConfig({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['config', 'validate'],
-    cwd,
-    env: buildOpenclawCommandEnv({ configPath, stateDir, env }),
-    dryRun,
-    capture: false,
-  });
-  return { ok: true };
-}
-
-export async function refreshOpenclawRuntime({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  const commandEnv = buildOpenclawCommandEnv({ configPath, stateDir, env });
-  const restart = await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['gateway', 'restart'],
-    cwd,
-    env: commandEnv,
-    dryRun,
-    capture: false,
-    allowFailure: true,
-  });
-  if (restart.status === 0) {
-    return { ok: true, action: 'restart', result: restart };
-  }
-
-  const start = await executeCommand({
-    commandRunner,
-    bin: openclawBin,
-    args: ['gateway', 'start'],
-    cwd,
-    env: commandEnv,
-    dryRun,
-    capture: false,
-    allowFailure: true,
-  });
-  if (start.status === 0) {
-    return { ok: true, action: 'start', result: start };
-  }
-
-  throw createInstallerError(
-    'openclaw_gateway_refresh_failed',
-    'Failed to restart or start the OpenClaw gateway service.',
-    { restart, start },
-  );
-}
-
-function wait(delayMs) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, delayMs);
-  });
-}
-
-export async function verifyClaworldInstall({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
-  agentId = DEFAULT_CLAWORLD_AGENT_ID,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-  attempts = DEFAULT_VERIFICATION_ATTEMPTS,
-  delayMs = DEFAULT_VERIFICATION_DELAY_MS,
-  requireGatewayRunning = resolveRequireGatewayRunning(env),
-  requireChannelToken = true,
-} = {}) {
-  let lastResult = null;
-
-  for (let attempt = 1; attempt <= attempts; attempt += 1) {
-    const [plugin, gatewayStatus, channelStatus, bindings] = await Promise.all([
-      inspectClaworldPluginInstall({
-        openclawBin,
-        configPath,
-        stateDir,
-        commandRunner,
-        cwd,
-        env,
-        dryRun,
-      }),
-      readGatewayStatus({
-        openclawBin,
-        configPath,
-        stateDir,
-        commandRunner,
-        cwd,
-        env,
-        dryRun,
-      }),
-      readChannelStatus({
-        openclawBin,
-        configPath,
-        stateDir,
-        commandRunner,
-        cwd,
-        env,
-        dryRun,
-      }),
-      readAgentBindings({
-        openclawBin,
-        configPath,
-        stateDir,
-        commandRunner,
-        cwd,
-        env,
-        dryRun,
-      }),
-    ]);
-
-    const channelAccount = readClaworldAccountStatus(channelStatus, accountId);
-    const gatewayRunning = gatewayStatus?.service?.runtime?.status === 'running';
-    const bindingLine = parseBindingLine(`${bindings.stdout || ''}${bindings.stderr || ''}`, {
-      agentId,
-      accountId,
-    });
-    const channelReady = Boolean(
-      channelAccount
-      && channelAccount.configured === true
-      && channelAccount.enabled !== false
-      && (
-        requireChannelToken !== true
-        || channelAccount.tokenStatus === 'available'
-      )
-    );
-    const pluginReady = Boolean(plugin.installed);
-    const bindingReady = Boolean(bindingLine);
-
-    lastResult = {
-      ok: pluginReady && channelReady && bindingReady && (!requireGatewayRunning || gatewayRunning),
-      attempt,
-      plugin,
-      gatewayStatus,
-      channelStatus,
-      channelAccount,
-      bindingLine,
-      gatewayRunning,
-      channelReady,
-      bindingReady,
-      requireGatewayRunning,
-      requireChannelToken,
-    };
-
-    if (lastResult.ok) {
-      return lastResult;
-    }
-    if (attempt < attempts) {
-      await wait(delayMs);
-    }
-  }
-
-  return lastResult || {
-    ok: false,
-    attempt: 0,
-  };
-}
-
-async function reconcileManagedClaworldRuntime({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = DEFAULT_OPENCLAW_CONFIG_PATH,
-  installerStatePath = null,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  currentConfigState = { existed: false, config: {} },
-  currentInstallerState = {},
-  currentConfig = {},
-  host = null,
-  serverUrl = null,
-  apiKey = null,
-  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
-  agentId = DEFAULT_CLAWORLD_AGENT_ID,
-  workspace = null,
-  displayName = null,
-  toolProfile = null,
-  sessionDmScope = null,
-  repoRoot = null,
-  fetchImpl = globalThis.fetch?.bind(globalThis),
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-  timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS,
-} = {}) {
-  const existingInstall = inspectManagedClaworldInstall({
-    cfg: currentConfig,
-    accountId,
-    installerState: currentInstallerState,
-    overrides: {
-      agentId,
-      workspace,
-      displayName,
-      toolProfile,
-      sessionDmScope,
-      ...(repoRoot ? { repoRoot } : {}),
-    },
-  });
-  const effectiveServerUrl = normalizeText(
-    serverUrl,
-    normalizeText(existingInstall.accountStatus?.serverUrl, DEFAULT_CLAWORLD_SERVER_URL),
-  );
-
-  const installAccountId = normalizeText(
-    accountId,
-    DEFAULT_CLAWORLD_ACCOUNT_ID,
-  );
-  const installAgentId = normalizeText(
-    agentId,
-    installAccountId,
-  );
-
-  const preflight = inspectManagedClaworldInstall({
-    cfg: currentConfig,
-    accountId: installAccountId,
-    installerState: currentInstallerState,
-    overrides: {
-      agentId: installAgentId,
-      workspace,
-      serverUrl: effectiveServerUrl,
-      displayName,
-      toolProfile,
-      sessionDmScope,
-      ...(repoRoot ? { repoRoot } : {}),
-    },
-  });
-  const desiredDisplayName = normalizeText(
-    displayName,
-    normalizeText(preflight.managedOptions.displayName, null),
-  );
-
-  const managedOptions = resolveClaworldManagedRuntimeOptions({
-    cfg: currentConfig,
-    installerState: currentInstallerState,
-    accountId: installAccountId,
-    overrides: {
-      agentId: installAgentId,
-      workspace,
-      serverUrl: effectiveServerUrl,
-      apiKey,
-      displayName: desiredDisplayName,
-      toolProfile,
-      sessionDmScope,
-      replaceManagedRuntime: true,
-      installPlugin: false,
-      pluginInstallMode: 'skip',
-      ...(repoRoot ? { repoRoot } : {}),
-    },
-  });
-
-  const transformed = applyClaworldBootstrapConfig(currentConfig, managedOptions);
-  const configChanged = JSON.stringify(currentConfigState.config) !== JSON.stringify(transformed.config);
-  const backupPath = configChanged
-    ? await backupConfigIfPresent(configPath, currentConfigState.existed, dryRun)
-    : null;
-  if (configChanged) {
-    await writeConfig(configPath, transformed.config, dryRun);
-  }
-
-  const workspaceActions = managedOptions.manageWorkspace
-    ? await seedManagedWorkspace(managedOptions, dryRun)
-    : [];
-  await validateOpenclawConfig({
-    openclawBin,
-    configPath,
-    stateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-  const runtimeRefresh = await refreshOpenclawRuntime({
-    openclawBin,
-    configPath,
-    stateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-  const verification = await verifyClaworldInstall({
-    openclawBin,
-    configPath,
-    stateDir,
-    accountId: installAccountId,
-    agentId: installAgentId,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-    delayMs: Math.min(timeoutMs, DEFAULT_VERIFICATION_DELAY_MS),
-    requireChannelToken: Boolean(managedOptions.appToken),
-  });
-  if (!verification.ok) {
-    throw createInstallerError(
-      'claworld_install_verification_failed',
-      'Claworld install verification did not confirm the managed channel runtime shape.',
-      { verification },
-    );
-  }
-
-  let installerStateChanged = false;
-  if (installerStatePath && installAccountId) {
-    const nextInstallerState = JSON.parse(JSON.stringify(ensureObject(currentInstallerState)));
-    setClaworldManagedRuntimeBackupState(nextInstallerState, installAccountId, null);
-    installerStateChanged = JSON.stringify(currentInstallerState) !== JSON.stringify(nextInstallerState);
-    if (installerStateChanged) {
-      await writeInstallerState(installerStatePath, nextInstallerState, dryRun);
-    }
-  }
-
-  return {
-    backupPath,
-    existingInstall,
-    effectiveServerUrl,
-    preflight,
-    activationStatus: managedOptions.appToken ? 'ready' : 'pending',
-    managedOptions,
-    transformed,
-    configChanged,
-    workspaceActions,
-    runtimeRefresh,
-    verification,
-    installerStatePath,
-    installerStateChanged,
-  };
-}
-
-export async function runClaworldInstallerInstall({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = DEFAULT_OPENCLAW_CONFIG_PATH,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  serverUrl = null,
-  apiKey = null,
-  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
-  agentId = DEFAULT_CLAWORLD_AGENT_ID,
-  workspace = null,
-  displayName = null,
-  toolProfile = null,
-  sessionDmScope = null,
-  repoRoot = null,
-  pluginInstallMode = 'npm',
-  pluginInstallSource = CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
-  fetchImpl = globalThis.fetch?.bind(globalThis),
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-  timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS,
-} = {}) {
-  const resolvedConfigPath = path.resolve(expandUserPath(configPath, os.homedir()));
-  const installerStatePath = resolveClaworldInstallerStatePath(resolvedConfigPath);
-  const resolvedStateDir = stateDir ? path.resolve(expandUserPath(stateDir, os.homedir())) : null;
-  const commandEnv = buildOpenclawCommandEnv({
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    env,
-  });
-  const currentConfigState = await loadConfigFromDisk(resolvedConfigPath);
-  const currentInstallerState = (await loadInstallerStateFromDisk(installerStatePath)).state;
-  const currentConfigBeforePluginInstall = currentConfigState.config;
-  const host = await detectOpenclawHost({
-    openclawBin,
-    commandRunner,
-    cwd,
-    env: commandEnv,
-    dryRun,
-  });
-  if (compareVersionParts(host.version, CLAWORLD_OPENCLAW_MIN_HOST_VERSION) < 0) {
-    throw createInstallerError(
-      'openclaw_version_too_old',
-      `OpenClaw ${host.version} is below the required minimum ${CLAWORLD_OPENCLAW_MIN_HOST_VERSION}.`,
-      { hostVersion: host.version, minHostVersion: CLAWORLD_OPENCLAW_MIN_HOST_VERSION },
-    );
-  }
-
-  const localPluginInstall = await resolveLocalPluginInstallTarget({
-    installMode: pluginInstallMode,
-    installSource: pluginInstallSource,
-    repoRoot,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-
-  const plugin = await ensureClaworldPluginInstalled({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    config: currentConfigBeforePluginInstall,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-    installMode: pluginInstallMode,
-    installSource: localPluginInstall.installSource,
-    refresh: false,
-  });
-  const currentConfig = mergePluginMetadata(
-    currentConfigBeforePluginInstall,
-    plugin.pluginConfig,
-  );
-  const lifecycle = await reconcileManagedClaworldRuntime({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    installerStatePath,
-    stateDir: resolvedStateDir,
-    currentConfigState,
-    currentInstallerState,
-    currentConfig,
-    host,
-    serverUrl,
-    apiKey,
-    accountId,
-    agentId,
-    workspace,
-    displayName,
-    toolProfile,
-    sessionDmScope,
-    repoRoot: plugin.managedRepoRoot || localPluginInstall.managedRepoRoot,
-    fetchImpl,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-    timeoutMs,
-  });
-
-  return {
-    ok: true,
-    command: CLAWORLD_INSTALLER_COMMAND,
-    configPath: resolvedConfigPath,
-    installerStatePath,
-    stateDir: resolvedStateDir,
-    host,
-    plugin,
-    ...lifecycle,
-  };
-}
-
-export async function runClaworldInstallerUpdate({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = DEFAULT_OPENCLAW_CONFIG_PATH,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  serverUrl = null,
-  apiKey = null,
-  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
-  agentId = DEFAULT_CLAWORLD_AGENT_ID,
-  workspace = null,
-  displayName = null,
-  pluginInstallSource = null,
-  toolProfile = null,
-  sessionDmScope = null,
-  fetchImpl = globalThis.fetch?.bind(globalThis),
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-  timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS,
-} = {}) {
-  const resolvedConfigPath = path.resolve(expandUserPath(configPath, os.homedir()));
-  const installerStatePath = resolveClaworldInstallerStatePath(resolvedConfigPath);
-  const resolvedStateDir = stateDir ? path.resolve(expandUserPath(stateDir, os.homedir())) : null;
-  const commandEnv = buildOpenclawCommandEnv({
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    env,
-  });
-  const currentConfigState = await loadConfigFromDisk(resolvedConfigPath);
-  const currentInstallerState = (await loadInstallerStateFromDisk(installerStatePath)).state;
-  const host = await detectOpenclawHost({
-    openclawBin,
-    commandRunner,
-    cwd,
-    env: commandEnv,
-    dryRun,
-  });
-  if (compareVersionParts(host.version, CLAWORLD_OPENCLAW_MIN_HOST_VERSION) < 0) {
-    throw createInstallerError(
-      'openclaw_version_too_old',
-      `OpenClaw ${host.version} is below the required minimum ${CLAWORLD_OPENCLAW_MIN_HOST_VERSION}.`,
-      { hostVersion: host.version, minHostVersion: CLAWORLD_OPENCLAW_MIN_HOST_VERSION },
-    );
-  }
-
-  const plugin = await updateTrackedClaworldPluginInstall({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    config: currentConfigState.config,
-    installSource: pluginInstallSource,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-
-  const refreshedConfigState = await loadConfigFromDisk(resolvedConfigPath);
-  const currentConfig = mergePluginMetadata(refreshedConfigState.config, plugin.pluginConfig || null);
-  const lifecycle = await reconcileManagedClaworldRuntime({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    installerStatePath,
-    stateDir: resolvedStateDir,
-    currentConfigState: refreshedConfigState,
-    currentInstallerState,
-    currentConfig,
-    host,
-    serverUrl,
-    apiKey,
-    accountId,
-    agentId,
-    workspace,
-    displayName,
-    toolProfile,
-    sessionDmScope,
-    repoRoot: plugin.managedRepoRoot || null,
-    fetchImpl,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-    timeoutMs,
-  });
-
-  return {
-    ok: true,
-    command: CLAWORLD_UPDATE_COMMAND,
-    configPath: resolvedConfigPath,
-    installerStatePath,
-    stateDir: resolvedStateDir,
-    host,
-    plugin,
-    ...lifecycle,
-  };
-}
-
-export async function runClaworldInstallerUninstall({
-  openclawBin = DEFAULT_OPENCLAW_BIN,
-  configPath = DEFAULT_OPENCLAW_CONFIG_PATH,
-  stateDir = DEFAULT_OPENCLAW_STATE_DIR,
-  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
-  agentId = DEFAULT_CLAWORLD_AGENT_ID,
-  commandRunner = defaultCommandRunner,
-  cwd = process.cwd(),
-  env = process.env,
-  dryRun = false,
-} = {}) {
-  const resolvedConfigPath = path.resolve(expandUserPath(configPath, os.homedir()));
-  const installerStatePath = resolveClaworldInstallerStatePath(resolvedConfigPath);
-  const resolvedStateDir = stateDir ? path.resolve(expandUserPath(stateDir, os.homedir())) : null;
-  const commandEnv = buildOpenclawCommandEnv({
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    env,
-  });
-  const currentConfigState = await loadConfigFromDisk(resolvedConfigPath);
-  const currentInstallerState = (await loadInstallerStateFromDisk(installerStatePath)).state;
-  const currentConfig = currentConfigState.config;
-  const trackedInstall = inspectTrackedClaworldPluginInstall(currentConfig);
-  const host = await detectOpenclawHost({
-    openclawBin,
-    commandRunner,
-    cwd,
-    env: commandEnv,
-    dryRun,
-  });
-  if (compareVersionParts(host.version, CLAWORLD_OPENCLAW_MIN_HOST_VERSION) < 0) {
-    throw createInstallerError(
-      'openclaw_version_too_old',
-      `OpenClaw ${host.version} is below the required minimum ${CLAWORLD_OPENCLAW_MIN_HOST_VERSION}.`,
-      { hostVersion: host.version, minHostVersion: CLAWORLD_OPENCLAW_MIN_HOST_VERSION },
-    );
-  }
-
-  const pluginBefore = await inspectClaworldPluginInstall({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-  const transformed = stripClaworldManagedRuntimeConfig(currentConfig, {
-    accountId,
-    agentId,
-    preserveBackup: true,
-  });
-  const configChanged = JSON.stringify(currentConfig) !== JSON.stringify(transformed.config);
-  const backupPath = configChanged
-    ? await backupConfigIfPresent(resolvedConfigPath, currentConfigState.existed, dryRun)
-    : null;
-  if (configChanged) {
-    await writeConfig(resolvedConfigPath, transformed.config, dryRun);
-  }
-  const nextInstallerState = JSON.parse(JSON.stringify(ensureObject(currentInstallerState)));
-  setClaworldManagedRuntimeBackupState(nextInstallerState, accountId, transformed.backup);
-  const installerStateChanged = JSON.stringify(currentInstallerState) !== JSON.stringify(nextInstallerState);
-  if (installerStateChanged) {
-    await writeInstallerState(installerStatePath, nextInstallerState, dryRun);
-  }
-
-  await validateOpenclawConfig({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-
-  const uninstallBootstrap = pluginBefore.installed
-    ? await preparePluginBootstrapConfig({
-        configPath: resolvedConfigPath,
-        config: currentConfig,
-        dryRun,
-      })
-    : null;
-
-  let pluginAction = 'plugin_already_absent';
-  try {
-    if (trackedInstall.source === 'installer_npm') {
-      const localInstallPath = normalizeText(trackedInstall.installPath, null) || normalizeText(trackedInstall.sourcePath, null);
-      if (!localInstallPath) {
-        throw createInstallerError(
-          'claworld_installer_managed_source_missing',
-          'Installer-managed Claworld source is missing its local install path.',
-          { trackedInstall },
-        );
-      }
-      if (!dryRun) {
-        await fs.rm(localInstallPath, { recursive: true, force: true });
-      }
-      pluginAction = 'removed_local_plugin_source';
-    } else if (pluginBefore.installed) {
-      await executeCommand({
-        commandRunner,
-        bin: openclawBin,
-        args: ['plugins', 'uninstall', 'claworld', '--force'],
-        cwd,
-        env: buildOpenclawCommandEnv({
-          configPath: uninstallBootstrap?.configPath || resolvedConfigPath,
-          stateDir: resolvedStateDir,
-          env,
-        }),
-        dryRun,
-        capture: false,
-      });
-      pluginAction = 'uninstalled_plugin';
-    }
-  } finally {
-    if (uninstallBootstrap) {
-      await uninstallBootstrap.cleanup();
-    }
-  }
-
-  const runtimeRefresh = await refreshOpenclawRuntime({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-  const pluginAfter = await inspectClaworldPluginInstall({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-  if ((pluginBefore.installed || trackedInstall.source === 'installer_npm') && pluginAfter.installed) {
-    throw createInstallerError(
-      'claworld_plugin_uninstall_failed',
-      'OpenClaw still reports the claworld plugin as installed after uninstall.',
-      { before: pluginBefore, after: pluginAfter },
-    );
-  }
-
-  const gatewayStatus = await readGatewayStatus({
-    openclawBin,
-    configPath: resolvedConfigPath,
-    stateDir: resolvedStateDir,
-    commandRunner,
-    cwd,
-    env,
-    dryRun,
-  });
-
-  return {
-    ok: true,
-    command: CLAWORLD_UNINSTALL_COMMAND,
-    configPath: resolvedConfigPath,
-    installerStatePath,
-    stateDir: resolvedStateDir,
-    host,
-    backupPath,
-    transformed,
-    configChanged,
-    installerStateChanged,
-    plugin: {
-      action: pluginAction,
-      before: pluginBefore,
-      after: pluginAfter,
-    },
-    runtimeRefresh,
-    gatewayStatus,
-  };
-}
-
-export {
-  compareVersionParts,
-  defaultCommandRunner,
-  findAgentEntry,
-  parseCommandVersion,
-  readClaworldAccountStatus,
-};