neoagent 3.2.1-beta.6 → 3.2.1-beta.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neoagent",
-  "version": "3.2.1-beta.6",
+  "version": "3.2.1-beta.7",
   "description": "Self-hosted AI agent for long-running tasks, automation, messaging, device control, and local memory",
   "license": "AGPL-3.0-only",
   "main": "server/index.js",

package/server/public/.last_build_id

@@ -1 +1 @@
-47dfb68683e209ba52dcaade6052a7c2
+4e3d49d31cbb561d89adf60e16759ebe

package/server/public/flutter_bootstrap.js

@@ -37,6 +37,6 @@ _flutter.buildConfig = {"engineRevision":"69c8c61792f04cc809dfef0c910414fb9afc06
 
 _flutter.loader.load({
   serviceWorkerSettings: {
-    serviceWorkerVersion: "1886361738" /* Flutter's service worker is deprecated and will be removed in a future Flutter release. */
+    serviceWorkerVersion: "3827219452" /* Flutter's service worker is deprecated and will be removed in a future Flutter release. */
   }
 });

package/server/public/main.dart.js

@@ -144506,7 +144506,7 @@ if(r){r=s.d
 r===$&&A.b()
 p.push(A.ju(q,A.jx(!1,new A.Y(B.wP,A.cU(new A.cH(B.kE,new A.acU(r,q),q),q,q),q),!1,B.J,!0),q,q,0,0,0,q))}if(!s.ay){r=s.e
 r===$&&A.b()
-r=B.b.t("mry17udu-e9492af").length!==0&&r.b}else r=!1
+r=B.b.t("mry3rvmk-b952e5d").length!==0&&r.b}else r=!1
 if(r){r=s.d
 r===$&&A.b()
 r=r.aU&&!r.ag?84:0
@@ -150393,7 +150393,7 @@ $S:0}
 A.a3j.prototype={}
 A.WC.prototype={
 r9(a){var s=this
-if(B.b.t("mry17udu-e9492af").length===0||s.a!=null)return
+if(B.b.t("mry3rvmk-b952e5d").length===0||s.a!=null)return
 s.Co()
 s.a=A.mL(B.Yh,new A.bmK(s))},
 Co(){var s=0,r=A.l(t.H),q,p=2,o=[],n=this,m,l,k,j,i,h,g,f
@@ -150411,7 +150411,7 @@ if(!t.f.b(k)){s=1
 break}i=J.a0(k,"buildId")
 h=i==null?null:B.b.t(J.q(i))
 j=h==null?"":h
-if(J.bv(j)===0||J.e(j,"mry17udu-e9492af")){s=1
+if(J.bv(j)===0||J.e(j,"mry3rvmk-b952e5d")){s=1
 break}n.b=!0
 n.H()
 p=2
@@ -150428,7 +150428,7 @@ case 2:return A.i(o.at(-1),r)}})
 return A.k($async$Co,r)},
 wV(){var s=0,r=A.l(t.H),q,p=2,o=[],n=this,m,l,k,j,i,h,g,f,e,d,c,b,a,a0,a1
 var $async$wV=A.h(function(a2,a3){if(a2===1){o.push(a3)
-s=p}for(;;)switch(s){case 0:if(B.b.t("mry17udu-e9492af").length===0||n.c){s=1
+s=p}for(;;)switch(s){case 0:if(B.b.t("mry3rvmk-b952e5d").length===0||n.c){s=1
 break}n.c=!0
 n.H()
 p=4

package/server/services/ai/capabilityHealth.js

@@ -39,6 +39,9 @@ async function getBrowserHealth(userId, app, engine) {
   const runtimeSettings = typeof runtimeManager?.getSettings === 'function'
     ? runtimeManager.getSettings(userId)
     : null;
+  const runtimeSnapshot = typeof runtimeManager?.getCapabilitySnapshot === 'function'
+    ? runtimeManager.getCapabilitySnapshot(userId)
+    : null;
   const extensionStatus = runtimeSettings?.browser_backend === 'extension'
     ? app?.locals?.browserExtensionRegistry?.getStatus(userId)
     : null;
@@ -63,122 +66,81 @@ async function getBrowserHealth(userId, app, engine) {
       });
     }
   }
-  let controller = null;
-  let resolutionError = null;
-
-  if (runtimeManager && typeof runtimeManager.getBrowserProviderForUser === 'function') {
-    try {
-      controller = await runtimeManager.getBrowserProviderForUser(userId);
-    } catch (err) {
-      resolutionError = err;
-    }
-  }
-
-  if (!controller) {
-    resolutionError = resolutionError || new Error('Browser provider is unavailable. VM runtime is required.');
-  }
-
-  if (!controller && resolutionError) {
+  if (!runtimeManager) {
     return capabilityEntry({
-      configured: true,
-      healthy: false,
-      degraded: true,
-      summary: `Browser controller resolution failed: ${resolutionError.message}`,
-      details: {
-        error: resolutionError.message,
-      },
+      summary: 'Browser runtime is not available in this environment.',
     });
   }
-  let pageInfo = null;
-  let launched = false;
-  let error = null;
 
-  try {
-    launched = typeof controller?.isLaunched === 'function'
-      ? await Promise.resolve(controller.isLaunched())
-      : false;
-    pageInfo = typeof controller?.getPageInfo === 'function' ? await controller.getPageInfo() : null;
-  } catch (err) {
-    error = err.message;
-  }
+  // Capability reporting runs on every agent turn. It must never resolve a
+  // provider because the VM provider performs image builds and container boot.
+  // Tool execution remains the authoritative health check and starts/restarts
+  // the runtime only when the model actually uses a browser tool.
+  const preferredBackend = runtimeSettings?.browser_backend
+    || runtimeSnapshot?.browser?.preferredBackend
+    || 'vm';
+  const vmInitialized = runtimeSnapshot?.browser?.vmInitialized === true;
+  const extensionConnected = extensionStatus?.connected === true
+    || runtimeSnapshot?.browser?.extensionConnected === true;
+  const extensionPreferredButOffline = preferredBackend === 'extension' && !extensionConnected;
 
   return capabilityEntry({
-    connected: launched,
+    connected: vmInitialized || extensionConnected,
     configured: true,
-    healthy: !error,
-    degraded: Boolean(error) || runtimeSettings?.browser_backend === 'extension',
-    summary: error
-      ? `Browser runtime error: ${error}`
-      : runtimeSettings?.browser_backend === 'extension'
-        ? `No extension device is active. Falling back to the vm browser runtime.`
-        : (launched ? 'Browser runtime is ready.' : 'Browser runtime is available but not launched.'),
+    healthy: true,
+    degraded: extensionPreferredButOffline,
+    summary: extensionPreferredButOffline
+      ? 'No extension device is active. The VM browser will start on first use.'
+      : vmInitialized
+        ? 'Browser VM session is initialized.'
+        : 'Browser runtime is available and will start on first use.',
     details: {
-      preferredBackend: runtimeSettings?.browser_backend || null,
-      backend: runtimeSettings?.browser_backend === 'extension'
-        ? 'vm'
-        : runtimeSettings?.browser_backend || null,
-      extensionConnected: extensionStatus?.connected === true,
+      preferredBackend,
+      backend: extensionConnected ? 'extension' : 'vm',
+      extensionConnected,
       activeTokenCount: Array.isArray(extensionStatus?.tokens)
         ? extensionStatus.tokens.filter((token) => token.status === 'active').length
         : 0,
-      launched,
-      pageInfo,
+      runtimeInitialized: vmInitialized,
     },
   });
 }
 
 async function getAndroidHealth(userId, app, engine) {
   const runtimeManager = app?.locals?.runtimeManager || engine?.runtimeManager || null;
-  let controller = null;
-  let resolutionError = null;
-
-  if (runtimeManager && typeof runtimeManager.getAndroidProviderForUser === 'function') {
-    try {
-      controller = await runtimeManager.getAndroidProviderForUser(userId);
-    } catch (err) {
-      resolutionError = err;
-    }
-  }
-
-  if (!controller) {
-    resolutionError = resolutionError || new Error('Android provider is unavailable. VM runtime is required.');
-  }
-
-  if (!controller || typeof controller.getStatus !== 'function') {
+  if (!runtimeManager) {
     return capabilityEntry({
-      degraded: Boolean(resolutionError),
-      summary: resolutionError
-        ? `Android controller resolution failed: ${resolutionError.message}`
-        : 'Android controller is not available.',
-      details: resolutionError ? { error: resolutionError.message } : {},
+      summary: 'Android runtime is not available in this environment.',
     });
   }
 
-  try {
-    const status = await controller.getStatus();
-    const bootstrapped = status.bootstrapped === true;
-    const canBootstrap = status.canBootstrap === true;
-    return capabilityEntry({
-      connected: Array.isArray(status.devices) && status.devices.some((device) => device.status === 'device'),
-      configured: canBootstrap || bootstrapped,
-      healthy: canBootstrap || bootstrapped,
-      degraded: Boolean(status.lastStartError),
-      summary: status.lastStartError
-        ? `Android tooling reported: ${status.lastStartError}`
-        : bootstrapped
-          ? 'Android environment is ready on this host.'
-          : (canBootstrap ? 'Android environment can be bootstrapped on this host.' : 'Android tooling cannot bootstrap on this host.'),
-      details: status,
-    });
-  } catch (err) {
-    return capabilityEntry({
-      configured: true,
-      healthy: false,
-      degraded: true,
-      summary: `Android status check failed: ${err.message}`,
-      details: { error: err.message },
-    });
-  }
+  // Like browser health, Android health is a snapshot. Creating a controller or
+  // running adb here makes unrelated chat turns pay runtime startup/status costs.
+  const runtimeSnapshot = typeof runtimeManager.getCapabilitySnapshot === 'function'
+    ? runtimeManager.getCapabilitySnapshot(userId)
+    : null;
+  const status = runtimeSnapshot?.android?.status || null;
+  const bootstrapped = status?.bootstrapped === true;
+  const starting = status?.starting === true;
+  const lastStartError = String(status?.lastStartError || '').trim();
+  return capabilityEntry({
+    connected: bootstrapped,
+    configured: true,
+    healthy: !lastStartError,
+    degraded: Boolean(lastStartError),
+    summary: lastStartError
+      ? `Android tooling reported: ${lastStartError}`
+      : bootstrapped
+        ? 'Android environment is ready.'
+        : starting
+          ? 'Android environment is starting.'
+          : 'Android runtime is available and will initialize on first use.',
+    details: status || {
+      initialized: runtimeSnapshot?.android?.initialized === true,
+      bootstrapped: false,
+      starting: false,
+    },
+  });
 }
 
 function getMessagingHealth(userId, app, engine, agentId = null) {
@@ -342,7 +304,9 @@ function getTaskHealth(userId, agentId = null) {
 }
 
 async function getCapabilityHealth({ userId, agentId = null, app, engine }) {
-  const providers = await getProviderHealthCatalog(userId, agentId);
+  const providers = await getProviderHealthCatalog(userId, agentId, {
+    probeLocal: false,
+  });
 
   return {
     providers,
@@ -363,6 +327,8 @@ async function getCapabilityHealth({ userId, agentId = null, app, engine }) {
 }
 
 module.exports = {
+  getAndroidHealth,
+  getBrowserHealth,
   getCapabilityHealth,
   summarizeCapabilityHealth,
 };

package/server/services/ai/loop/conversation_loop.js

@@ -59,6 +59,11 @@ const {
   normalizeModelSelections,
   resolveModelSelection,
 } = require('../model_identity');
+const {
+  isModelCoolingDown,
+  recordModelFailure,
+  recordModelSuccess,
+} = require('../model_failure_cache');
 const { getProviderForUser } = require('../provider_selector');
 const { IterationBudget } = require('./iteration_budget');
 const {
@@ -421,7 +426,10 @@ async function getFailureFallbackModelId(
   const { getSupportedModels } = require('../models');
   const aiSettings = getAiSettings(userId, agentId);
   const models = await getSupportedModels(userId, agentId, { signal });
-  const availableModels = models.filter((model) => model.available !== false);
+  const availableModels = models.filter(
+    (model) => model.available !== false
+      && !isModelCoolingDown(userId, agentId, model.id),
+  );
   const configuredEnabledIds = Array.isArray(aiSettings.enabled_models)
     ? aiSettings.enabled_models.map((id) => String(id).trim()).filter(Boolean)
     : [];
@@ -599,6 +607,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   db.prepare('UPDATE agent_runs SET model = ?, updated_at = datetime(\'now\') WHERE id = ?')
     .run(modelSelectionId, runId);
   const switchToFallbackModel = async (failedSelectionId, error, phase) => {
+    recordModelFailure(userId, agentId, failedSelectionId, error);
     const fallbackModelId = await getFailureFallbackModelId(
       userId,
       agentId,
@@ -639,12 +648,16 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   };
   const runWithModelFallback = async (phase, fn) => {
     try {
-      return await fn();
+      const result = await fn();
+      recordModelSuccess(userId, agentId, modelSelectionId);
+      return result;
     } catch (err) {
       const failedSelectionId = modelSelectionId;
       const switched = await switchToFallbackModel(failedSelectionId, err, phase);
       if (!switched) throw err;
-      return await fn();
+      const result = await fn();
+      recordModelSuccess(userId, agentId, modelSelectionId);
+      return result;
     }
   };
 
@@ -1492,8 +1505,10 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           response = modelCall.response;
           responseModel = modelCall.responseModel;
           streamContent = modelCall.streamContent;
+          recordModelSuccess(userId, agentId, modelSelectionId);
         } catch (err) {
           console.error(`[Engine] Model call failed (${model}):`, err.message);
+          recordModelFailure(userId, agentId, modelSelectionId, err);
           const fallbackModelId = retryForFallback
             ? await getFailureFallbackModelId(
               userId,
@@ -1561,6 +1576,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             response = fallbackCall.response;
             responseModel = fallbackCall.responseModel;
             streamContent = fallbackCall.streamContent;
+            recordModelSuccess(userId, agentId, modelSelectionId);
           } else {
             throw err;
           }

package/server/services/ai/model_failure_cache.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const DEFAULT_COOLDOWN_MS = 15 * 60 * 1000;
+const failures = new Map();
+
+function cacheKey(userId, agentId, modelSelectionId) {
+  return [
+    String(userId ?? ''),
+    String(agentId ?? 'main'),
+    String(modelSelectionId || '').trim(),
+  ].join(':');
+}
+
+function readCooldownMs() {
+  const configured = Number(process.env.NEOAGENT_MODEL_NOT_FOUND_COOLDOWN_MS);
+  if (!Number.isFinite(configured)) return DEFAULT_COOLDOWN_MS;
+  return Math.max(1_000, Math.min(configured, 24 * 60 * 60 * 1000));
+}
+
+function isPermanentModelFailure(error) {
+  const status = Number(
+    error?.status
+    ?? error?.statusCode
+    ?? error?.response?.status,
+  );
+  if (status === 404) return true;
+  return /\b404\b.*\b(model|nim|provider|request)\b|\b(model|nim)\b.*\b404\b/i
+    .test(String(error?.message || ''));
+}
+
+function recordModelFailure(userId, agentId, modelSelectionId, error, now = Date.now()) {
+  const modelId = String(modelSelectionId || '').trim();
+  if (!modelId || !isPermanentModelFailure(error)) return false;
+  failures.set(cacheKey(userId, agentId, modelId), {
+    expiresAt: now + readCooldownMs(),
+  });
+  return true;
+}
+
+function recordModelSuccess(userId, agentId, modelSelectionId) {
+  const modelId = String(modelSelectionId || '').trim();
+  if (!modelId) return false;
+  return failures.delete(cacheKey(userId, agentId, modelId));
+}
+
+function isModelCoolingDown(userId, agentId, modelSelectionId, now = Date.now()) {
+  const modelId = String(modelSelectionId || '').trim();
+  if (!modelId) return false;
+  const key = cacheKey(userId, agentId, modelId);
+  const entry = failures.get(key);
+  if (!entry) return false;
+  if (entry.expiresAt <= now) {
+    failures.delete(key);
+    return false;
+  }
+  return true;
+}
+
+function clearModelFailureCache() {
+  failures.clear();
+}
+
+module.exports = {
+  clearModelFailureCache,
+  isModelCoolingDown,
+  isPermanentModelFailure,
+  recordModelFailure,
+  recordModelSuccess,
+};

package/server/services/ai/models.js

@@ -264,7 +264,7 @@ async function getProviderHealthCatalog(userId, agentId = null, options = {}) {
         let statusLabel = provider.statusLabel;
         let availabilityReason = provider.availabilityReason;
 
-        if (provider.id === 'ollama' && provider.enabled) {
+        if (provider.id === 'ollama' && provider.enabled && options.probeLocal !== false) {
             const probe = await probeOllama(
                 provider.baseUrl || AI_PROVIDER_DEFINITIONS.ollama.defaultBaseUrl,
                 1500,

package/server/services/ai/provider_selector.js

@@ -7,6 +7,7 @@ const {
   normalizeModelSelections,
   resolveModelSelection,
 } = require('./model_identity');
+const { isModelCoolingDown } = require('./model_failure_cache');
 
 function buildSelection(model, userId, providerConfig) {
   return {
@@ -30,12 +31,29 @@ async function getProviderForUser(
     signal: providerConfig.signal,
   });
   const selectableModels = models.filter((model) => model.available !== false);
+  const readyModels = selectableModels.filter(
+    (model) => !isModelCoolingDown(userId, agentId, model.id),
+  );
 
   if (modelOverride && typeof modelOverride === 'string') {
     const requested = resolveModelSelection(selectableModels, modelOverride);
     if (!requested) {
       throw new Error(`Requested model '${modelOverride.trim()}' is not available.`);
     }
+    if (isModelCoolingDown(userId, agentId, requested.id) && readyModels.length > 0) {
+      const configuredFallback = resolveModelSelection(
+        readyModels,
+        aiSettings.fallback_model_id,
+      );
+      const fallback = configuredFallback
+        || readyModels.find((model) => model.provider !== requested.provider)
+        || readyModels[0];
+      providerConfig.onStatus?.({
+        phase: 'model_fallback',
+        message: `Skipping recently unavailable model ${requested.id}; using ${fallback.id}.`,
+      });
+      return buildSelection(fallback, userId, providerConfig);
+    }
     return buildSelection(requested, userId, providerConfig);
   }
 
@@ -43,9 +61,35 @@ async function getProviderForUser(
     ? aiSettings.enabled_models.map((id) => String(id).trim()).filter(Boolean)
     : [];
   const enabledIds = normalizeModelSelections(selectableModels, configuredEnabledIds);
-  const availableModels = configuredEnabledIds.length > 0
-    ? selectableModels.filter((model) => enabledIds.includes(model.id))
-    : selectableModels;
+  let availableModels = configuredEnabledIds.length > 0
+    ? readyModels.filter((model) => enabledIds.includes(model.id))
+    : readyModels;
+
+  if (
+    availableModels.length === 0
+    && configuredEnabledIds.length > 0
+    && enabledIds.length > 0
+  ) {
+    const configuredFallback = resolveModelSelection(
+      readyModels,
+      aiSettings.fallback_model_id,
+    );
+    if (configuredFallback) {
+      providerConfig.onStatus?.({
+        phase: 'model_fallback',
+        message: `Enabled models are temporarily unavailable; using ${configuredFallback.id}.`,
+      });
+      availableModels = [configuredFallback];
+    }
+  }
+
+  // If every configured model is cooling down and there is no alternative,
+  // allow one retry instead of making the installation permanently unavailable.
+  if (availableModels.length === 0 && readyModels.length === 0) {
+    availableModels = configuredEnabledIds.length > 0
+      ? selectableModels.filter((model) => enabledIds.includes(model.id))
+      : selectableModels;
+  }
 
   if (availableModels.length === 0) {
     const message = configuredEnabledIds.length > 0
@@ -64,6 +108,17 @@ async function getProviderForUser(
   let selectedModel = fallbackModel;
   if (userSelectedDefault !== 'auto') {
     selectedModel = resolveModelSelection(availableModels, userSelectedDefault) || fallbackModel;
+    const configuredDefault = resolveModelSelection(selectableModels, userSelectedDefault);
+    if (
+      configuredDefault
+      && configuredDefault.id !== selectedModel.id
+      && isModelCoolingDown(userId, agentId, configuredDefault.id)
+    ) {
+      providerConfig.onStatus?.({
+        phase: 'model_fallback',
+        message: `Skipping recently unavailable model ${configuredDefault.id}; using ${selectedModel.id}.`,
+      });
+    }
   } else {
     const selectionHint = providerConfig.selectionHint && typeof providerConfig.selectionHint === 'object'
       ? providerConfig.selectionHint

package/server/services/ai/providers/google.js

@@ -94,7 +94,9 @@ class GoogleProvider extends BaseProvider {
       }
       if (msg.role === 'tool') {
         history.push({
-          role: 'function',
+          // Gemini chat history only accepts user/model roles. Tool results are
+          // represented as functionResponse parts on a user turn.
+          role: 'user',
           parts: [{
             functionResponse: {
               name: msg.name || 'tool',
@@ -147,6 +149,18 @@ class GoogleProvider extends BaseProvider {
       normalizedHistory.push({ role: currentRole, parts: currentParts });
     }
 
+    // Structured helpers can consist entirely of system instructions. Gemini's
+    // chat API still requires a user turn to trigger generation.
+    if (
+      normalizedHistory.length === 0
+      || normalizedHistory[normalizedHistory.length - 1].role === 'model'
+    ) {
+      normalizedHistory.push({
+        role: 'user',
+        parts: [{ text: 'Provide the requested response using the system instructions.' }]
+      });
+    }
+
     if (normalizedHistory.length > 0 && normalizedHistory[0].role !== 'user') {
       normalizedHistory.unshift({
         role: 'user',

package/server/services/runtime/docker-vm-manager.js

@@ -306,6 +306,15 @@ class DockerVMManager {
     return Boolean(session && isContainerRunning(session.containerId));
   }
 
+  // A side-effect-free snapshot for request-path capability reporting. Unlike
+  // hasVm(), this deliberately avoids a synchronous `docker inspect`, which can
+  // block the Node event loop. Tool execution still calls ensureVm() and performs
+  // the authoritative liveness check before using a tracked session.
+  hasTrackedVm(userId) {
+    const key = String(userId || '').trim();
+    return Boolean(key && this.instances.has(key));
+  }
+
   // Used by validation.js — cached to avoid docker calls on every status poll.
   getReadiness() {
     const now = Date.now();

package/server/services/runtime/guest_bootstrap.js

@@ -13,6 +13,8 @@ const GUEST_PAYLOAD_PROFILES = Object.freeze({
     { source: 'runtime/paths.js', target: 'runtime/paths.js' },
     { source: 'server/guest_agent.js', target: 'server/guest_agent.js' },
     { source: 'server/services/browser', target: 'server/services/browser' },
+    { source: 'server/services/android/process.js', target: 'server/services/android/process.js' },
+    { source: 'server/utils/cloud-security.js', target: 'server/utils/cloud-security.js' },
   ],
   cli: [
     { source: 'server/guest-agent.cli.package.json', target: 'package.json' },
@@ -28,6 +30,8 @@ const GUEST_PAYLOAD_PROFILES = Object.freeze({
     { source: 'server/guest_agent.js', target: 'server/guest_agent.js' },
     { source: 'server/services/cli', target: 'server/services/cli' },
     { source: 'server/services/browser', target: 'server/services/browser' },
+    { source: 'server/services/android/process.js', target: 'server/services/android/process.js' },
+    { source: 'server/utils/cloud-security.js', target: 'server/utils/cloud-security.js' },
   ],
   android: [
     { source: 'server/guest-agent.android.package.json', target: 'package.json' },
@@ -36,6 +40,9 @@ const GUEST_PAYLOAD_PROFILES = Object.freeze({
     { source: 'server/guest_agent.js', target: 'server/guest_agent.js' },
     { source: 'server/services/cli', target: 'server/services/cli' },
     { source: 'server/services/android', target: 'server/services/android' },
+    { source: 'server/utils/abort.js', target: 'server/utils/abort.js' },
+    { source: 'server/utils/cloud-security.js', target: 'server/utils/cloud-security.js' },
+    { source: 'server/utils/image_payload.js', target: 'server/utils/image_payload.js' },
   ],
 });
 

package/server/services/runtime/guest_image.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { spawnSync } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const { DATA_DIR } = require('../../../runtime/paths');
 const { stageGuestPayload, normalizeRuntimeProfile } = require('./guest_bootstrap');
 
@@ -105,6 +105,34 @@ function dockerAvailable() {
   return !result.error && result.status === 0;
 }
 
+function runDockerCommand(args, options = {}) {
+  const timeoutMs = Number(options.timeout || BUILD_TIMEOUT_MS);
+  const spawnImpl = options.spawnImpl || spawn;
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl('docker', args, {
+      stdio: options.stdio || ['ignore', 'inherit', 'inherit'],
+      windowsHide: true,
+    });
+    let settled = false;
+    const finish = (error, status = null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (error) reject(error);
+      else resolve(status);
+    };
+    const timeout = setTimeout(() => {
+      const error = new Error(`docker ${args[0]} timed out after ${timeoutMs}ms`);
+      error.code = 'DOCKER_COMMAND_TIMEOUT';
+      try { child.kill('SIGKILL'); } catch {}
+      finish(error);
+    }, timeoutMs);
+    timeout.unref?.();
+    child.once('error', (error) => finish(error));
+    child.once('close', (status) => finish(null, status));
+  });
+}
+
 // Builds and caches the per-profile guest-agent Docker image. The image bakes in
 // the guest agent, its dependencies, and (for browser_cli) the Chromium browser,
 // so containers start the agent directly with no runtime installation step.
@@ -166,15 +194,16 @@ class GuestImageBuilder {
   async #build(tag) {
     console.log(`[GuestImage:${this.profile}] Building guest image ${tag} (one-time; downloads browser + deps)…`);
     const started = Date.now();
-    const result = docker(['build', '-t', tag, this.contextDir], {
-      timeout: BUILD_TIMEOUT_MS,
-      stdio: ['ignore', 'inherit', 'inherit'],
-    });
-    if (result.error) {
-      throw new Error(`Guest image build failed to start: ${result.error.message}`);
+    let status;
+    try {
+      status = await runDockerCommand(['build', '-t', tag, this.contextDir], {
+        timeout: BUILD_TIMEOUT_MS,
+      });
+    } catch (error) {
+      throw new Error(`Guest image build failed: ${error.message}`, { cause: error });
     }
-    if (result.status !== 0) {
-      throw new Error(`Guest image build for ${tag} exited with status ${result.status}`);
+    if (status !== 0) {
+      throw new Error(`Guest image build for ${tag} exited with status ${status}`);
     }
     this.#cachedBuiltAt = Date.now();
     console.log(`[GuestImage:${this.profile}] Built ${tag} in ${Math.round((Date.now() - started) / 1000)}s`);
@@ -185,5 +214,6 @@ class GuestImageBuilder {
 module.exports = {
   GuestImageBuilder,
   dockerAvailable,
+  runDockerCommand,
   BASE_IMAGE,
 };

package/server/services/runtime/manager.js

@@ -87,6 +87,41 @@ class RuntimeManager {
     );
   }
 
+  getCapabilitySnapshot(userId) {
+    const settings = this.getSettings(userId) || {};
+    const key = String(userId || '').trim();
+    const extensionConnected = this.hasActiveExtensionBrowser(userId);
+    const androidController = key && this.androidControllers instanceof Map
+      ? this.androidControllers.get(key)
+      : null;
+    let androidStatus = null;
+    if (androidController && typeof androidController.getStatusSync === 'function') {
+      try {
+        androidStatus = androidController.getStatusSync();
+      } catch {
+        androidStatus = null;
+      }
+    }
+
+    return {
+      browser: {
+        preferredBackend: settings.browser_backend,
+        activeBackend: extensionConnected ? 'extension' : 'vm',
+        extensionConnected,
+        vmInitialized: Boolean(
+          this.browserBackend?.vmManager?.hasTrackedVm?.(userId),
+        ),
+      },
+      android: {
+        initialized: Boolean(androidController),
+        status: androidStatus,
+      },
+      desktop: {
+        connected: this.hasActiveDesktopCompanion(userId),
+      },
+    };
+  }
+
   resolveBackend(userId, requested) {
     void userId;
     return requested === 'browser' ? this.browserBackend : this.cliBackend;