oomi-ai 0.2.41 → 0.2.45

package/bin/oomi-ai.js

@@ -14,35 +14,37 @@ import { startPersonaJobPoller } from '../lib/personaJobPoller.js';
 import { startPersonaRuntimeSupervisor } from '../lib/personaRuntimeSupervisor.js';
 import { executePersonaJob, extractPersonaJobPayload } from '../lib/personaJobExecutor.js';
 import { inferSpokenMetadataFromContent, normalizeSpokenMetadata } from '../lib/spokenMetadata.js';
-import {
-  resolveOpenclawBridgeLiveLogPath,
-  resolveOpenclawBridgeLockPath,
-  resolveOpenclawBridgeStatePath,
-  resolveOpenclawBridgeStatusPath,
-  resolveOpenclawConfigCandidates,
-  resolveOpenclawHome,
-  resolveOpenclawIdentityPath,
-  resolveOpenclawProfilePath,
-  resolveOpenclawSkillsDir,
-  resolveOpenclawUpdateStatePath,
-  resolveOpenclawWorkspaceRoot,
-} from '../lib/openclawPaths.js';
+import {
+  resolveOpenclawBridgeLiveLogPath,
+  resolveOpenclawBridgeLockPath,
+  resolveOpenclawBridgeStatePath,
+  resolveOpenclawBridgeStatusPath,
+  resolveOpenclawConfigCandidates,
+  resolveOpenclawHome,
+  resolveOpenclawIdentityPath,
+  resolveOpenclawLegacyPersonasDir,
+  resolveOpenclawProfilePath,
+  resolveOpenclawSkillsDir,
+  resolveOpenclawUpdateStatePath,
+  resolveOpenclawWorkspaceRoot,
+} from '../lib/openclawPaths.js';
 import {
   applyOpenclawProfile,
   buildOomiDevLocalProfile,
   readOpenclawProfile,
   writeOpenclawProfile,
 } from '../lib/openclawProfile.js';
