oomi-ai 0.2.38 → 0.2.40

package/README.md

@@ -4,10 +4,12 @@ OpenClaw channel plugin and bridge tooling for Oomi managed chat and voice.
 
 ## Current Focus
 
-`0.2.38` keeps the persona automation lane, adds a stable local persona runtime manager, upgrades the Docker dev harness from a package simulator to a real OpenClaw runtime, and introduces a shared OpenClaw profile contract so local onboarding, Docker bootstrap, and future hosted agents use the same setup model:
-- WebSpatial-based persona scaffolding for generated Oomi apps
-- a high-level `oomi personas create-managed` command for agent-driven persona creation
-- a stable `oomi personas launch-managed` flow for local persona hosting under `~/.openclaw/personas`
+`0.2.40` keeps the persona automation lane, adds a stable local persona runtime manager, upgrades the Docker dev harness from a package simulator to a real OpenClaw runtime, and introduces a shared OpenClaw profile contract so local onboarding, Docker bootstrap, and future hosted agents use the same setup model:
+- WebSpatial-based persona scaffolding for generated Oomi apps
+- vendored AndroidXR WebSpatial fork sync for persona runtimes, including the npm-safe package metadata needed by OpenClaw installs
+- managed persona runtime installs now detect vendored WebSpatial drift and reinstall automatically so existing workspaces pick up XR runtime fixes
+- a high-level `oomi personas create-managed` command for agent-driven persona creation
+- a stable `oomi personas launch-managed` flow for local persona hosting under `OPENCLAW_WORKSPACE/personas`
 - a matching `oomi personas delete` flow that stops managed runtimes and removes the persona workspace from the OpenClaw machine
 - shared OpenClaw path handling for isolated local or containerized dev roots
 - versioned `oomi openclaw profile init|apply` commands for deterministic local/dev or hosted setup flows
@@ -288,7 +290,7 @@ The local harness uses the `openrouter-free` preset for direct-provider smoke. I
 Use the scaffold flow when OpenClaw needs to build a managed persona app that will live inside Oomi:
 
 ```bash
-oomi personas scaffold market-analyst --name "Market Analyst" --description "Private app for reviewing my broker positions and risk." --out ~/.openclaw/personas/market-analyst
+oomi personas scaffold market-analyst --name "Market Analyst" --description "Private app for reviewing my broker positions and risk." --out ~/.openclaw/workspace/personas/market-analyst
 ```
 
 Use:
@@ -307,7 +309,7 @@ oomi personas delete market-analyst
 oomi personas runtime-register market-analyst --local-port 4789
 oomi personas heartbeat market-analyst --local-port 4789
 oomi persona-jobs start pj_123
-oomi persona-jobs succeed pj_123 --workspace-path ~/.openclaw/personas/market-analyst --local-port 4789
+oomi persona-jobs succeed pj_123 --workspace-path ~/.openclaw/workspace/personas/market-analyst --local-port 4789
 oomi persona-jobs fail pj_123 --code JOB_FAILED --message "Scaffold generation failed."
 ```
 
@@ -325,14 +327,22 @@ If you want to explicitly host or reuse the persona app on the OpenClaw machine
 oomi personas launch-managed cooking-persona --entry-url https://your-relay.example/oomi/cooking-persona
 ```
 
-This command:
-
-- reuses `~/.openclaw/personas/<slug>` as the stable workspace
-- scaffolds only when the workspace is missing
-- installs dependencies only when needed or forced
-- allocates or reuses a free local port
-- starts or reuses the local runtime
-- registers the runtime URL back to Oomi unless `--no-register` is set
+This command:
+
+- reuses `OPENCLAW_WORKSPACE/personas/<slug>` as the stable workspace
+- scaffolds only when the workspace is missing
+- installs dependencies only when needed or forced
+- allocates or reuses a free local port
+- starts or reuses the local runtime
+- registers the runtime URL back to Oomi unless `--no-register` is set
+
+For existing managed personas that are already open in Oomi, the safe edit flow is:
+
+```bash
+oomi personas status <slug> --json
+```
+
+The agent should use `editableWorkspacePath` from that output as the authoritative directory for reads, edits, and verification. `compatibilityWorkspacePath` is only a fallback for older installs.
 
 ## Bridge Health States
 

package/agent_instructions.md

@@ -209,6 +209,15 @@ When generating a managed persona app for Oomi:
 4. Preserve the scaffolded WebSpatial/Vite shell, `public/oomi.health.json`, `oomi.runtime.json`, and `public/manifest.webmanifest`.
 5. After customization, start the app and register the runtime with Oomi using the current runtime contract.
 
