oomi-ai 0.2.49 → 0.2.50

package/README.md

@@ -299,22 +299,23 @@ oomi personas scaffold market-analyst --name "Market Analyst" --description "Pri
 
 Use:
 - `oomi personas create <id>` only for repo-local manifest work, not for the normal managed Oomi persona flow
-- `oomi personas create-managed --name "Cooking Persona" --description "Private cooking workspace"` for the end-to-end Oomi-managed 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
-
-Additional persona runtime commands:
-
-```bash
-oomi personas launch-managed market-analyst --name "Market Analyst" --description "Private app for reviewing my broker positions and risk."
+
+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 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."
+oomi persona-jobs fail pj_123 --code JOB_FAILED --message "Scaffold generation failed."
 ```
 
 Notes:
@@ -324,16 +325,83 @@ Notes:
 - 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.
 
-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:
+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

package/agent_instructions.md

@@ -203,12 +203,29 @@ For persona app work, treat the scaffold as a runtime contract, not a disposable
 
 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. If you need to inspect or repair runtime registration manually, prefer `oomi personas launch-managed <slug>` or `oomi openclaw refresh` before dropping to low-level callbacks.
+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:
 
@@ -221,11 +238,12 @@ When generating a managed persona app for Oomi:
 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, start the app and register the runtime with Oomi using the current runtime contract.
-11. For normal OpenClaw-hosted persona apps on the same LAN, the runtime registration contract is:
+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:
 
@@ -246,7 +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. 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.
-5. If you must pass `--endpoint` explicitly, it must be the LAN-reachable host or a relay URL, not `127.0.0.1`.
+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

@@ -262,11 +262,11 @@ Commands:
   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 a managed persona in Oomi and enqueue its build job for the linked device.
+    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.
-  personas scaffold <slug>
-    Create an Oomi-managed persona app scaffold for agent customization.
+    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. Prefer --local-port so the CLI can derive a reachable endpoint.
+    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. Prefer --local-port so the CLI can derive a reachable endpoint.
+    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/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.49",
+  "version": "0.2.50",
   "description": "Managed Oomi chat, voice bridge, and XR-first persona scaffolding for OpenClaw",
   "bin": {
     "oomi": "bin/oomi-ai.js"

package/templates/persona-app/README.md

@@ -33,13 +33,24 @@ The scaffold is considered healthy only when all of the following stay true:
 - Manifest: `/manifest.webmanifest`
 - Default dev port: `4789`
 
-## Local Development
-
+## Local Development
+
 ```bash
 npm install
 npm run dev:avp
 ```
 
+## Managed Launch Contract
+
+This scaffold is meant to be launched through the managed Oomi flow, not as an ad hoc dev server:
+
+- scaffold the workspace with `oomi personas scaffold`
+- create the backend record with `oomi personas create-managed`
+- launch and register through `oomi personas launch-managed`
+- verify `.oomi/runtime.json`, `oomi personas status --json`, and `oomi personas heartbeat --json`
+
+Do not replace that flow with `npm run dev` when reporting persona creation success back to Oomi.
+
 ## Notes
 
 - Preserve the WebSpatial/Vite shell, the runtime metadata files in `public/`, and the XR-specific route split between browser and scene modes.

package/templates/persona-app/src/persona/notes.ts

@@ -5,5 +5,6 @@ export const personaNotes = [
   "Keep using the vendored AndroidXR-enabled WebSpatial fork instead of switching back to the stock npm packages.",
   "Author multiple meaningful surfaces with explicit enable-xr, --xr-back, and --xr-background-material values so the app reads as spatial instead of one captured webpage.",
   "Keep html.is-spatial shell styles transparent so the host recedes and the panels carry the visual material.",
+  "Keep the managed runtime compatible with `oomi personas launch-managed`; do not require manual npm run dev for Oomi to consider the persona live.",
   "Do not remove public/oomi.runtime.json, public/oomi.health.json, or public/manifest.webmanifest.",
 ];