-import {
-  buildLocalPersonaRuntime,
-  defaultPersonaWorkspaceRoot,
-  installPersonaWorkspace,
-  isPersonaWorkspaceProcessRunning,
-  resolvePersonaDevCommand,
-  startPersonaWorkspace,
-  stopPersonaWorkspace,
-  waitForPersonaRuntime,
-} from '../lib/personaRuntimeProcess.js';
+import {
+  buildLocalPersonaRuntime,
+  defaultPersonaWorkspaceRoot,
+  installPersonaWorkspace,
+  isPersonaWorkspaceProcessRunning,
+  resolvePersonaHealthPath,
+  resolvePersonaDevCommand,
+  startPersonaWorkspace,
+  stopPersonaWorkspace,
+  waitForPersonaRuntime,
+} from '../lib/personaRuntimeProcess.js';
 import {
   destroyManagedPersonaRuntime,
   getManagedPersonaRuntimeStatus,
@@ -50,13 +52,17 @@ import {
   slugifyPersonaName,
   stopManagedPersonaRuntime,
 } from '../lib/personaRuntimeManager.js';
+import {
+  readPersonaRuntimeState,
+  resolvePersonaWorkspacePath,
+} from '../lib/personaRuntimeRegistry.js';
 import { startLocalGatewayAgentServer } from '../lib/openclawDevGateway.js';
 import { ensureSessionBridge, flushSessionQueue, flushWaitingForConnect, forwardFrameToSession } from './sessionBridgeState.js';
 
 const MARKER_START = '<oomi-agent-instructions>';
 const MARKER_END = '</oomi-agent-instructions>';
 
-const PACKAGE_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const UPDATE_STATE_FILE = resolveOpenclawUpdateStatePath();
 const DEFAULT_UPDATE_CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
 const DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 1200;
@@ -231,10 +237,12 @@ Commands:
     Replay an assistant chat.final frame through spoken-metadata normalization.
   openclaw debug tts-pipeline
     Replay an assistant chat.final through local backend voice handling.
-  openclaw debug local-gateway-agent
-    Run a tiny local OpenClaw gateway/agent for Docker dev testing.
-  openclaw debug persona-runtime
-    Scaffold, launch, and stop a managed persona runtime locally.
+  openclaw debug local-gateway-agent
+    Run a tiny local OpenClaw gateway/agent for Docker dev testing.
+  openclaw debug persona-runtime
+    Scaffold, launch, and stop a managed persona runtime locally.
+  openclaw refresh
+    Restart the bridge and running managed persona runtimes after an oomi-ai update.
 
   openclaw pair
     Pair this OpenClaw host with Oomi and start bridge (single command).
@@ -320,18 +328,20 @@ Common flags:
   --out PATH             Output directory for scaffolded persona app
   --template-version V   Scaffold template version (default: v1)
   --force                Overwrite files in an existing output directory
-  --force-install        Reinstall persona workspace dependencies before launch
-  --no-sync              Skip backend sync (for create)
-  --no-create            Do not create a managed persona record if one does not already exist
+  --force-install        Reinstall persona workspace dependencies before launch
+  --include-stopped      Relaunch managed persona runtimes even if not currently marked running
+  --no-sync              Skip backend sync (for create)
+  --no-create            Do not create a managed persona record if one does not already exist
   --local-port N         Local runtime port for persona runtime callbacks
   --endpoint URL         Runtime endpoint for persona runtime callbacks
   --entry-url URL        Viewer URL to register for a launched persona runtime
-  --health-path PATH     Runtime health path (default: /oomi.health.json)
+  --health-path PATH     Runtime health path override (default: workspace-specific)
   --healthcheck-url URL  Runtime healthcheck URL override
-  --transport TEXT       Runtime transport label (default: local, relay when --entry-url is used)
+  --transport TEXT       Runtime transport label (default: local, relay when --entry-url is used)
   --workspace-root PATH  Persona workspace root (default: OPENCLAW_WORKSPACE/personas)
-  --restart              Restart an existing managed persona runtime before launch
-  --started-at ISO       Start timestamp override
+  --restart              Restart an existing managed persona runtime before launch
+  --skip-version-check   Skip checking npm for the latest oomi-ai version during refresh
+  --started-at ISO       Start timestamp override
   --observed-at ISO      Heartbeat timestamp override
   --completed-at ISO     Completion timestamp override
   --code TEXT            Error code for fail callbacks
@@ -829,14 +839,91 @@ function resolvePersonaEntryUrl(flags = {}) {
   return String(flags['entry-url'] || '').trim();
 }
 
-function resolvePersonaLaunchTransport(flags = {}) {
-  const explicitTransport = String(flags.transport || '').trim();
-  if (explicitTransport) {
-    return explicitTransport;
-  }
-
-  return resolvePersonaEntryUrl(flags) ? 'relay' : 'local';
-}
+function resolvePersonaLaunchTransport(flags = {}) {
+  const explicitTransport = String(flags.transport || '').trim();
+  if (explicitTransport) {
+    return explicitTransport;
+  }
+
+  return resolvePersonaEntryUrl(flags) ? 'relay' : 'local';
+}
+
+function listPersonaWorkspaceRoots(workspaceRoot = defaultPersonaWorkspaceRoot()) {
+  const roots = [
+    String(workspaceRoot || '').trim(),
+    String(resolveOpenclawLegacyPersonasDir() || '').trim(),
+  ].filter(Boolean);
+
+  const deduped = [];
+  const seen = new Set();
+  for (const root of roots) {
+    const resolved = path.resolve(root);
+    if (seen.has(resolved) || !fs.existsSync(resolved)) {
+      continue;
+    }
+    seen.add(resolved);
+    deduped.push(resolved);
+  }
+
+  return deduped;
+}
+
+function collectManagedPersonaRefreshTargets({
+  workspaceRoot = defaultPersonaWorkspaceRoot(),
+  includeStopped = false,
+} = {}) {
+  const targets = [];
+  const seenWorkspacePaths = new Set();
+  const seenSlugs = new Set();
+
+  for (const root of listPersonaWorkspaceRoots(workspaceRoot)) {
+    const entries = fs.readdirSync(root, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+        continue;
+      }
+
+      const workspacePath = path.join(root, entry.name);
+      let dedupeKey = workspacePath;
+      try {
+        dedupeKey = fs.realpathSync(workspacePath);
+      } catch {
+        dedupeKey = path.resolve(workspacePath);
+      }
+      if (seenWorkspacePaths.has(dedupeKey)) {
+        continue;
+      }
+      seenWorkspacePaths.add(dedupeKey);
+
+      const state = readPersonaRuntimeState(workspacePath);
+      if (!state || Object.keys(state).length === 0) {
+        continue;
+      }
+
+      const slug = String(state.slug || entry.name || '').trim();
+      if (!slug || seenSlugs.has(slug)) {
+        continue;
+      }
+
+      const pid = normalizePid(state.pid);
+      const processRunning = pid ? isPersonaWorkspaceProcessRunning(pid) : false;
+      const runtimeStatus = String(state.status || '').trim().toLowerCase();
+      if (!includeStopped && !processRunning && runtimeStatus !== 'running') {
+        continue;
+      }
+
+      seenSlugs.add(slug);
+      targets.push({
+        slug,
+        workspacePath,
+        state,
+        processRunning,
+      });
+    }
+  }
+
+  return targets.sort((a, b) => a.slug.localeCompare(b.slug));
+}
 
 async function findExistingManagedPersona(client, slug) {
   try {
@@ -1114,31 +1201,81 @@ async function runManagedPersonaJobExecution({
   }
 }
 
-function resolvePersonaRuntimeInput(flags = {}, defaults = {}) {
-  const localPort = parseOptionalPositiveInteger(flags['local-port'] || flags.localPort || defaults.localPort);
-  const endpoint = String(flags.endpoint || defaults.endpoint || '').trim();
-  const healthPath = String(flags['health-path'] || defaults.healthPath || '/oomi.health.json').trim() || '/oomi.health.json';
-  const healthcheckUrl = String(flags['healthcheck-url'] || defaults.healthcheckUrl || '').trim();
-  const transport = String(flags.transport || defaults.transport || 'local').trim() || 'local';
-
-  if (endpoint) {
-    return {
-      endpoint,
-      healthcheckUrl: healthcheckUrl || `${endpoint.replace(/\/$/, '')}${healthPath}`,
+function resolvePersonaRuntimeWorkspacePath({
+  slug = '',
+  workspacePath = '',
+  workspaceRoot = '',
+} = {}) {
+  const explicitWorkspacePath = String(workspacePath || '').trim();
+  if (explicitWorkspacePath) {
+    return path.resolve(explicitWorkspacePath);
+  }
+
+  const safeSlug = String(slug || '').trim();
+  if (!safeSlug) {
+    return '';
+  }
+
+  const safeWorkspaceRoot = String(workspaceRoot || defaultPersonaWorkspaceRoot()).trim();
+  if (!safeWorkspaceRoot) {
+    return '';
+  }
+
+  return resolvePersonaWorkspacePath({
+    workspaceRoot: safeWorkspaceRoot,
+    slug: safeSlug,
+  });
+}
+
+function resolvePersonaRuntimeInput(flags = {}, defaults = {}, options = {}) {
+  const localPort = parseOptionalPositiveInteger(flags['local-port'] || flags.localPort || defaults.localPort);
+  const endpoint = String(flags.endpoint || defaults.endpoint || '').trim();
+  const explicitHealthPath = String(flags['health-path'] || defaults.healthPath || '').trim();
+  const healthcheckUrl = String(flags['healthcheck-url'] || defaults.healthcheckUrl || '').trim();
+  const transport = String(flags.transport || defaults.transport || 'local').trim() || 'local';
+  const workspacePath = resolvePersonaRuntimeWorkspacePath({
+    slug: options.slug || defaults.slug || flags.slug,
+    workspacePath:
+      options.workspacePath ||
+      defaults.workspacePath ||
+      flags['workspace-path'] ||
+      flags.workspacePath,
+    workspaceRoot:
+      options.workspaceRoot ||
+      defaults.workspaceRoot ||
+      flags['workspace-root'] ||
+      flags.workspaceRoot,
+  });
+  const healthPath = explicitHealthPath ||
+    resolvePersonaHealthPath({
+      workspacePath,
+      fallback: '/oomi.health.json',
+    });
+
+  if (endpoint) {
+    return {
+      endpoint,
+      healthcheckUrl: healthcheckUrl || `${endpoint.replace(/\/$/, '')}${healthPath}`,
       localPort,
       transport,
     };
   }
 
-  if (!localPort) {
-    throw new Error('Runtime endpoint or local port is required.');
-  }
-
-  return buildLocalPersonaRuntime({
-    localPort,
-    healthPath,
-  });
-}
+  if (!localPort) {
+    throw new Error('Runtime endpoint or local port is required.');
+  }
+
+  const runtime = buildLocalPersonaRuntime({
+    localPort,
+    healthPath,
+  });
+
+  return {
+    ...runtime,
+    endpoint: runtime.reachableEndpoint || runtime.endpoint,
+    localEndpoint: runtime.endpoint,
+  };
+}
 
 function parseIsoTimestamp(rawValue, label) {
   const value = String(rawValue || '').trim();
@@ -1175,12 +1312,19 @@ function printStructuredResult(result, asJson = false) {
   }
 }
 
-async function handlePersonaRuntimeRegisterCommand(slug, flags = {}) {
-  const client = createCliPersonaApiClient(flags);
-  const runtime = resolvePersonaRuntimeInput(flags);
-  const payload = await client.registerRuntime({
-    slug,
-    endpoint: runtime.endpoint,
+async function handlePersonaRuntimeRegisterCommand(slug, flags = {}) {
+  const client = createCliPersonaApiClient(flags);
+  const runtime = resolvePersonaRuntimeInput(
+    flags,
+    {},
+    {
+      slug,
+      workspaceRoot: resolvePersonaWorkspaceRoot(flags),
+    },
+  );
+  const payload = await client.registerRuntime({
+    slug,
+    endpoint: runtime.endpoint,
     healthcheckUrl: runtime.healthcheckUrl,
     localPort: runtime.localPort,
     transport: runtime.transport,
@@ -1189,12 +1333,19 @@ async function handlePersonaRuntimeRegisterCommand(slug, flags = {}) {
   printStructuredResult(payload, isTruthyFlag(flags.json));
 }
 
-async function handlePersonaHeartbeatCommand(slug, flags = {}) {
-  const client = createCliPersonaApiClient(flags);
-  const runtime = resolvePersonaRuntimeInput(flags);
-  const payload = await client.heartbeatRuntime({
-    slug,
-    endpoint: runtime.endpoint,
+async function handlePersonaHeartbeatCommand(slug, flags = {}) {
+  const client = createCliPersonaApiClient(flags);
+  const runtime = resolvePersonaRuntimeInput(
+    flags,
+    {},
+    {
+      slug,
+      workspaceRoot: resolvePersonaWorkspaceRoot(flags),
+    },
+  );
+  const payload = await client.heartbeatRuntime({
+    slug,
+    endpoint: runtime.endpoint,
     healthcheckUrl: runtime.healthcheckUrl,
     localPort: runtime.localPort,
     transport: runtime.transport,
@@ -1231,16 +1382,22 @@ async function handlePersonaJobStartCommand(jobId, flags = {}) {
   printStructuredResult(payload, isTruthyFlag(flags.json));
 }
 
-async function handlePersonaJobSucceedCommand(jobId, flags = {}) {
-  const client = createCliPersonaApiClient(flags);
-  const runtime = resolvePersonaRuntimeInput(flags);
-  const workspacePath = String(flags['workspace-path'] || flags.workspacePath || '').trim();
-  if (!workspacePath) {
-    throw new Error('Workspace path is required. Use --workspace-path.');
-  }
-
-  const payload = await client.succeedJob({
-    jobId,
+async function handlePersonaJobSucceedCommand(jobId, flags = {}) {
+  const client = createCliPersonaApiClient(flags);
+  const workspacePath = String(flags['workspace-path'] || flags.workspacePath || '').trim();
+  if (!workspacePath) {
+    throw new Error('Workspace path is required. Use --workspace-path.');
+  }
+  const runtime = resolvePersonaRuntimeInput(
+    flags,
+    {},
+    {
+      workspacePath,
+    },
+  );
+
+  const payload = await client.succeedJob({
+    jobId,
     workspacePath,
     localPort: runtime.localPort,
     transport: runtime.transport,
@@ -1408,6 +1565,162 @@ async function handlePersonaDeleteCommand(slug, flags = {}) {
   });
   printStructuredResult(result, isTruthyFlag(flags.json));
 }
+
+async function restartManagedPersonaRefreshTargets(flags = {}) {
+  const workspaceRoot = resolvePersonaWorkspaceRoot(flags);
+  const targets = collectManagedPersonaRefreshTargets({
+    workspaceRoot,
+    includeStopped: isTruthyFlag(flags['include-stopped']),
+  });
+  const results = [];
+
+  let client = null;
+  let registrationError = '';
+  try {
+    client = createCliPersonaApiClient(flags);
+  } catch (error) {
+    registrationError = error instanceof Error ? error.message : String(error);
+  }
+
+  for (const target of targets) {
+    const state = target.state && typeof target.state === 'object' ? target.state : {};
+    const launchResult = await launchManagedPersonaRuntime({
+      slug: target.slug,
+      name: String(state.name || target.slug).trim() || target.slug,
+      description: String(state.description || state.name || target.slug).trim() || target.slug,
+      workspaceRoot,
+      templateVersion: String(state.templateVersion || 'v1').trim() || 'v1',
+      forceInstall: isTruthyFlag(flags['force-install']),
+      restart: true,
+      logFilePath: String(state.logFilePath || '').trim(),
+      entryUrl: '',
+      transport: 'local',
+    });
+
+    let registration = null;
+    if (client) {
+      try {
+        registration = await client.registerRuntime({
+          slug: launchResult.slug,
+          endpoint: launchResult.runtime.endpoint,
+          healthcheckUrl: launchResult.runtime.healthcheckUrl,
+          localPort: launchResult.runtime.localPort,
+          transport: launchResult.runtime.transport,
+          startedAt: new Date().toISOString(),
+        });
+      } catch (error) {
+        registration = {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    results.push({
+      slug: launchResult.slug,
+      workspacePath: launchResult.workspacePath,
+      localPort: launchResult.runtime.localPort,
+      endpoint: launchResult.runtime.endpoint,
+      healthcheckUrl: launchResult.runtime.healthcheckUrl,
+      registration,
+    });
+  }
+
+  return {
+    workspaceRoot,
+    targets,
+    results,
+    registrationError,
+  };
+}
+
+async function refreshBridgeForUpdate(flags = {}) {
+  if (process.platform === 'darwin') {
+    const launchdStatus = readBridgeLaunchdStatus();
+    if (launchdStatus.installed) {
+      await stopBridgeLaunchdService();
+      startBridgeLaunchdService();
+      incrementBridgeMetric('bridge_restart_count');
+      return {
+        restarted: true,
+        mode: 'service',
+        target: launchdStatus.target,
+      };
+    }
+  }
+
+  const running = findRunningBridgeProcess();
+  if (!running) {
+    return {
+      restarted: false,
+      mode: 'process',
+    };
+  }
+
+  const stopResult = await stopBridgeProcesses();
+  if (Array.isArray(stopResult.stillAlive) && stopResult.stillAlive.length > 0) {
+    throw new Error(`Failed to stop bridge processes: ${stopResult.stillAlive.join(', ')}`);
+  }
+
+  const detachedResult = startBridgeDetachedProcess(flags);
+  incrementBridgeMetric('bridge_restart_count');
+  return {
+    restarted: true,
+    mode: 'process',
+    pid: detachedResult.pid,
+    alreadyRunning: Boolean(detachedResult.alreadyRunning),
+  };
+}
+
+async function handleOpenclawRefreshCommand(flags = {}) {
+  const currentVersion = currentPackageVersion();
+  let latestVersion = '';
+  if (!isTruthyFlag(flags['skip-version-check'])) {
+    latestVersion = await fetchLatestPublishedVersion('oomi-ai');
+    if (latestVersion && compareVersions(currentVersion, latestVersion) < 0) {
+      throw new Error(
+        `Installed oomi-ai ${currentVersion} is behind npm ${latestVersion}. Update first, then rerun: oomi openclaw refresh`
+      );
+    }
+  }
+
+  const personaRefresh = await restartManagedPersonaRefreshTargets(flags);
+  const bridgeRefresh = await refreshBridgeForUpdate(flags);
+  const payload = {
+    ok: true,
+    currentVersion,
+    latestVersion: latestVersion || currentVersion,
+    personas: {
+      discovered: personaRefresh.targets.length,
+      restarted: personaRefresh.results.length,
+      registrationError: personaRefresh.registrationError || null,
+      results: personaRefresh.results,
+    },
+    bridge: bridgeRefresh,
+  };
+
+  if (isTruthyFlag(flags.json)) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(`Oomi refresh complete (${payload.currentVersion})`);
+  console.log(`Personas restarted: ${payload.personas.restarted}/${payload.personas.discovered}`);
+  if (payload.personas.registrationError) {
+    console.log(`Backend registration skipped: ${payload.personas.registrationError}`);
+  }
+  payload.personas.results.forEach((result) => {
+    console.log(`- ${result.slug}: ${result.endpoint}`);
+    if (result.registration && result.registration.ok === false) {
+      console.log(`  registration: ${result.registration.error}`);
+    }
+  });
+  if (payload.bridge.restarted) {
+    console.log(`Bridge restarted (${payload.bridge.mode}).`);
+  } else {
+    console.log('Bridge not running; no restart performed.');
+  }
+}
 
 function resolveOpenclawConfigPath() {
   const candidates = resolveOpenclawConfigCandidates();
@@ -5339,15 +5652,20 @@ async function main() {
     return;
   }
 
-  if (command === 'openclaw' && subcommand === 'debug') {
-    await handleOpenclawDebugCommand(args.positionals[0], args.flags);
-    return;
-  }
-
-  if (command === 'personas' && subcommand === 'sync') {
-    await syncPersonas({ backendUrl: args.flags['backend-url'], root: args.flags.root });
-    return;
-  }
+  if (command === 'openclaw' && subcommand === 'debug') {
+    await handleOpenclawDebugCommand(args.positionals[0], args.flags);
+    return;
+  }
+
+  if (command === 'openclaw' && subcommand === 'refresh') {
+    await handleOpenclawRefreshCommand(args.flags);
+    return;
+  }
+
+  if (command === 'personas' && subcommand === 'sync') {
+    await syncPersonas({ backendUrl: args.flags['backend-url'], root: args.flags.root });
+    return;
+  }
 
   if (command === 'personas' && subcommand === 'create') {
     const id = args.positionals[0];
@@ -5504,8 +5822,10 @@ export {
   runBridgeCallbackSafely,
   extractGatewayRequestMeta,
   extractGatewayResponseMeta,
-  isServiceManagedBridgeStart,
-  isGatewayRunStartedFrame,
-  isBridgeWorkerCommand,
-  parsePositiveInteger,
-};
+  isServiceManagedBridgeStart,
+  isGatewayRunStartedFrame,
+  isBridgeWorkerCommand,
+  parsePositiveInteger,
+  collectManagedPersonaRefreshTargets,
+  resolvePersonaRuntimeInput,
+};

package/lib/personaRuntimeManager.js

@@ -8,6 +8,7 @@ import {
   defaultPersonaWorkspaceRoot,
   installPersonaWorkspace,
   isPersonaWorkspaceProcessRunning,
+  resolvePersonaHealthPath,
   resolvePersonaDevCommand,
   syncLegacyWebSpatialScaffoldFiles,
   syncVendoredWebSpatialPackages,
@@ -143,20 +144,12 @@ export function slugifyPersonaName(name) {
   return normalized;
 }
 
-function resolveHealthPath(workspacePath) {
-  const runtimeConfigPath = path.join(workspacePath, 'oomi.runtime.json');
-  if (!fs.existsSync(runtimeConfigPath)) {
-    return '/oomi.health.json';
-  }
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(runtimeConfigPath, 'utf8'));
-    const healthPath = trimString(parsed?.healthPath);
-    return healthPath || '/oomi.health.json';
-  } catch {
-    return '/oomi.health.json';
-  }
-}
+function resolveHealthPath(workspacePath) {
+  return resolvePersonaHealthPath({
+    workspacePath,
+    fallback: '/oomi.health.json',
+  });
+}
 
 function workspaceNeedsScaffold(workspacePath) {
   return !fs.existsSync(path.join(workspacePath, 'package.json'));
@@ -210,28 +203,32 @@ async function ensureWorkspaceInstall({
   return true;
 }
 
-function buildRuntimeRegistration({
-  localRuntime,
-  entryUrl,
-  transport,
-}) {
-  const safeEntryUrl = trimString(entryUrl);
-  if (safeEntryUrl) {
-    return {
-      endpoint: safeEntryUrl,
-      transport: trimString(transport) || 'relay',
-      healthcheckUrl: localRuntime.healthcheckUrl,
-      localPort: localRuntime.localPort,
-    };
-  }
-
-  return {
-    endpoint: localRuntime.endpoint,
-    transport: trimString(transport) || localRuntime.transport,
-    healthcheckUrl: localRuntime.healthcheckUrl,
-    localPort: localRuntime.localPort,
-  };
-}
+function buildRuntimeRegistration({
+  localRuntime,
+  entryUrl,
+  transport,
+}) {
+  const safeEntryUrl = trimString(entryUrl);
+  if (safeEntryUrl) {
+    return {
+      endpoint: safeEntryUrl,
+      transport: trimString(transport) || 'relay',
+      healthcheckUrl: localRuntime.healthcheckUrl,
+      localPort: localRuntime.localPort,
+      localEndpoint: localRuntime.endpoint,
+      reachableEndpoint: localRuntime.reachableEndpoint,
+    };
+  }
+
+  return {
+    endpoint: localRuntime.reachableEndpoint || localRuntime.endpoint,
+    transport: trimString(transport) || localRuntime.transport,
+    healthcheckUrl: localRuntime.healthcheckUrl,
+    localPort: localRuntime.localPort,
+    localEndpoint: localRuntime.endpoint,
+    reachableEndpoint: localRuntime.reachableEndpoint,
+  };
+}
 
 export async function launchManagedPersonaRuntime({
   slug,
@@ -266,19 +263,31 @@ export async function launchManagedPersonaRuntime({
     workspacePath,
     templateVersion,
   });
-  const installed = await ensureWorkspaceInstall({
-    workspacePath,
-    forceInstall,
-  });
-
-  const healthPath = scaffoldInfo.healthPath || resolveHealthPath(workspacePath);
-  const preferredPort = previousState.localPort || scaffoldInfo.defaultPort;
-
-  let reusingRunningProcess = false;
-  if (!restart && Number.isInteger(previousState.pid) && isPersonaWorkspaceProcessRunning(previousState.pid)) {
-    try {
-      await waitForPersonaRuntime({
-        healthcheckUrl: previousState.healthcheckUrl || buildLocalPersonaRuntime({
+  const installed = await ensureWorkspaceInstall({
+    workspacePath,
+    forceInstall,
+  });
+
+  const healthPath = resolveHealthPath(workspacePath);
+  const preferredPort = previousState.localPort || scaffoldInfo.defaultPort;
+  const expectedDevCommand = resolvePersonaDevCommand({
+    workspacePath,
+    localPort: preferredPort,
+  });
+
+  let reusingRunningProcess = false;
+  if (
+    !restart &&
+    Number.isInteger(previousState.pid) &&
+    isPersonaWorkspaceProcessRunning(previousState.pid, {
+      workspacePath,
+      expectedCommand: expectedDevCommand,
+      localPort: preferredPort,
+    })
+  ) {
+    try {
+      await waitForPersonaRuntime({
+        healthcheckUrl: previousState.healthcheckUrl || buildLocalPersonaRuntime({
           localPort: preferredPort,
           healthPath,
         }).healthcheckUrl,
@@ -326,24 +335,27 @@ export async function launchManagedPersonaRuntime({
     entryUrl,
     transport,
   });
-  const runtimeState = updatePersonaRuntimeState(workspacePath, {
+  const runtimeState = updatePersonaRuntimeState(workspacePath, {
     slug: safeSlug,
     name: safeName,
     description: safeDescription,
     workspacePath,
     templateVersion,
-    localPort: localRuntime.localPort,
-    localEndpoint: localRuntime.endpoint,
-    endpoint: registration.endpoint,
-    entryUrl: registration.endpoint,
+    localPort: localRuntime.localPort,
+    localEndpoint: localRuntime.endpoint,
+    reachableEndpoint: localRuntime.reachableEndpoint,
+    bindHost: localRuntime.bindHost,
+    reachableHost: localRuntime.reachableHost,
+    endpoint: registration.endpoint,
+    entryUrl: registration.endpoint,
     transport: registration.transport,
     healthcheckUrl: localRuntime.healthcheckUrl,
     pid: processInfo.pid,
     logFilePath: processInfo.logFilePath,
-    status: 'running',
-    lastStartedAt: new Date().toISOString(),
-    devCommand: resolvePersonaDevCommand({ workspacePath, localPort }),
-  });
+    status: 'running',
+    lastStartedAt: new Date().toISOString(),
+    devCommand: resolvePersonaDevCommand({ workspacePath, localPort }),
+  });
 
   return {
     ok: true,

package/lib/personaRuntimeProcess.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -29,12 +30,25 @@ const WEBSPATIAL_VENDOR_ROOT = path.join(
 );
 const VENDORED_WEBSPATIAL_CORE_SPEC = 'file:./vendor/webspatial/core-sdk';
 const VENDORED_WEBSPATIAL_REACT_SPEC = 'file:./vendor/webspatial/react-sdk';
+const WEBSPATIAL_RUNTIME_BASE_PATH = '/webspatial/avp';
 const WEBSPATIAL_TEMPLATE_DEV_DEPENDENCIES = [
   '@webspatial/builder',
   '@webspatial/platform-visionos',
   '@webspatial/vite-plugin',
 ];
 const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
+  {
+    relativePath: 'oomi.runtime.json',
+    shouldReplace: (content) =>
+      content.includes('"renderMode": "webspatial"') &&
+      content.includes('"healthPath": "/oomi.health.json"'),
+  },
+  {
+    relativePath: 'package.json',
+    shouldReplace: (content) =>
+      content.includes('vite --host 127.0.0.1 --port 4789') ||
+      content.includes('vite preview --host 127.0.0.1 --port 4789'),
+  },
   {
     relativePath: path.join('src', 'spatial.ts'),
     shouldReplace: (content) =>
@@ -198,15 +212,117 @@ function normalizePositiveInteger(value) {
   return Math.floor(parsed);
 }
 
-function resolvePersonaBindHost() {
+function isWildcardHost(host) {
+  const normalized = String(host || '').trim().toLowerCase();
+  return normalized === '0.0.0.0' || normalized === '::' || normalized === '[::]';
+}
+
+function isLoopbackHost(host) {
+  const normalized = String(host || '').trim().toLowerCase();
+  return normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1' || normalized === '[::1]';
+}
+
+function isPrivateIpv4(address) {
+  if (!/^\d+\.\d+\.\d+\.\d+$/u.test(address)) {
+    return false;
+  }
+
+  const [first, second] = address.split('.').map((segment) => Number(segment));
+  if (first === 10) return true;
+  if (first === 192 && second === 168) return true;
+  if (first === 172 && second >= 16 && second <= 31) return true;
+  return false;
+}
+
+function scorePersonaNetworkCandidate(candidate) {
+  let score = 0;
+  const name = String(candidate.name || '').toLowerCase();
+  const address = String(candidate.address || '');
+
+  if (isPrivateIpv4(address)) score += 40;
+  if (address.startsWith('192.168.')) score += 8;
+  if (address.startsWith('10.')) score += 6;
+  if (/ethernet|wi-?fi|wlan|en\d|eth\d/iu.test(name)) score += 12;
+  if (/hyper-v|vethernet|wsl|docker|vmware|virtualbox|tailscale|loopback|bridge/iu.test(name)) score -= 30;
+  if (address.startsWith('169.254.')) score -= 100;
+  return score;
+}
+
+function formatPersonaRuntimeHostForUrl(host) {
+  const safeHost = String(host || '').trim();
+  if (!safeHost) {
+    return '127.0.0.1';
+  }
+  if (safeHost.includes(':') && !safeHost.startsWith('[')) {
+    return `[${safeHost}]`;
+  }
+  return safeHost;
+}
+
+export function resolvePersonaBindHost() {
   const value = String(process.env.OOMI_PERSONA_BIND_HOST || '').trim();
-  return value || '127.0.0.1';
+  return value || '0.0.0.0';
+}
+
+export function resolvePersonaReachableHost({
+  bindHost = resolvePersonaBindHost(),
+  env = process.env,
+  networkInterfaces = os.networkInterfaces(),
+} = {}) {
+  const explicit = String(env.OOMI_PERSONA_PUBLIC_HOST || '').trim();
+  if (explicit) {
+    return explicit;
+  }
+
+  const safeBindHost = String(bindHost || '').trim();
+  if (safeBindHost && !isWildcardHost(safeBindHost) && !isLoopbackHost(safeBindHost)) {
+    return safeBindHost;
+  }
+
+  const candidates = [];
+  for (const [name, entries] of Object.entries(networkInterfaces || {})) {
+    for (const entry of Array.isArray(entries) ? entries : []) {
+      if (!entry || entry.internal || entry.family !== 'IPv4') {
+        continue;
+      }
+
+      const address = String(entry.address || '').trim();
+      if (!address || isLoopbackHost(address) || address.startsWith('169.254.')) {
+        continue;
+      }
+
+      candidates.push({
+        name,
+        address,
+      });
+    }
+  }
+
+  const winner = candidates
+    .sort((left, right) => scorePersonaNetworkCandidate(right) - scorePersonaNetworkCandidate(left))[0];
+
+  return winner?.address || '127.0.0.1';
 }
 
 function trimString(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
 
+function normalizePersonaHealthPath(healthPath, runtimeConfig = {}) {
+  const safeHealthPath = trimString(healthPath) || '/oomi.health.json';
+  const renderMode = trimString(runtimeConfig?.renderMode).toLowerCase();
+  if (renderMode !== 'webspatial') {
+    return safeHealthPath;
+  }
+
+  if (safeHealthPath.startsWith(`${WEBSPATIAL_RUNTIME_BASE_PATH}/`)) {
+    return safeHealthPath;
+  }
+
+  const normalizedSuffix = safeHealthPath.startsWith('/') ? safeHealthPath : `/${safeHealthPath}`;
+  return `${WEBSPATIAL_RUNTIME_BASE_PATH}${normalizedSuffix}`;
+}
+
 function readPersonaConfigLiteral(source, key) {
   if (!source) {
     return '';
@@ -576,6 +692,17 @@ export function resolvePersonaDevEnvironment({
   return {};
 }
 
+export function resolvePersonaHealthPath({
+  workspacePath,
+  fallback = '/oomi.health.json',
+} = {}) {
+  const runtimeConfig = readPersonaRuntimeConfig(workspacePath);
+  return normalizePersonaHealthPath(
+    trimString(runtimeConfig?.healthPath) || fallback,
+    runtimeConfig,
+  );
+}
+
 export function startPersonaWorkspace({
   workspacePath,
   logFilePath,
@@ -754,23 +881,30 @@ export async function waitForPersonaRuntime({
   throw new Error(`Timed out waiting for persona runtime healthcheck: ${message}`);
 }
 
-export function buildLocalPersonaRuntime({
-  localPort,
-  healthPath,
-}) {
-  const port = Number(localPort);
-  if (!Number.isFinite(port) || port <= 0) {
-    throw new Error('Local port is required.');
-  }
-
-  const endpoint = `http://127.0.0.1:${port}`;
-  return {
-    transport: 'local',
-    endpoint,
-    localPort: port,
-    healthcheckUrl: `${endpoint}${healthPath}`,
-  };
-}
+export function buildLocalPersonaRuntime({
+  localPort,
+  healthPath,
+}) {
+  const port = Number(localPort);
+  if (!Number.isFinite(port) || port <= 0) {
+    throw new Error('Local port is required.');
+  }
+
+  const bindHost = resolvePersonaBindHost();
+  const reachableHost = resolvePersonaReachableHost({ bindHost });
+  const endpoint = `http://127.0.0.1:${port}`;
+  const reachableEndpoint = `http://${formatPersonaRuntimeHostForUrl(reachableHost)}:${port}`;
+  const normalizedHealthPath = healthPath || '/oomi.health.json';
+  return {
+    transport: 'local',
+    endpoint,
+    reachableEndpoint,
+    bindHost,
+    reachableHost,
+    localPort: port,
+    healthcheckUrl: `${endpoint}${normalizedHealthPath}`,
+  };
+}
 
 export function defaultPersonaWorkspaceRoot() {
   return resolveOpenclawPersonasDir();

package/lib/personaRuntimeSupervisor.js

@@ -4,8 +4,13 @@ import path from 'node:path';
 import { resolveOpenclawLegacyPersonasDir } from './openclawPaths.js';
 import { createPersonaApiClient } from './personaApiClient.js';
 import { launchManagedPersonaRuntime } from './personaRuntimeManager.js';
-import { readPersonaRuntimeState } from './personaRuntimeRegistry.js';
-import { isPersonaWorkspaceProcessRunning } from './personaRuntimeProcess.js';
+import { readPersonaRuntimeState, updatePersonaRuntimeState } from './personaRuntimeRegistry.js';
+import {
+  buildLocalPersonaRuntime,
+  isPersonaWorkspaceProcessRunning,
+  resolvePersonaDevCommand,
+  resolvePersonaHealthPath,
+} from './personaRuntimeProcess.js';
 
 function trimString(value) {
   return typeof value === 'string' ? value.trim() : '';
@@ -76,14 +81,32 @@ async function reconcileWorkspace({
   const runtime = {
     slug,
     endpoint: trimString(state.endpoint || state.entryUrl || state.localEndpoint),
+    localEndpoint: trimString(state.localEndpoint),
+    reachableEndpoint: trimString(state.reachableEndpoint),
     healthcheckUrl: trimString(state.healthcheckUrl),
     transport: trimString(state.transport) || 'local',
     localPort: Number.isFinite(Number(state.localPort)) ? Number(state.localPort) : null,
   };
 
+  const localRuntime = runtime.localPort
+    ? buildLocalPersonaRuntime({
+        localPort: runtime.localPort,
+        healthPath: resolvePersonaHealthPath({
+          workspacePath,
+          fallback: '/oomi.health.json',
+        }),
+      })
+    : null;
+
+  const expectedDevCommand = runtime.localPort
+    ? resolvePersonaDevCommand({
+        workspacePath,
+        localPort: runtime.localPort,
+      })
+    : state.devCommand;
   const processRunning = isPersonaWorkspaceProcessRunning(state.pid, {
     workspacePath,
-    expectedCommand: state.devCommand,
+    expectedCommand: expectedDevCommand,
     localPort: runtime.localPort,
   });
 
@@ -110,6 +133,8 @@ async function reconcileWorkspace({
       effectiveRuntime = {
         slug,
         endpoint: launchResult.runtime.endpoint,
+        localEndpoint: launchResult.runtime.localEndpoint || launchResult.localRuntime.endpoint,
+        reachableEndpoint: launchResult.runtime.reachableEndpoint || launchResult.localRuntime.reachableEndpoint,
         healthcheckUrl: launchResult.runtime.healthcheckUrl,
         transport: launchResult.runtime.transport,
         localPort: launchResult.runtime.localPort,
@@ -135,7 +160,106 @@ async function reconcileWorkspace({
 
   const healthy = await healthcheckOk(effectiveRuntime.healthcheckUrl);
   if (!healthy) {
-    return;
+    if (!autoRestart) {
+      return;
+    }
+
+    try {
+      const recovered = await launchManagedPersonaRuntime({
+        slug,
+        name: trimString(state.name) || slug,
+        description: trimString(state.description) || trimString(state.name) || slug,
+        workspaceRoot,
+        templateVersion: trimString(state.templateVersion) || 'v1',
+        forceInstall: false,
+        restart: true,
+        logFilePath: trimString(state.logFilePath),
+        entryUrl: '',
+        transport: 'local',
+      });
+
+      effectiveRuntime = {
+        slug,
+        endpoint: recovered.runtime.endpoint,
+        localEndpoint: recovered.runtime.localEndpoint || recovered.localRuntime.endpoint,
+        reachableEndpoint: recovered.runtime.reachableEndpoint || recovered.localRuntime.reachableEndpoint,
+        healthcheckUrl: recovered.runtime.healthcheckUrl,
+        transport: recovered.runtime.transport,
+        localPort: recovered.runtime.localPort,
+      };
+
+      await client.registerRuntime({
+        slug,
+        endpoint: effectiveRuntime.endpoint,
+        healthcheckUrl: effectiveRuntime.healthcheckUrl,
+        localPort: effectiveRuntime.localPort,
+        transport: effectiveRuntime.transport,
+        startedAt: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.warn?.(
+        `[persona-runtime] unhealthy runtime restart failed for ${slug}: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+      return;
+    }
+  }
+
+  if (!healthy) {
+    const recoveredHealthy = await healthcheckOk(effectiveRuntime.healthcheckUrl);
+    if (!recoveredHealthy) {
+      return;
+    }
+  }
+
+  if (localRuntime) {
+    const refreshedLocalRuntime = buildLocalPersonaRuntime({
+      localPort: effectiveRuntime.localPort,
+      healthPath: resolvePersonaHealthPath({
+        workspacePath,
+        fallback: '/oomi.health.json',
+      }),
+    });
+    const desiredEndpoint = refreshedLocalRuntime.reachableEndpoint || runtime.endpoint;
+    const endpointChanged = desiredEndpoint && desiredEndpoint !== effectiveRuntime.endpoint;
+    const localEndpointChanged = refreshedLocalRuntime.endpoint !== effectiveRuntime.localEndpoint;
+    const reachableEndpointChanged = refreshedLocalRuntime.reachableEndpoint !== effectiveRuntime.reachableEndpoint;
+
+    if (endpointChanged || localEndpointChanged || reachableEndpointChanged) {
+      effectiveRuntime = {
+        ...effectiveRuntime,
+        endpoint: desiredEndpoint,
+        localEndpoint: refreshedLocalRuntime.endpoint,
+        reachableEndpoint: refreshedLocalRuntime.reachableEndpoint,
+      };
+      updatePersonaRuntimeState(workspacePath, {
+        endpoint: desiredEndpoint,
+        entryUrl: desiredEndpoint,
+        localEndpoint: refreshedLocalRuntime.endpoint,
+        reachableEndpoint: refreshedLocalRuntime.reachableEndpoint,
+        bindHost: refreshedLocalRuntime.bindHost,
+        reachableHost: refreshedLocalRuntime.reachableHost,
+      });
+
+      try {
+        await client.registerRuntime({
+          slug,
+          endpoint: effectiveRuntime.endpoint,
+          healthcheckUrl: effectiveRuntime.healthcheckUrl,
+          localPort: effectiveRuntime.localPort,
+          transport: effectiveRuntime.transport,
+          startedAt: new Date().toISOString(),
+        });
+      } catch (error) {
+        logger.warn?.(
+          `[persona-runtime] registration refresh failed for ${slug}: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        return;
+      }
+    }
   }
 
   try {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "oomi-ai",
   "name": "Oomi Channel Plugin",
   "description": "Managed Oomi channel integration for OpenClaw.",
-  "version": "0.2.41",
+  "version": "0.2.45",
   "author": "Oomi",
   "license": "MIT",
   "openclawVersion": ">=0.5.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.41",
+  "version": "0.2.45",
   "description": "Oomi OpenClaw channel plugin and bridge tooling",
   "bin": {
     "oomi": "bin/oomi-ai.js"

package/templates/persona-app/oomi.runtime.json

@@ -1,7 +1,7 @@
 {
   "templateVersion": "__OOMI_TEMPLATE_VERSION__",
   "appKind": "oomi-persona-app",
-  "healthPath": "/oomi.health.json",
+  "healthPath": "/webspatial/avp/oomi.health.json",
   "defaultPort": 4789,
   "supportsRuntimeRegistration": true,
   "renderMode": "webspatial",

package/templates/persona-app/package.json

@@ -5,10 +5,10 @@
   "type": "module",
   "scripts": {
     "install:clean": "npm install",
-    "dev": "vite --host 127.0.0.1 --port 4789",
-    "dev:avp": "cross-env XR_ENV=avp vite --host 127.0.0.1 --port 4789",
+    "dev": "vite --host 0.0.0.0 --port 4789 --strictPort",
+    "dev:avp": "cross-env XR_ENV=avp vite --host 0.0.0.0 --port 4789 --strictPort",
     "build": "vite build && cross-env XR_ENV=avp vite build",
-    "preview": "vite preview --host 127.0.0.1 --port 4789",
+    "preview": "vite preview --host 0.0.0.0 --port 4789 --strictPort",
     "lint": "eslint ."
   },
   "dependencies": {

package/templates/persona-app/template.json

@@ -4,7 +4,7 @@
   "displayName": "Oomi Persona App",
   "appKind": "oomi-persona-app",
   "defaultPort": 4789,
-  "healthPath": "/oomi.health.json",
+  "healthPath": "/webspatial/avp/oomi.health.json",
   "startCommand": "npm run dev:avp",
   "editableZones": [
     "src/persona",