+When editing an existing managed persona that is already open in Oomi:
+
+1. Do not ask the user to find the app path manually if Oomi already selected the persona tab for you.
+2. First run `oomi personas status <slug> --json`.
+3. Use `editableWorkspacePath` from that command as the authoritative directory for reads, edits, and verification.
+4. Treat `compatibilityWorkspacePath` only as a fallback or migration clue.
+5. Preserve the scaffolded WebSpatial shell and runtime health files unless the user explicitly asks for a deeper structural change.
+6. Do not claim the persona changed unless you have verified the file contents changed in `editableWorkspacePath` or the runtime reflects the update.
+
 When executing a structured persona job from Oomi:
 
 1. Prefer `oomi persona-jobs execute --message-file <job.json>` when the backend has already produced a machine-readable job payload.

package/bin/oomi-ai.js

@@ -329,7 +329,7 @@ Common flags:
   --health-path PATH     Runtime health path (default: /oomi.health.json)
   --healthcheck-url URL  Runtime healthcheck URL override
   --transport TEXT       Runtime transport label (default: local, relay when --entry-url is used)
-  --workspace-root PATH  Persona workspace root (default: ~/.openclaw/personas)
+  --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
   --observed-at ISO      Heartbeat timestamp override

package/lib/openclawPaths.js

@@ -15,11 +15,11 @@ export function resolveOpenclawHome() {
   return path.join(os.homedir(), '.openclaw');
 }
 
