oomi-ai 0.2.48 → 0.2.50

package/README.md

@@ -1,57 +1,60 @@
-# oomi-ai
-
-OpenClaw channel plugin and bridge tooling for Oomi managed chat and voice.
-
-## Current Focus
-
-`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
-- explicit model auth modes so onboarding can default to `oomi-managed` while internal testing can still opt into direct provider auth
-- a repo-local `openclaw debug persona-runtime` smoke test for managed persona runtime launch/reuse/stop
-- a Docker-based OpenClaw dev harness that runs a real `openclaw gateway` inside an isolated container
-- device-authenticated persona runtime registration and job callbacks
-- automatic bridge-side polling for queued `persona_job` control messages
-- one shared spoken-metadata normalizer used by both the extension and the bridge
-- a repo-backed local `tts-pipeline` replay that can validate assistant-final -> backend -> real Qwen TTS before publishing
-- spoken-metadata handling that preserves natural pauses like `...` and keeps the managed voice contract valid on the real chat session path
-
-This package is for two audiences:
-- OpenClaw operators who need to connect a machine to Oomi and keep chat or voice healthy
-- Developers evaluating the plugin on npm and deciding whether it matches their OpenClaw + Oomi setup
-
-## What This Package Ships
-
-The npm package contains two Oomi integration surfaces:
-
-1. OpenClaw channel extension
-- File: `openclaw.extension.js`
-- Purpose: stable managed text transport through the Oomi backend channel API
-- This is the preferred integration surface for normal chat
-
-2. Local bridge + CLI
-- Files: `bin/oomi-ai.js`, `bin/sessionBridgeState.js`
-- Purpose: pair a device, manage the OpenClaw bridge worker, and support managed gateway traffic needed by device-backed chat and voice
-- This is the part that deals with broker sockets, local gateway sessions, challenge auth, and bridge health
-
-In practical terms:
-- If you only need a clean managed chat channel, the extension is the main reason to install this package
-- If you need Oomi device-backed chat or voice on an OpenClaw machine, you also need the bridge tooling in this package
+# oomi-ai
+
+Managed Oomi chat, voice bridge, and XR-first persona scaffolding for OpenClaw.
+
+## At A Glance
+
+- managed OpenClaw channel extension for Oomi text chat
+- local bridge and pairing tooling for device-backed chat and voice
+- XR-first WebSpatial persona scaffolding for generated Oomi work surfaces
+- vendored AndroidXR WebSpatial fork sync and scaffold repair for managed persona runtimes
+- managed persona launch, register, stop, delete, and queued persona-job execution flows
+- repo-local runtime and TTS validation loops for package developers
+
+This package is for two audiences:
+- OpenClaw operators who need to connect a machine to Oomi and keep chat or voice healthy
+- Developers evaluating the plugin on npm and deciding whether it matches their OpenClaw + Oomi setup
+
+## Current Package Focus
+
+The current package is centered on three operational contracts:
+
+1. managed Oomi text transport inside OpenClaw
+2. device-backed chat and voice through the local bridge
+3. XR-first persona runtime generation and repair for Oomi work surfaces
+
+## What This Package Ships
+
+The npm package contains three Oomi integration surfaces:
+
+1. OpenClaw channel extension
+- File: `openclaw.extension.js`
+- Purpose: stable managed text transport through the Oomi backend channel API
+- This is the preferred integration surface for normal chat
+
+2. Local bridge + CLI
+- Files: `bin/oomi-ai.js`, `bin/sessionBridgeState.js`
+- Purpose: pair a device, manage the OpenClaw bridge worker, and support managed gateway traffic needed by device-backed chat and voice
+- This is the part that deals with broker sockets, local gateway sessions, challenge auth, and bridge health
+
+3. Persona scaffold + runtime helpers
+- Files: `templates/persona-app/*`, `lib/scaffold.js`, `lib/personaRuntime*.js`
+- Purpose: create, launch, repair, and register XR-first managed persona apps for Oomi
+- This is the part that matters when Oomi or an agent generates a specialist work surface
+
+In practical terms:
+- If you only need a clean managed chat channel, the extension is the main reason to install this package
+- If you need Oomi device-backed chat or voice on an OpenClaw machine, you also need the bridge tooling in this package
+- If you need Oomi-managed personas that open as real XR work surfaces, you also need the scaffold and runtime helpers in this package
 
 ## When To Install It
 
-Install `oomi-ai` if all of the following are true:
-- you use OpenClaw
-- you want Oomi as a managed channel inside OpenClaw
-- you want device-backed Oomi chat, Oomi voice, or both
-
-Do not install it just to use the Oomi web app by itself.
+Install `oomi-ai` if all of the following are true:
+- you use OpenClaw
+- you want Oomi as a managed channel, bridge-backed voice surface, or persona runtime inside OpenClaw
+- you want device-backed Oomi chat, Oomi voice, generated personas, or some combination of those
+
+Do not install it just to use the Oomi web app by itself.
 
 ## Install And Upgrade
 
@@ -82,14 +85,15 @@ openclaw plugins install oomi-ai@latest
 
 ## Operator Quick Start
 
-The packaged operator instructions live in [agent_instructions.md](./agent_instructions.md).
-That is the primary reference for:
-- pairing a device
-- installing the plugin
-- configuring `channels.oomi.accounts.default`
-- running or supervising the bridge
-- checking whether the system is healthy
-- troubleshooting chat and voice failures
+The packaged operator instructions live in [agent_instructions.md](./agent_instructions.md).
+That is the primary reference for:
+- pairing a device
+- installing the plugin
+- configuring `channels.oomi.accounts.default`
+- running or supervising the bridge
+- checking whether the system is healthy
+- troubleshooting chat and voice failures
+- generating or repairing XR-first managed persona apps
 
 Fast-path install flow:
 
@@ -285,43 +289,119 @@ OPENROUTER_API_KEY=<your-openrouter-key>
 
 The local harness uses the `openrouter-free` preset for direct-provider smoke. If `OPENROUTER_API_KEY` is present in `.env.local`, `pnpm run dev:openclaw-local` automatically uses the provider-backed testing path. Without that key, it boots in `oomi-managed` mode and waits on a future Oomi-managed provider relay.
 
-## Persona Scaffolding
-
-Use the scaffold flow when OpenClaw needs to build a managed persona app that will live inside Oomi:
+## Persona Scaffolding
+
+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/workspace/personas/market-analyst
 ```
 
-Use:
-- `oomi personas create <id>` for repo-local manifest work
-- `oomi personas create-managed --name "Cooking Persona" --description "Private cooking workspace"` for the end-to-end Oomi-managed persona flow
-- `oomi personas scaffold <slug>` for a WebSpatial-based Oomi app shell with runtime metadata and health documents
-- `oomi persona-jobs execute --message-file <job.json>` when OpenClaw receives a structured persona orchestration job from Oomi
-
-Additional persona runtime commands:
-
-```bash
-oomi personas launch-managed market-analyst --name "Market Analyst" --description "Private app for reviewing my broker positions and risk."
+Use:
+- `oomi personas create <id>` only for repo-local manifest work, not for the normal managed Oomi persona flow
+- `oomi personas create-managed <slug>` to create the backend managed persona record before launch or runtime registration
+- `oomi personas scaffold <slug>` for an XR-first WebSpatial Oomi app shell with runtime metadata and health documents
+- `oomi persona-jobs execute --message-file <job.json>` when OpenClaw receives a structured persona orchestration job from Oomi
+
+Managed runtime and recovery commands:
+
+```bash
+oomi personas launch-managed market-analyst --workspace-root ~/.openclaw/workspace/personas --force-install --json
 oomi personas status market-analyst
 oomi personas stop market-analyst
 oomi personas delete market-analyst
+# recovery only, after create-managed already exists
 oomi personas runtime-register market-analyst --local-port 4789
-oomi personas heartbeat market-analyst --local-port 4789
-oomi persona-jobs start pj_123
+oomi personas heartbeat market-analyst --local-port 4789
+oomi persona-jobs start pj_123
 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."
-```
-
-Recommended agent flow:
-
-```bash
-oomi personas create-managed --name "Cooking Persona" --description "Private cooking workspace for recipes, meal planning, and kitchen notes."
-```
-
-That command creates the managed persona record in Oomi using the linked device identity. The backend then enqueues the `persona_job`, and the running bridge consumes that job automatically. The poll path is filtered to `metadata.type = persona_job`, so it does not consume normal queued chat traffic.
-
-If you want to explicitly host or reuse the persona app on the OpenClaw machine outside the queued-job path, use:
+oomi persona-jobs fail pj_123 --code JOB_FAILED --message "Scaffold generation failed."
+```
+
+Notes:
+
+- For remote Oomi clients such as web and Android XR, do not manually register `http://127.0.0.1:<port>` as the persona `entryUrl`.
+- When you pass only `--local-port`, `oomi-ai` derives a LAN-reachable endpoint automatically and keeps the healthcheck on loopback.
+- If you pass `--endpoint` explicitly, it should be a LAN or relay URL that the client can actually open.
+- The scaffolded XR route should default directly into a mounted scene component that calls `configurePersonaScene()`, logs `detectSpatialEnvironment()`, and renders multiple authored `enable-xr` panels.
+- The browser route should remain valid, but the XR entry path should not fall back to a flat marketing or home page.
+- Do not use manual `npm run dev` as the first-time persona launch path for managed Oomi personas.
+
+Exact managed persona creation order:
+
+```bash
+export WORKSPACE_ROOT="$HOME/.openclaw/workspace/personas"
+export SLUG="tokyo-guide"
+export NAME="Tokyo Guide"
+export DESCRIPTION="Personal travel assistant for Tokyo trip planning - itineraries, food, culture, and summer tips for July"
+
+# 1. Scaffold the local app workspace
+oomi personas scaffold "$SLUG" \
+  --name "$NAME" \
+  --description "$DESCRIPTION" \
+  --out "$WORKSPACE_ROOT/$SLUG" \
+  --force
+
+# 2. Verify scaffold actually wrote files
+test -f "$WORKSPACE_ROOT/$SLUG/persona.json"
+test -f "$WORKSPACE_ROOT/$SLUG/oomi.runtime.json"
+test -f "$WORKSPACE_ROOT/$SLUG/package.json"
+
+# 3. Create the backend persona record first
+oomi personas create-managed "$SLUG" \
+  --name "$NAME" \
+  --description "$DESCRIPTION" \
+  --json
+
+# 4. Launch the managed runtime and register it with Oomi
+oomi personas launch-managed "$SLUG" \
+  --workspace-root "$WORKSPACE_ROOT" \
+  --force-install \
+  --json
+
+# 5. Verify local runtime state exists
+test -f "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json"
+cat "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json"
+
+# 6. Verify Oomi-local status
+oomi personas status "$SLUG" --json
+
+# 7. Send a heartbeat using the actual assigned port
+PORT="$(jq -r '.localPort' "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json")"
+oomi personas heartbeat "$SLUG" \
+  --local-port "$PORT" \
+  --json
+```
+
+Rules for that flow:
+
+- scaffold first
+- verify scaffold wrote files before backend creation
+- create-managed before any runtime registration or heartbeat
+- launch-managed instead of manual `npm run dev`
+- heartbeat only after `.oomi/runtime.json` exists
+- fail fast if any `--json` command does not return success
+- never treat local runtime success as backend registration success
+
+Do not do this for first-time creation:
+
+```bash
+oomi personas runtime-register "$SLUG" --local-port 4791
+oomi personas launch-managed "$SLUG"
+npm run dev &
+```
+
+That sequence is wrong because `runtime-register` and `heartbeat` assume the backend persona already exists, `launch-managed` only auto-creates when the persona is missing and `--name` is present, and manual `npm run dev` bypasses the managed runtime state contract.
+
+Queued-job shortcut:
+
+```bash
+oomi personas create-managed cooking-persona --name "Cooking Persona" --description "Private cooking workspace for recipes, meal planning, and kitchen notes."
+```
+
+Use that shortcut only when the backend and running bridge are already set up to consume the queued `persona_job` automatically. Do not confuse it with the explicit scaffold + launch flow above.
+
+If you want to explicitly host or reuse the persona app on the OpenClaw machine outside the queued-job path, use:
 
 ```bash
 oomi personas launch-managed cooking-persona --entry-url https://your-relay.example/oomi/cooking-persona
@@ -412,18 +492,26 @@ What to check:
 - if the package local replay succeeds but the live machine fails, verify the OpenClaw machine is actually running the updated bridge binary
 - if the local replay fails, fix the assistant-final contract first instead of debugging the browser or backend deployment
 
-## Developer Notes
-
-If you are inspecting this package on npm, the main architectural points are:
-- the extension path is the stable managed text contract
-- the local bridge exists because Oomi also needs device-backed and voice-capable flows
-- the bridge has been hardened for:
-  - strict `connect`-first forwarding
-  - method-specific request shaping
-  - `idempotencyKey` handling
-  - bridge status that does not report `connected` before managed subscription is ready
-  - runtime fault isolation so local session failures are less likely to crash the whole provider
-  - one shared hidden managed-voice speech metadata helper used by both the extension and the local bridge
+## Developer Notes
+
+If you are inspecting this package on npm, the main architectural points are:
+- the extension path is the stable managed text contract
+- the local bridge exists because Oomi also needs device-backed and voice-capable flows
+- the persona scaffold exists because Oomi specialist personas can surface as scoped XR/web work surfaces, not just chat tabs
+- the bridge has been hardened for:
+  - strict `connect`-first forwarding
+  - method-specific request shaping
+  - `idempotencyKey` handling
+  - bridge status that does not report `connected` before managed subscription is ready
+  - runtime fault isolation so local session failures are less likely to crash the whole provider
+  - one shared hidden managed-voice speech metadata helper used by both the extension and the local bridge
+
+For generated WebSpatial persona apps, the intended scaffold contract is:
+- XR mode defaults directly into the mounted scene route
+- `configurePersonaScene()` runs from that scene component
+- runtime diagnostics are logged on scene boot
+- multiple meaningful UI surfaces use `enable-xr` and `xrStyle()`
+- `html.is-spatial` keeps the host shell transparent
 
 If you are developing the plugin, test the packaged surface with:
 

package/agent_instructions.md

@@ -1,6 +1,11 @@
-# Oomi OpenClaw Operator Guide
-
-Use these instructions when you need to connect, repair, or verify an OpenClaw machine that should talk to Oomi.
+# Oomi OpenClaw Operator Guide
+
+Use these instructions when you need to connect, repair, or verify an OpenClaw machine that should talk to Oomi.
+
+This is the packaged agent-facing reference for:
+- managed OpenClaw connect and repair flows
+- device-backed chat and voice bridge recovery
+- XR-first persona generation and persona runtime repair
 
 ## Primary Goal
 
@@ -194,20 +199,51 @@ Aliases allowed if needed:
 
 ## Persona App Generation
 
+For persona app work, treat the scaffold as a runtime contract, not a disposable starting point.
+
 When a user asks you in chat to create a new persona for Oomi:
 
-1. Prefer `oomi personas create-managed --name "<name>" --description "<description>"`.
-2. That is the primary end-to-end command for agent-driven persona creation.
-3. It creates the managed persona record in Oomi and relies on the running bridge to consume the queued `persona_job` automatically.
-4. Do not manually scaffold first unless you are recovering a failed persona job or working outside the queued Oomi flow.
+1. First clarify the persona `name`, `slug`, `description`, permissions, tools, and the ideal work surface.
+2. After that, use this exact manual creation order on the OpenClaw machine:
+   - `export WORKSPACE_ROOT="$HOME/.openclaw/workspace/personas"`
+   - `export SLUG="<persona-slug>"`
+   - `export NAME="<persona-name>"`
+   - `export DESCRIPTION="<persona-description>"`
+   - `oomi personas scaffold "$SLUG" --name "$NAME" --description "$DESCRIPTION" --out "$WORKSPACE_ROOT/$SLUG" --force`
+   - `test -f "$WORKSPACE_ROOT/$SLUG/persona.json"`
+   - `test -f "$WORKSPACE_ROOT/$SLUG/oomi.runtime.json"`
+   - `test -f "$WORKSPACE_ROOT/$SLUG/package.json"`
+   - `oomi personas create-managed "$SLUG" --name "$NAME" --description "$DESCRIPTION" --json`
+   - `oomi personas launch-managed "$SLUG" --workspace-root "$WORKSPACE_ROOT" --force-install --json`
+   - `test -f "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json"`
+   - `cat "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json"`
+   - `oomi personas status "$SLUG" --json`
+   - `PORT="$(jq -r '.localPort' "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json")"`
+   - `oomi personas heartbeat "$SLUG" --local-port "$PORT" --json`
+3. Fail fast if scaffold verification fails or if any `--json` command does not return success.
+4. Treat backend registration as incomplete until `create-managed`, `launch-managed`, `status`, and `heartbeat` all succeed.
+5. Do not present a localhost URL like `http://127.0.0.1:4789` as the final persona runtime URL for Oomi clients.
+6. Do not rely on `launch-managed` auto-creating the backend persona record. Run `create-managed` explicitly first.
+7. Do not use `oomi personas runtime-register <slug>` or `oomi personas heartbeat <slug>` before `create-managed` succeeds.
+8. Do not use manual `npm run dev` or any unmanaged dev server as the persona launch path.
 
 When generating a managed persona app for Oomi:
 
 1. Do not build the app shell from scratch.
 2. Always run `oomi personas scaffold <slug> --name "<name>" --description "<description>" --out <path>` first.
 3. Only customize persona-specific files inside `src/persona/` and `persona/` unless Oomi explicitly instructs otherwise.
-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.
+4. Preserve the scaffolded WebSpatial/Vite shell, `public/oomi.health.json`, `oomi.runtime.json`, `public/manifest.webmanifest`, and the vendored WebSpatial fork.
+5. Keep the browser route and the XR route split. In XR mode, the index route should open directly into the mounted scene component, not a flat homepage.
+6. Call `configurePersonaScene()` from that mounted scene component and log `detectSpatialEnvironment()` on scene boot so the runtime can be verified in headset.
+7. Author multiple meaningful XR surfaces with `enable-xr`, `--xr-back`, and `--xr-background-material` values instead of putting one outer `enable-xr` wrapper around the whole page.
+8. Keep `html.is-spatial` shell styles transparent so the host recedes and the authored panels carry the spatial material.
+9. Keep `snapdom` and `html2canvas` exposed from `main.tsx` because AndroidXR DOM capture depends on them.
+10. After customization, bring the persona online through `oomi personas launch-managed <slug> --workspace-root <root> --force-install --json`, then verify `oomi personas status <slug> --json`, then heartbeat using the assigned local port from `.oomi/runtime.json`.
+11. For normal OpenClaw-hosted persona apps on the same LAN, the managed runtime registration contract is:
+   - backend `entryUrl`: LAN-reachable host such as `http://192.168.x.x:<port>`
+   - backend `healthcheckUrl`: local loopback such as `http://127.0.0.1:<port>/webspatial/avp/oomi.health.json`
+12. Do not override `--endpoint` with `127.0.0.1` unless the persona is intentionally local-only and not meant to open from Oomi web/XR.
+13. Do not replace the managed runtime flow with manual `npm run dev`, ad hoc `runtime-register`, or ad hoc `heartbeat` commands during first-time creation.
 
 When editing an existing managed persona that is already open in Oomi:
 
@@ -215,7 +251,7 @@ When editing an existing managed persona that is already open in Oomi:
 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.
+5. Preserve the scaffolded WebSpatial shell and runtime health files unless the user explicitly asks for a deeper structural change, and do not regress the XR route back into a flat home page.
 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:
@@ -228,5 +264,8 @@ When executing a structured persona job from Oomi:
    - `oomi persona-jobs start <jobId>`
    - `oomi persona-jobs succeed <jobId> --workspace-path <path> --local-port 4789`
    - `oomi persona-jobs fail <jobId> --code <code> --message "<text>"`
+4. Before any low-level `runtime-register` or `heartbeat` recovery command, make sure the backend persona already exists via `create-managed`.
+5. If you use the low-level `runtime-register` or `heartbeat` commands, prefer `--local-port` by itself and let `oomi-ai` derive the LAN-reachable endpoint automatically.
+6. If you must pass `--endpoint` explicitly, it must be the LAN-reachable host or a relay URL, not `127.0.0.1`.
 
 When the Oomi bridge is running on the machine, queued persona jobs from Oomi are now polled and executed automatically through the filtered control-message lane. You should still use the explicit commands above for manual retries, recovery, or direct operator workflows.

package/bin/oomi-ai.js

@@ -259,14 +259,14 @@ Commands:
   personas sync
     Sync personas from the repo into the Oomi backend registry.
 
-  personas create <id>
-    Create a new persona manifest and optionally sync it to the backend.
-  personas create-managed [slug]
-    Create a managed persona in Oomi and enqueue its build job for the linked device.
-  personas launch-managed [slug]
-    Launch or reuse a managed persona runtime on this OpenClaw machine.
-  personas scaffold <slug>
-    Create an Oomi-managed persona app scaffold for agent customization.
+  personas create <id>
+    Create a new persona manifest for local or repo work. For managed Oomi personas prefer create-managed.
+  personas create-managed [slug]
+    Create the managed persona record in Oomi. Run this before manual launch-managed, runtime-register, or heartbeat flows.
+  personas launch-managed [slug]
+    Launch or reuse a managed persona runtime on this OpenClaw machine and register a client-reachable runtime URL. Prefer scaffold + create-managed first.
+  personas scaffold <slug>
+    Create an Oomi-managed persona app scaffold for agent customization.
   personas status <slug>
     Show local managed persona runtime state for a persona slug.
   personas stop <slug>
@@ -274,9 +274,9 @@ Commands:
   personas delete <slug>
     Stop a managed persona runtime and remove its workspace from this OpenClaw machine.
   personas runtime-register <slug>
-    Register a running persona runtime with the Oomi backend.
-  personas heartbeat <slug>
-    Send a persona runtime heartbeat to the Oomi backend.
+    Register a running persona runtime with the Oomi backend. Recovery-only after create-managed. Prefer --local-port so the CLI can derive a reachable endpoint.
+  personas heartbeat <slug>
+    Send a persona runtime heartbeat to the Oomi backend. Recovery-only after launch-managed wrote .oomi/runtime.json.
   personas runtime-fail <slug>
     Report persona runtime failure to the Oomi backend.
   persona-jobs start <jobId>
@@ -1579,21 +1579,21 @@ async function handlePersonaLaunchManagedCommand(flags = {}, positionalSlug = ''
   const client = createCliPersonaApiClient(flags);
   const safeName = String(flags.name || '').trim();
   const safeDescription = String(flags.description || '').trim() || safeName;
-  const safeSlug = String(flags.slug || positionalSlug || (safeName ? slugifyPersonaName(safeName) : '')).trim();
-  if (!safeSlug) {
-    throw new Error('Persona slug or name is required. Usage: oomi personas launch-managed [slug] --name "<name>"');
-  }
+  const safeSlug = String(flags.slug || positionalSlug || (safeName ? slugifyPersonaName(safeName) : '')).trim();
+  if (!safeSlug) {
+    throw new Error('Persona slug or name is required. Usage: oomi personas launch-managed [slug] --name "<name>". Prefer `oomi personas create-managed <slug> --name "<name>" --description "<description>"` first.');
+  }
 
   const shouldCreate = !isTruthyFlag(flags['no-create']);
   let createdPersona = false;
   let personaPayload = await findExistingManagedPersona(client, safeSlug);
-  if (!personaPayload) {
-    if (!shouldCreate) {
-      throw new Error(`Managed persona ${safeSlug} does not exist in Oomi. Remove --no-create or create it first.`);
-    }
-    if (!safeName) {
-      throw new Error('Persona name is required when creating a new managed persona.');
-    }
+  if (!personaPayload) {
+    if (!shouldCreate) {
+      throw new Error(`Managed persona ${safeSlug} does not exist in Oomi. Remove --no-create or create it first with \`oomi personas create-managed ${safeSlug} --name "<name>" --description "<description>"\`.`);
+    }
+    if (!safeName) {
+      throw new Error('Persona name is required when creating a new managed persona implicitly. Prefer running `oomi personas create-managed <slug> --name "<name>" --description "<description>"` first instead of relying on launch-managed auto-create.');
+    }
     personaPayload = await client.createManagedPersona({
       slug: safeSlug,
       name: safeName,

package/lib/personaRuntimeProcess.js

@@ -54,6 +54,7 @@ const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
     shouldReplace: (content) =>
       !content.includes('WEBSPATIAL_FORK_REPOSITORY') ||
       !content.includes('configurePersonaScene') ||
+      !content.includes('"--xr-back": String(back)') ||
       content.includes('WEBSPATIAL_FORK_COMMIT = "b2746721e4fe6b4f86dac0ea55938074eea00cda"') ||
       content.includes('WEBSPATIAL_FORK_COMMIT = "8904ac8fec48fe49ee14d1739237bd1afb2894fe"'),
   },
@@ -67,20 +68,22 @@ const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
   {
     relativePath: path.join('src', 'App.tsx'),
     shouldReplace: (content) =>
+      !content.includes('const isSpatialRuntime = __XR_ENV_BASE__.startsWith("/webspatial/avp");') ||
+      !content.includes('<Route path="home" element={<HomePage />} />') ||
       content.includes('<Route path="/" element={<HomePage />} />') ||
-      content.includes('<Route path="/scene" element={<ScenePage />} />'),
+      content.includes('<Route path="/scene" element={<ScenePage />} />') ||
+      content.includes('<Route index element={<HomePage />} />'),
   },
   {
     relativePath: path.join('src', 'pages', 'HomePage.tsx'),
     shouldReplace: (content) =>
       (content.includes('Open Spatial Scene') &&
       content.includes('Open Scene Route')) ||
-      (content.includes('Launch Spatial Surface') &&
-      content.includes('Open Browser Preview') &&
-      content.includes('Focused surface') &&
-      !content.includes('sceneMode')) ||
-      content.includes('enable-xr-monitor={sceneMode || undefined}') ||
-      content.includes('enable-xr={sceneMode || undefined}') ||
+      content.includes('sceneMode') ||
+      content.includes('configurePersonaScene();') ||
+      content.includes('persona-preview-card') ||
+      content.includes('Launch Spatial Surface') ||
+      content.includes('Open Spatial Preview') ||
       (
         content.includes('persona-panel persona-runtime" enable-xr') ||
         content.includes('persona-button" onClick={openPersonaScene} enable-xr') ||
@@ -91,6 +94,7 @@ const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
   {
     relativePath: path.join('src', 'pages', 'ScenePage.tsx'),
     shouldReplace: (content) =>
+      content.includes('sceneMode') ||
       (
         !content.includes('enable-xr-monitor') &&
         content.includes(
@@ -103,14 +107,23 @@ const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
         content.includes('Fork-backed proof points')
       ),
   },
+  {
+    relativePath: path.join('src', 'index.css'),
+    shouldReplace: (content) =>
+      !content.includes('html.is-spatial #root') ||
+      content.includes('radial-gradient(circle at top, rgba(205, 183, 143, 0.32), transparent 36%)'),
+  },
   {
     relativePath: path.join('src', 'App.css'),
     shouldReplace: (content) =>
+      content.includes('.persona-shell') ||
       (content.includes('.scene-panel') && !content.includes('.scene-interaction-grid')) ||
       content.includes('html.is-spatial .persona-runtime {') ||
       content.includes('html.is-spatial .persona-scene-root {') ||
       content.includes('html.is-spatial .persona-button,') ||
-      content.includes('html.is-spatial .persona-card,'),
+      content.includes('html.is-spatial .persona-card,') ||
+      !content.includes('.scene-workspace-grid') ||
+      !content.includes('.home-grid'),
   },
   {
     relativePath: 'vite.config.ts',

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.48",
+  "version": "0.2.50",
   "author": "Oomi",
   "license": "MIT",
   "openclawVersion": ">=0.5.0",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.48",
-  "description": "Oomi OpenClaw channel plugin and bridge tooling",
+  "version": "0.2.50",
+  "description": "Managed Oomi chat, voice bridge, and XR-first persona scaffolding for OpenClaw",
   "bin": {
     "oomi": "bin/oomi-ai.js"
   },
@@ -29,14 +29,19 @@
       "defaultChoice": "npm"
     }
   },
-  "keywords": [
-    "oomi",
-    "openclaw",
-    "cli",
-    "voice",
-    "agent"
-  ],
-  "homepage": "https://oomi.ai",
+  "keywords": [
+    "oomi",
+    "openclaw",
+    "cli",
+    "plugin",
+    "voice",
+    "agent",
+    "persona",
+    "webspatial",
+    "xr",
+    "androidxr"
+  ],
+  "homepage": "https://www.oomi.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/crispcode-io/oomi.git",