neoagent 2.3.1-beta.70 → 2.3.1-beta.72

package/server/services/runtime/backends/local-vm.js

@@ -7,6 +7,7 @@ const APK_UPLOAD_ROOT = path.resolve(
     || path.join(DATA_DIR, 'uploads', 'android-apks'),
 );
 const MAX_APK_BYTES = Number(process.env.NEOAGENT_ANDROID_APK_MAX_BYTES || 512 * 1024 * 1024);
+const IDLE_TIMEOUT_MS = Number(process.env.NEOAGENT_VM_IDLE_TIMEOUT_MS || 10 * 60 * 1000);
 
 function assertPathInside(baseDir, candidatePath, label) {
   const resolvedBase = path.resolve(baseDir);
@@ -23,9 +24,10 @@ function assertPathInside(baseDir, candidatePath, label) {
 }
 
 class RuntimeHttpClient {
-  constructor(baseUrl, token = '') {
+  constructor(baseUrl, token = '', options = {}) {
     this.baseUrl = String(baseUrl || '').replace(/\/+$/, '');
     this.token = String(token || '').trim();
+    this.onActivity = options.onActivity || null;
   }
 
   async waitForHealth(options = {}) {
@@ -53,26 +55,38 @@ class RuntimeHttpClient {
     throw new Error('Timed out waiting for the guest runtime to become ready.');
   }
 
-  async request(method, pathname, body) {
-    const response = await fetch(`${this.baseUrl}${pathname}`, {
-      method,
-      headers: {
-        'content-type': 'application/json',
-        ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
-      },
-      body: body === undefined ? undefined : JSON.stringify(body),
-    });
+  async request(method, pathname, body, options = {}) {
+    const controller = options.timeoutMs ? new AbortController() : null;
+    const timer = controller ? setTimeout(() => controller.abort(new Error(`Request timed out after ${options.timeoutMs} ms.`)), options.timeoutMs) : null;
+    try {
+      const response = await fetch(`${this.baseUrl}${pathname}`, {
+        method,
+        headers: {
+          'content-type': 'application/json',
+          ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller?.signal,
+      });
 
-    const contentType = response.headers.get('content-type') || '';
-    const payload = contentType.includes('application/json')
-      ? await response.json().catch(() => ({}))
-      : { text: await response.text().catch(() => '') };
+      const contentType = response.headers.get('content-type') || '';
+      const payload = contentType.includes('application/json')
+        ? await response.json().catch(() => ({}))
+        : { text: await response.text().catch(() => '') };
 
-    if (!response.ok) {
-      const errorMessage = payload?.error || payload?.text || `Runtime request failed: ${response.status}`;
-      throw new Error(errorMessage);
+      if (!response.ok) {
+        const errorMessage = payload?.error || payload?.text || `Runtime request failed: ${response.status}`;
+        throw new Error(errorMessage);
+      }
+      if (response.ok && typeof this.onActivity === 'function') {
+        this.onActivity();
+      }
+      return payload;
+    } finally {
+      if (timer) {
+        clearTimeout(timer);
+      }
     }
-    return payload;
   }
 
   async requestStream(method, pathname, stream, options = {}) {
@@ -88,6 +102,10 @@ class RuntimeHttpClient {
       duplex: 'half',
     });
 
+    if (response.ok && typeof this.onActivity === 'function') {
+      this.onActivity();
+    }
+
     const contentType = response.headers.get('content-type') || '';
     const payload = contentType.includes('application/json')
       ? await response.json().catch(() => ({}))
@@ -300,6 +318,37 @@ class LocalVmExecutionBackend {
     this.vmManager = options.vmManager;
     this.token = options.token || process.env.NEOAGENT_VM_GUEST_TOKEN || '';
     this.artifactStore = options.artifactStore || null;
+    this.lastActivity = new Map();
+    this.reaperInterval = null;
+
+    if (IDLE_TIMEOUT_MS > 0) {
+      this.#startIdleReaper();
+    }
+  }
+
+  #touch(userId) {
+    const key = String(userId || '').trim();
+    if (key) {
+      this.lastActivity.set(key, Date.now());
+    }
+  }
+
+  #startIdleReaper() {
+    if (this.reaperInterval) return;
+    this.reaperInterval = setInterval(async () => {
+      const now = Date.now();
+      for (const [userId, lastUsed] of this.lastActivity.entries()) {
+        if (now - lastUsed > IDLE_TIMEOUT_MS) {
+          console.log(`[Runtime] User ${userId} runtime idle for ${Math.round((now - lastUsed) / 1000)}s, shutting down VM.`);
+          this.lastActivity.delete(userId);
+          try {
+            await this.vmManager?.killVm?.(userId);
+          } catch (err) {
+            console.error(`[Runtime] Failed to shut down idle VM for user ${userId}:`, err.message);
+          }
+        }
+      }
+    }, Math.min(IDLE_TIMEOUT_MS, 60 * 1000));
   }
 
   async #clientForUser(userId) {
@@ -307,10 +356,13 @@ class LocalVmExecutionBackend {
       throw new Error('Local VM manager is not available.');
     }
     const session = await this.vmManager.ensureVm(userId);
-    const client = new RuntimeHttpClient(session.baseUrl, this.token);
+    this.#touch(userId);
+    const client = new RuntimeHttpClient(session.baseUrl, this.token, {
+      onActivity: () => this.#touch(userId),
+    });
     try {
       await client.waitForHealth({
-        timeoutMs: Number(process.env.NEOAGENT_VM_BOOT_TIMEOUT_MS || 120000),
+        timeoutMs: Number(process.env.NEOAGENT_VM_BOOT_TIMEOUT_MS || 20 * 60 * 1000),
       });
     } catch (error) {
       const runtimeError = typeof session.getLastError === 'function' ? session.getLastError() : '';
@@ -366,7 +418,32 @@ class LocalVmExecutionBackend {
     });
   }
 
+  async isGuestAgentReadyForUser(userId, timeoutMs = 1000) {
+    if (!this.vmManager) {
+      return false;
+    }
+    const key = String(userId || '').trim();
+    if (!key) {
+      return false;
+    }
+    const session = this.vmManager.instances?.get?.(key);
+    if (!session?.baseUrl) {
+      return false;
+    }
+    const client = new RuntimeHttpClient(session.baseUrl, this.token);
+    try {
+      await client.request('GET', '/health', undefined, { timeoutMs });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   async shutdown() {
+    if (this.reaperInterval) {
+      clearInterval(this.reaperInterval);
+      this.reaperInterval = null;
+    }
     await this.vmManager?.shutdown?.();
   }
 }

package/server/services/runtime/guest_bootstrap.js

@@ -0,0 +1,450 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { DATA_DIR } = require('../../../runtime/paths');
+
+const VM_ROOT = path.join(DATA_DIR, 'runtime-vms');
+const GUEST_BOOTSTRAP_ROOT = path.join(VM_ROOT, 'guest-bootstrap');
+
+fs.mkdirSync(GUEST_BOOTSTRAP_ROOT, { recursive: true });
+
+function encodeGuestToken(value) {
+  return Buffer.from(String(value || ''), 'utf8').toString('base64');
+}
+
+function createCloudInitScript({
+  guestToken,
+  hostShareMount,
+  hostDataMount = '/mnt/neoagent-data',
+  guestAgentPort = 8421,
+}) {
+  const guestTokenB64 = encodeGuestToken(guestToken);
+  const envFile = '/etc/neoagent/neoagent.env';
+  const appDir = '/opt/neoagent';
+  const bootstrapMarker = '/var/lib/neoagent/bootstrap-complete';
+  const nodeSourceSetupUrl = 'https://deb.nodesource.com/setup_20.x';
+
+  return [
+    '#!/usr/bin/env bash',
+    'set -euo pipefail',
+    '',
+    'export DEBIAN_FRONTEND=noninteractive',
+    `HOST_SHARE_MOUNT=${JSON.stringify(hostShareMount)}`,
+    `HOST_DATA_MOUNT=${JSON.stringify(hostDataMount)}`,
+    `APP_DIR=${JSON.stringify(appDir)}`,
+    `BOOTSTRAP_MARKER=${JSON.stringify(bootstrapMarker)}`,
+    `ENV_FILE=${JSON.stringify(envFile)}`,
+    '',
+    'mkdir -p /etc/neoagent /var/lib/neoagent "$HOST_SHARE_MOUNT" "$HOST_DATA_MOUNT" "$APP_DIR"',
+    '',
+    '# Ensure the 9p virtio filesystem driver is loaded',
+    'modprobe 9p 2>/dev/null || true',
+    'modprobe 9pnet_virtio 2>/dev/null || true',
+    '',
+    'if ! grep -qs "neoagent-host" /etc/fstab; then',
+    '  echo "neoagent-host ${HOST_SHARE_MOUNT} 9p trans=virtio,version=9p2000.L,msize=104857600,ro 0 0" >> /etc/fstab',
+    'fi',
+    'if ! grep -qs "neoagent-data" /etc/fstab; then',
+    '  echo "neoagent-data ${HOST_DATA_MOUNT} 9p trans=virtio,version=9p2000.L,msize=104857600,rw 0 0" >> /etc/fstab',
+    'fi',
+    '',
+    'mount "$HOST_SHARE_MOUNT" >/dev/null 2>&1 || mount -a >/dev/null 2>&1 || true',
+    'mount "$HOST_DATA_MOUNT" >/dev/null 2>&1 || mount -a >/dev/null 2>&1 || true',
+    '',
+    '# Redirect logs to the host-writable share once mounted',
+    'LOG_FILE="${HOST_DATA_MOUNT}/bootstrap.log"',
+    'exec >"$LOG_FILE" 2>&1',
+    'echo "NeoAgent guest bootstrap starting."',
+    '',
+    'apt-get update',
+    'apt-get install -y --no-install-recommends \\',
+    '  curl \\',
+    '  ca-certificates \\',
+    '  gnupg \\',
+    '  openjdk-17-jre-headless \\',
+    '  git \\',
+    '  rsync \\',
+    '  build-essential \\',
+    '  python3 \\',
+    '  unzip \\',
+    '  libatk1.0-0 \\',
+    '  libatk-bridge2.0-0 \\',
+    '  libatspi2.0-0 \\',
+    '  libcups2 \\',
+    '  libx11-xcb1 \\',
+    '  libgtk-3-0 \\',
+    '  libnss3 \\',
+    '  libnspr4 \\',
+    '  libxcomposite1 \\',
+    '  libxdamage1 \\',
+    '  libxrandr2 \\',
+    '  libxkbcommon0 \\',
+    '  libasound2t64 \\',
+    '  libgbm1 \\',
+    '  libdrm2 \\',
+    '  libdbus-1-3 \\',
+    '  libpango-1.0-0 \\',
+    '  libpangocairo-1.0-0 \\',
+    '  libxshmfence1',
+    'apt-get clean >/dev/null 2>&1 || true',
+    'rm -rf /var/lib/apt/lists/*',
+    '',
+    'if [ -d "$HOST_SHARE_MOUNT" ]; then',
+    '  SYNC_PATHS=(',
+    '    server/guest-agent.package.json:package.json',
+    '    runtime/env.js',
+    '    runtime/paths.js',
+    '    server/guest_agent.js',
+    '    server/services/cli',
+    '    server/services/browser',
+    '    server/services/android',
+    '  )',
+    '  for relPath in "${SYNC_PATHS[@]}"; do',
+    '    sourceRelPath="$relPath"',
+    '    targetRelPath="$relPath"',
+    '    if [[ "$relPath" == *:* ]]; then',
+    '      sourceRelPath="${relPath%%:*}"',
+    '      targetRelPath="${relPath##*:}"',
+    '    fi',
+    '    sourcePath="$HOST_SHARE_MOUNT/$sourceRelPath"',
+    '    targetPath="$APP_DIR/$targetRelPath"',
+    '    if [ ! -e "$sourcePath" ]; then',
+    '      echo "Required host path is missing: $relPath" >&2',
+    '      exit 1',
+    '    fi',
+    '    mkdir -p "$(dirname "$targetPath")"',
+    '    if [ -d "$sourcePath" ]; then',
+    '      mkdir -p "$targetPath"',
+    '      rsync -a --delete "$sourcePath"/ "$targetPath"/',
+    '    else',
+    '      rsync -a "$sourcePath" "$targetPath"',
+    '    fi',
+    '  done',
+    'else',
+    '  echo "Host repo share is not available." >&2',
+    '  exit 1',
+    'fi',
+    '',
+    'if ! command -v node >/dev/null 2>&1 || ! node -e "process.exit(Number(process.versions.node.split(\'.\')[0]) >= 20 ? 0 : 1)"; then',
+    '  curl -fsSL ' + JSON.stringify(nodeSourceSetupUrl) + ' | bash -',
+    '  apt-get install -y --no-install-recommends nodejs',
+    '  apt-get clean >/dev/null 2>&1 || true',
+    '  rm -rf /var/lib/apt/lists/*',
+    'fi',
+    '',
+    `printf '%s\n' ${JSON.stringify(`NEOAGENT_VM_GUEST_TOKEN_B64=${guestTokenB64}`)} > "$ENV_FILE"`,
+    `printf '%s\n' ${JSON.stringify(`NEOAGENT_GUEST_AGENT_PORT=${guestAgentPort}`)} >> "$ENV_FILE"`,
+    'chmod 0600 "$ENV_FILE"',
+    '',
+    'cd "$APP_DIR"',
+    'if [ ! -d node_modules ] || [ ! -f node_modules/.neoagent-bootstrap-stamp ] || [ package.json -nt node_modules/.neoagent-bootstrap-stamp ]; then',
+    '  export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1',
+    '  npm install --omit=dev --no-audit --no-fund',
+    '  mkdir -p node_modules',
+    '  date > node_modules/.neoagent-bootstrap-stamp',
+    'fi',
+    '',
+    '# Install Playwright browser binaries (skipped if already present)',
+    'PLAYWRIGHT_BROWSERS_PATH="$APP_DIR/.playwright-browsers"',
+    'PLAYWRIGHT_STAMP="$PLAYWRIGHT_BROWSERS_PATH/.chromium-installed"',
+    'if [ ! -f "$PLAYWRIGHT_STAMP" ]; then',
+    '  mkdir -p "$PLAYWRIGHT_BROWSERS_PATH"',
+    '  PLAYWRIGHT_BROWSERS_PATH="$PLAYWRIGHT_BROWSERS_PATH" npx playwright install chromium --with-deps || \\',
+    '    PLAYWRIGHT_BROWSERS_PATH="$PLAYWRIGHT_BROWSERS_PATH" node ./node_modules/playwright-chromium/install.js || true',
+    '  date > "$PLAYWRIGHT_STAMP"',
+    'fi',
+    'export PLAYWRIGHT_BROWSERS_PATH',
+    '',
+    'systemctl daemon-reload',
+    'systemctl enable neoagent-guest-agent.service',
+    'systemctl restart neoagent-guest-agent.service',
+    'touch "$BOOTSTRAP_MARKER"',
+    'echo "NeoAgent guest bootstrap completed."',
+    '',
+  ].join('\n');
+}
+
+function createCloudInitUserData({
+  guestToken,
+  hostShareMount = '/mnt/neoagent-host',
+  hostDataMount = '/mnt/neoagent-data',
+  guestAgentPort = 8421,
+}) {
+  const guestTokenB64 = encodeGuestToken(guestToken);
+  const bootstrapScript = createCloudInitScript({
+    guestToken,
+    hostShareMount,
+    hostDataMount,
+    guestAgentPort,
+  });
+
+  return [
+    '#cloud-config',
+    'package_update: false',
+    'write_files:',
+    '  - path: /etc/neoagent/neoagent.env',
+    "    permissions: '0600'",
+    '    owner: root:root',
+    '    content: |',
+    `      NEOAGENT_VM_GUEST_TOKEN_B64=${guestTokenB64}`,
+    `      NEOAGENT_GUEST_AGENT_PORT=${guestAgentPort}`,
+    '  - path: /usr/local/bin/neoagent-guest-bootstrap.sh',
+    "    permissions: '0755'",
+    '    owner: root:root',
+    '    content: |',
+    ...bootstrapScript.split('\n').map((line) => `      ${line}`),
+    '  - path: /etc/systemd/system/neoagent-guest-agent.service',
+    "    permissions: '0644'",
+    '    owner: root:root',
+    '    content: |',
+    '      [Unit]',
+    '      Description=NeoAgent guest agent',
+    '      After=network-online.target',
+    '      Wants=network-online.target',
+    '',
+    '      [Service]',
+    '      Type=simple',
+    '      EnvironmentFile=/etc/neoagent/neoagent.env',
+    '      Environment=PLAYWRIGHT_BROWSERS_PATH=/opt/neoagent/.playwright-browsers',
+    '      WorkingDirectory=/opt/neoagent',
+    '      ExecStart=/usr/bin/env node /opt/neoagent/server/guest_agent.js',
+    '      Restart=always',
+    '      RestartSec=5',
+    '',
+    '      [Install]',
+    '      WantedBy=multi-user.target',
+    '  - path: /etc/systemd/system/neoagent-guest-bootstrap.service',
+    "    permissions: '0644'",
+    '    owner: root:root',
+    '    content: |',
+    '      [Unit]',
+    '      Description=NeoAgent guest bootstrap',
+    '      After=network-online.target',
+    '      Wants=network-online.target',
+    '',
+    '      [Service]',
+    '      Type=oneshot',
+    '      ExecStart=/usr/local/bin/neoagent-guest-bootstrap.sh',
+    '      RemainAfterExit=yes',
+    '',
+    '      [Install]',
+    '      WantedBy=multi-user.target',
+    'runcmd:',
+    '  - [bash, -lc, "systemctl daemon-reload"]',
+    '  - [bash, -lc, "systemctl enable neoagent-guest-bootstrap.service"]',
+    '  - [bash, -lc, "systemctl start neoagent-guest-bootstrap.service"]',
+    '',
+  ].join('\n');
+}
+
+function createCloudInitMetaData({ instanceId, localHostName }) {
+  return [
+    `instance-id: ${instanceId}`,
+    `local-hostname: ${localHostName}`,
+    '',
+  ].join('\n');
+}
+
+function commandExists(command) {
+  const probe = spawnSync(
+    process.platform === 'win32' ? 'where' : 'bash',
+    process.platform === 'win32' ? [command] : ['-lc', `command -v "${command}"`],
+    { stdio: 'ignore' },
+  );
+  return probe.status === 0;
+}
+
+function parseDiskutilMountPoint(output) {
+  const match = String(output || '').match(/Mount Point:\s+(.+)/);
+  return match ? match[1].trim() : null;
+}
+
+function copySeedFilesToVolume(volumePath, sourceDir) {
+  for (const entry of ['user-data', 'meta-data', 'startup.nsh']) {
+    const sourcePath = path.join(sourceDir, entry);
+    const targetPath = path.join(volumePath, entry);
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+}
+
+function createFatSeedImage(sourceDir, imagePath) {
+  if (process.platform === 'win32') {
+    throw new Error('Creating a FAT seed image is not supported on Windows yet.');
+  }
+
+  const hdiutilAvailable = commandExists('hdiutil');
+  const newfsMsdosPath = commandExists('/sbin/newfs_msdos') ? '/sbin/newfs_msdos' : (commandExists('newfs_msdos') ? 'newfs_msdos' : null);
+  const diskutilAvailable = commandExists('diskutil');
+  if (!hdiutilAvailable || !newfsMsdosPath || !diskutilAvailable) {
+    throw new Error('Required disk image tools are not available.');
+  }
+
+  fs.mkdirSync(path.dirname(imagePath), { recursive: true });
+  fs.rmSync(imagePath, { force: true });
+  fs.writeFileSync(imagePath, Buffer.alloc(32 * 1024 * 1024));
+
+  let device = null;
+  try {
+    const attachResult = spawnSync('hdiutil', ['attach', '-nomount', imagePath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (attachResult.status !== 0) {
+      throw new Error(
+        String(attachResult.stderr || attachResult.stdout || attachResult.error?.message || 'Failed to attach FAT seed image.')
+          .trim(),
+      );
+    }
+
+    device = String(attachResult.stdout || '').trim().split('\n').find(Boolean)?.split(/\s+/)[0] || null;
+    if (!device) {
+      throw new Error('Failed to resolve the temporary FAT seed device.');
+    }
+    const rawDevice = device.replace('/dev/disk', '/dev/rdisk');
+
+    const formatResult = spawnSync(newfsMsdosPath, ['-v', 'CIDATA', rawDevice], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (formatResult.status !== 0) {
+      throw new Error(
+        String(formatResult.stderr || formatResult.stdout || formatResult.error?.message || 'Failed to format FAT seed image.')
+          .trim(),
+      );
+    }
+
+    const mountResult = spawnSync('diskutil', ['mount', device], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (mountResult.status !== 0) {
+      throw new Error(
+        String(mountResult.stderr || mountResult.stdout || mountResult.error?.message || 'Failed to mount FAT seed image.')
+          .trim(),
+      );
+    }
+
+    const mountPoint = parseDiskutilMountPoint(mountResult.stdout)
+      || parseDiskutilMountPoint(spawnSync('diskutil', ['info', device], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }).stdout)
+      || `/Volumes/CIDATA`;
+
+    if (!fs.existsSync(mountPoint)) {
+      throw new Error(`Mounted FAT seed volume is missing at ${mountPoint}.`);
+    }
+
+    copySeedFilesToVolume(mountPoint, sourceDir);
+    return imagePath;
+  } finally {
+    if (device) {
+      try {
+        spawnSync('diskutil', ['unmount', 'force', device], { stdio: 'ignore' });
+      } catch {}
+      try {
+        spawnSync('hdiutil', ['detach', device], { stdio: 'ignore' });
+      } catch {}
+    }
+  }
+}
+
+function createSeedIso(sourceDir, isoPath) {
+  const candidates = [
+    {
+      command: 'xorriso',
+      args: ['-as', 'mkisofs', '-output', isoPath, '-volid', 'CIDATA', '-joliet', '-rock', sourceDir],
+    },
+    {
+      command: 'cloud-localds',
+      args: [isoPath, path.join(sourceDir, 'user-data'), path.join(sourceDir, 'meta-data')],
+    },
+    {
+      command: 'hdiutil',
+      args: ['makehybrid', '-ov', '-o', isoPath, '-iso', '-joliet', '-iso-volume-name', 'CIDATA', '-joliet-volume-name', 'CIDATA', sourceDir],
+    },
+    {
+      command: 'mkisofs',
+      args: ['-o', isoPath, '-V', 'CIDATA', '-J', '-r', sourceDir],
+    },
+  ];
+
+  let lastError = null;
+  for (const candidate of candidates) {
+    if (!commandExists(candidate.command)) {
+      continue;
+    }
+
+    const result = spawnSync(candidate.command, candidate.args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status === 0 && fs.existsSync(isoPath)) {
+      return isoPath;
+    }
+    lastError = new Error(
+      String(result.stderr || result.stdout || result.error?.message || `exit status ${result.status ?? 'unknown'}`).trim() || `Failed to create seed ISO with ${candidate.command}.`
+    );
+  }
+
+  throw new Error(`Unable to create cloud-init seed ISO: ${lastError ? lastError.message : 'no supported ISO writer was found.'}`);
+}
+
+function ensureGuestBootstrapSeed({
+  userRoot,
+  guestToken,
+  hostShareMount = '/mnt/neoagent-host',
+  guestAgentPort = 8421,
+}) {
+  const seedRoot = path.join(userRoot, 'cloud-init');
+  const seedDir = path.join(seedRoot, 'seed');
+  const seedImagePath = path.join(seedRoot, 'cidata.img');
+  const isoPath = path.join(seedRoot, 'cidata.iso');
+  fs.mkdirSync(seedDir, { recursive: true });
+
+  const userDataPath = path.join(seedDir, 'user-data');
+  const metaDataPath = path.join(seedDir, 'meta-data');
+  const startupNshPath = path.join(seedDir, 'startup.nsh');
+  const userData = createCloudInitUserData({ guestToken, hostShareMount, guestAgentPort });
+  const metaData = createCloudInitMetaData({
+    instanceId: `neoagent-${path.basename(userRoot)}`,
+    localHostName: `neoagent-${path.basename(userRoot)}`,
+  });
+  const startupNsh = [
+    '@echo -off',
+    'map -r',
+    'fs0:',
+    '\\EFI\\ubuntu\\shimx64.efi',
+    '\\EFI\\ubuntu\\grubx64.efi',
+    '\\EFI\\BOOT\\BOOTX64.EFI',
+  ].join('\r\n');
+
+  fs.writeFileSync(userDataPath, userData);
+  fs.writeFileSync(metaDataPath, metaData);
+  fs.writeFileSync(startupNshPath, startupNsh);
+  let createdSeedPath = null;
+  try {
+    createdSeedPath = createFatSeedImage(seedDir, seedImagePath);
+  } catch (error) {
+    createdSeedPath = createSeedIso(seedDir, isoPath);
+  }
+
+  return {
+    seedRoot,
+    seedDir,
+    seedImagePath: createdSeedPath,
+    isoPath: createdSeedPath === isoPath ? isoPath : null,
+    userDataPath,
+    metaDataPath,
+    startupNshPath,
+    hostShareMount,
+  };
+}
+
+module.exports = {
+  createCloudInitMetaData,
+  createCloudInitUserData,
+  createSeedIso,
+  ensureGuestBootstrapSeed,
+  GUEST_BOOTSTRAP_ROOT,
+};

package/server/services/runtime/manager.js

@@ -40,6 +40,10 @@ class RuntimeManager {
     return backend.executeCommand(userId, command, options);
   }
 
+  hasVmForUser(userId) {
+    return Boolean(this.vmBackend?.vmManager?.hasVm?.(userId));
+  }
+
   async killCommand(userId, pid, reason = 'aborted') {
     return this.vmBackend.killCommand(userId, pid, reason);
   }
@@ -60,6 +64,13 @@ class RuntimeManager {
     return this.vmBackend.getAndroidProviderForUser(userId);
   }
 
+  async isGuestAgentReadyForUser(userId, timeoutMs = 1000) {
+    if (typeof this.vmBackend?.isGuestAgentReadyForUser !== 'function') {
+      return false;
+    }
+    return this.vmBackend.isGuestAgentReadyForUser(userId, timeoutMs);
+  }
+
   async shutdown() {
     await Promise.allSettled([this.vmBackend.shutdown()]);
   }