-export function resolveOpenclawWorkspaceRoot() {
-  const explicitWorkspace = trimString(process.env.OPENCLAW_WORKSPACE);
-  if (explicitWorkspace) {
-    return path.resolve(explicitWorkspace);
-  }
+export function resolveOpenclawWorkspaceRoot() {
+  const explicitWorkspace = trimString(process.env.OPENCLAW_WORKSPACE);
+  if (explicitWorkspace) {
+    return path.resolve(explicitWorkspace);
+  }
 
   const openclawHome = resolveOpenclawHome();
   const managedWorkspace = path.join(openclawHome, 'workspace');
@@ -27,12 +27,16 @@ export function resolveOpenclawWorkspaceRoot() {
     return managedWorkspace;
   }
 
-  return openclawHome;
-}
-
-export function resolveOpenclawPath(...parts) {
-  return path.join(resolveOpenclawHome(), ...parts);
-}
+  return openclawHome;
+}
+
+export function resolveOpenclawLegacyPersonasDir() {
+  return resolveOpenclawPath('personas');
+}
+
+export function resolveOpenclawPath(...parts) {
+  return path.join(resolveOpenclawHome(), ...parts);
+}
 
 export function resolveOpenclawConfigCandidates() {
   return [
@@ -41,13 +45,18 @@ export function resolveOpenclawConfigCandidates() {
   ];
 }
 
-export function resolveOpenclawSkillsDir() {
-  return resolveOpenclawPath('skills');
-}
-
-export function resolveOpenclawPersonasDir() {
-  return resolveOpenclawPath('personas');
-}
+export function resolveOpenclawSkillsDir() {
+  return resolveOpenclawPath('skills');
+}
+
+export function resolveOpenclawPersonasDir() {
+  const explicitPersonas = trimString(process.env.OPENCLAW_PERSONAS_DIR);
+  if (explicitPersonas) {
+    return path.resolve(explicitPersonas);
+  }
+
+  return path.join(resolveOpenclawWorkspaceRoot(), 'personas');
+}
 
 export function resolveOpenclawIdentityPath() {
   return resolveOpenclawPath('identity', 'device.json');

package/lib/personaRuntimeManager.js

@@ -1,17 +1,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
-
-import { findAvailablePort } from './personaPortAllocator.js';
-import {
-  buildLocalPersonaRuntime,
-  defaultPersonaWorkspaceRoot,
-  installPersonaWorkspace,
-  isPersonaWorkspaceProcessRunning,
-  resolvePersonaDevCommand,
-  startPersonaWorkspace,
-  stopPersonaWorkspace,
-  waitForPersonaRuntime,
-} from './personaRuntimeProcess.js';
+
+import { findAvailablePort } from './personaPortAllocator.js';
+import { resolveOpenclawLegacyPersonasDir } from './openclawPaths.js';
+import {
+  buildLocalPersonaRuntime,
+  defaultPersonaWorkspaceRoot,
+  installPersonaWorkspace,
+  isPersonaWorkspaceProcessRunning,
+  resolvePersonaDevCommand,
+  syncLegacyWebSpatialScaffoldFiles,
+  syncVendoredWebSpatialPackages,
+  startPersonaWorkspace,
+  stopPersonaWorkspace,
+  waitForPersonaRuntime,
+} from './personaRuntimeProcess.js';
 import {
   readPersonaRuntimeState,
   resolvePersonaRuntimeLogPath,
@@ -21,9 +24,110 @@ import {
 } from './personaRuntimeRegistry.js';
 import { scaffoldPersonaApp } from './scaffold.js';
 
-function trimString(value) {
-  return typeof value === 'string' ? value.trim() : '';
-}
+function trimString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function samePath(a, b) {
+  return path.resolve(String(a || '')) === path.resolve(String(b || ''));
+}
+
+function pathExists(targetPath) {
+  return Boolean(targetPath) && fs.existsSync(targetPath);
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function ensureDirectoryLink(linkPath, targetPath) {
+  if (!linkPath || !targetPath || samePath(linkPath, targetPath) || pathExists(linkPath)) {
+    return false;
+  }
+
+  ensureDir(path.dirname(linkPath));
+  try {
+    fs.symlinkSync(
+      targetPath,
+      linkPath,
+      process.platform === 'win32' ? 'junction' : 'dir'
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveManagedPersonaWorkspacePaths({
+  slug,
+  workspaceRoot = defaultPersonaWorkspaceRoot(),
+}) {
+  const canonicalWorkspaceRoot = path.resolve(workspaceRoot);
+  const canonicalWorkspacePath = resolvePersonaWorkspacePath({
+    workspaceRoot: canonicalWorkspaceRoot,
+    slug,
+  });
+  const legacyWorkspaceRoot = path.resolve(resolveOpenclawLegacyPersonasDir());
+  const legacyWorkspacePath = samePath(canonicalWorkspaceRoot, legacyWorkspaceRoot)
+    ? ''
+    : resolvePersonaWorkspacePath({
+        workspaceRoot: legacyWorkspaceRoot,
+        slug,
+      });
+
+  return {
+    canonicalWorkspaceRoot,
+    canonicalWorkspacePath,
+    legacyWorkspaceRoot: legacyWorkspacePath ? legacyWorkspaceRoot : '',
+    legacyWorkspacePath,
+  };
+}
+
+function resolveManagedPersonaWorkspace({
+  slug,
+  workspaceRoot = defaultPersonaWorkspaceRoot(),
+}) {
+  const paths = resolveManagedPersonaWorkspacePaths({ slug, workspaceRoot });
+  ensureDir(paths.canonicalWorkspaceRoot);
+
+  let migratedFromLegacy = false;
+  let canonicalProxyCreated = false;
+  let legacyProxyCreated = false;
+
+  if (!pathExists(paths.canonicalWorkspacePath) && pathExists(paths.legacyWorkspacePath)) {
+    try {
+      fs.renameSync(paths.legacyWorkspacePath, paths.canonicalWorkspacePath);
+      migratedFromLegacy = true;
+    } catch {
+      canonicalProxyCreated = ensureDirectoryLink(
+        paths.canonicalWorkspacePath,
+        paths.legacyWorkspacePath
+      );
+    }
+  }
+
+  if (pathExists(paths.canonicalWorkspacePath) && paths.legacyWorkspacePath && !pathExists(paths.legacyWorkspacePath)) {
+    legacyProxyCreated = ensureDirectoryLink(
+      paths.legacyWorkspacePath,
+      paths.canonicalWorkspacePath
+    );
+  }
+
+  const workspacePath = pathExists(paths.canonicalWorkspacePath)
+    ? paths.canonicalWorkspacePath
+    : (pathExists(paths.legacyWorkspacePath) ? paths.legacyWorkspacePath : paths.canonicalWorkspacePath);
+
+  return {
+    ...paths,
+    workspacePath,
+    editableWorkspacePath: pathExists(paths.canonicalWorkspacePath)
+      ? paths.canonicalWorkspacePath
+      : workspacePath,
+    migratedFromLegacy,
+    canonicalProxyCreated,
+    legacyProxyCreated,
+  };
+}
 
 export function slugifyPersonaName(name) {
   const normalized = trimString(name)
@@ -91,16 +195,18 @@ async function ensureWorkspaceScaffold({
   };
 }
 
-async function ensureWorkspaceInstall({
-  workspacePath,
-  forceInstall = false,
-}) {
-  const nodeModulesPath = path.join(workspacePath, 'node_modules');
-  if (!forceInstall && fs.existsSync(nodeModulesPath)) {
-    return false;
-  }
-
-  await installPersonaWorkspace({ workspacePath });
+async function ensureWorkspaceInstall({
+  workspacePath,
+  forceInstall = false,
+}) {
+  const packageSyncChanged = syncVendoredWebSpatialPackages({ workspacePath });
+  syncLegacyWebSpatialScaffoldFiles({ workspacePath });
+  const nodeModulesPath = path.join(workspacePath, 'node_modules');
+  if (!forceInstall && fs.existsSync(nodeModulesPath) && !packageSyncChanged) {
+    return false;
+  }
+
+  await installPersonaWorkspace({ workspacePath });
   return true;
 }
 
@@ -143,14 +249,15 @@ export async function launchManagedPersonaRuntime({
   const safeDescription = trimString(description) || safeName;
   if (!safeName) {
     throw new Error('Persona name is required.');
-  }
-
-  const safeSlug = trimString(slug) || slugifyPersonaName(safeName);
-  const workspacePath = resolvePersonaWorkspacePath({
-    workspaceRoot,
-    slug: safeSlug,
-  });
-  const previousState = readPersonaRuntimeState(workspacePath);
+  }
+
+  const safeSlug = trimString(slug) || slugifyPersonaName(safeName);
+  const workspaceResolution = resolveManagedPersonaWorkspace({
+    slug: safeSlug,
+    workspaceRoot,
+  });
+  const workspacePath = workspaceResolution.workspacePath;
+  const previousState = readPersonaRuntimeState(workspacePath);
 
   const scaffoldInfo = await ensureWorkspaceScaffold({
     slug: safeSlug,
@@ -238,13 +345,16 @@ export async function launchManagedPersonaRuntime({
     devCommand: resolvePersonaDevCommand({ workspacePath, localPort }),
   });
 
-  return {
-    ok: true,
-    slug: safeSlug,
-    workspacePath,
-    scaffolded: scaffoldInfo.scaffolded,
-    installed,
-    reusedRunningProcess: reusingRunningProcess,
+  return {
+    ok: true,
+    slug: safeSlug,
+    workspacePath,
+    editableWorkspacePath: workspaceResolution.editableWorkspacePath,
+    compatibilityWorkspacePath: workspaceResolution.legacyWorkspacePath || '',
+    migratedFromLegacy: workspaceResolution.migratedFromLegacy,
+    scaffolded: scaffoldInfo.scaffolded,
+    installed,
+    reusedRunningProcess: reusingRunningProcess,
     runtime: registration,
     localRuntime,
     state: runtimeState,
@@ -256,26 +366,33 @@ export function getManagedPersonaRuntimeStatus({
   workspaceRoot = defaultPersonaWorkspaceRoot(),
 }) {
   const safeSlug = trimString(slug);
-  if (!safeSlug) {
-    throw new Error('Persona slug is required.');
-  }
-
-  const workspacePath = resolvePersonaWorkspacePath({
-    workspaceRoot,
-    slug: safeSlug,
-  });
-  const state = readPersonaRuntimeState(workspacePath);
-  const pid = Number.isInteger(state.pid) ? state.pid : null;
-
-  return {
-    slug: safeSlug,
-    workspacePath,
-    workspaceExists: fs.existsSync(workspacePath),
-    runtimeStatePath: resolvePersonaRuntimeStatePath(workspacePath),
-    processRunning: pid ? isPersonaWorkspaceProcessRunning(pid) : false,
-    state,
-  };
-}
+  if (!safeSlug) {
+    throw new Error('Persona slug is required.');
+  }
+
+  const workspaceResolution = resolveManagedPersonaWorkspace({
+    slug: safeSlug,
+    workspaceRoot,
+  });
+  const workspacePath = workspaceResolution.workspacePath;
+  const state = readPersonaRuntimeState(workspacePath);
+  const pid = Number.isInteger(state.pid) ? state.pid : null;
+
+  return {
+    slug: safeSlug,
+    workspaceRoot: workspaceResolution.canonicalWorkspaceRoot,
+    workspacePath,
+    editableWorkspacePath: workspaceResolution.editableWorkspacePath,
+    compatibilityWorkspacePath: workspaceResolution.legacyWorkspacePath || '',
+    workspaceExists: fs.existsSync(workspacePath),
+    runtimeStatePath: resolvePersonaRuntimeStatePath(workspacePath),
+    processRunning: pid ? isPersonaWorkspaceProcessRunning(pid) : false,
+    migratedFromLegacy: workspaceResolution.migratedFromLegacy,
+    canonicalProxyCreated: workspaceResolution.canonicalProxyCreated,
+    legacyProxyCreated: workspaceResolution.legacyProxyCreated,
+    state,
+  };
+}
 
 export async function stopManagedPersonaRuntime({
   slug,
@@ -352,8 +469,11 @@ export async function destroyManagedPersonaRuntime({
     slug,
     workspaceRoot,
   });
-  ensureWorkspacePathWithinRoot(status.workspacePath, workspaceRoot);
+  ensureWorkspacePathWithinRoot(status.workspacePath, status.workspaceRoot || workspaceRoot);
   fs.rmSync(status.workspacePath, { recursive: true, force: true });
+  if (status.compatibilityWorkspacePath && pathExists(status.compatibilityWorkspacePath)) {
+    fs.rmSync(status.compatibilityWorkspacePath, { recursive: true, force: true });
+  }
 
   return {
     ok: true,