oomi-ai 0.2.28 → 0.2.38

package/README.md

@@ -1,19 +1,26 @@
-# oomi-ai
-
-OpenClaw channel plugin and bridge tooling for Oomi managed chat and voice.
-
-## Current Focus
-
-`0.2.28` keeps the persona automation lane and adds a usable local managed-voice validation path:
-- WebSpatial-based persona scaffolding for generated Oomi apps
-- a high-level `oomi personas create-managed` command for agent-driven persona creation
-- 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:
+# oomi-ai
+
+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`
+- 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
 
@@ -122,9 +129,9 @@ Optional fields:
 - `defaultSessionKey`
 - `requestTimeoutMs`
 
-## Runtime Model
-
-There are two runtime contracts worth understanding.
+## Runtime Model
+
+There are two runtime contracts worth understanding.
 
 ### Managed Text Chat
 
@@ -143,84 +150,189 @@ That bridge:
 
 This is the part of the package most likely to matter when debugging voice turn failures.
 
-For managed cloned-voice replies, the canonical contract is:
-- visible assistant `content` stays user-facing
-- hidden `metadata.spoken` carries the backend TTS payload
-- the shared helper in `lib/spokenMetadata.js` is used by both the extension and the local bridge to preserve or normalize that sidecar before it reaches the backend
-
-The backend cloned-voice path is intentionally strict. If `metadata.spoken` does not reach Oomi, backend TTS fails instead of speaking a flat fallback voice.
-
-## Local TTS Validation
-
-If you are developing this package inside the Oomi repo, you can now validate the managed voice path locally before publishing.
-
-This local gate does three things:
-- replays an assistant `chat.final` frame through the same spoken-metadata normalization path used by the OpenClaw extension and the bridge
-- feeds that normalized frame into the Rails backend replay harness
-- optionally calls the real Qwen cloned-voice provider and confirms that audio deltas come back
-
-Important:
-- this is a repo developer workflow, not a generic npm-only operator command
-- it expects the Oomi repo checkout, the Rails backend, and local provider env vars
-- the real-provider replay can auto-enroll a disposable default sample voice profile from `assets/voice/source/nemu-enrollment-sample.mp3`
-
-Assistant-final contract only:
-
-```bash
-oomi openclaw debug assistant-final --text "Hey Justin! How is the testing going?" --json
-```
-
-Full local backend replay:
-
-```bash
-oomi openclaw debug tts-pipeline --text "When your voice reaches me, it gets turned into text, I read it and think about it, then I speak back through the managed chat session." --json
+For managed cloned-voice replies, the canonical contract is:
+- visible assistant `content` stays user-facing
+- hidden `metadata.spoken` carries the backend TTS payload
+- the shared helper in `lib/spokenMetadata.js` is used by both the extension and the local bridge to preserve or normalize that sidecar before it reaches the backend
+
+The backend cloned-voice path is intentionally strict. If `metadata.spoken` does not reach Oomi, backend TTS fails instead of speaking a flat fallback voice.
+
+## Bridge Logging
+
+The bridge is intentionally quiet by default in production so normal deploys do not spam logs with frame-level transport noise.
+
+To enable verbose bridge tracing temporarily, set:
+
+```bash
+OOMI_BRIDGE_DEBUG=1
+```
+
+With that flag enabled, the bridge will emit low-level session, frame, and spoken-metadata debug logs again.
+
+## Local TTS Validation
+
+If you are developing this package inside the Oomi repo, you can now validate the managed voice path locally before publishing.
+
+This local gate does three things:
+- replays an assistant `chat.final` frame through the same spoken-metadata normalization path used by the OpenClaw extension and the bridge
+- feeds that normalized frame into the Rails backend replay harness
+- optionally calls the real Qwen cloned-voice provider and confirms that audio deltas come back
+
+Important:
+- this is a repo developer workflow, not a generic npm-only operator command
+- it expects the Oomi repo checkout, the Rails backend, and local provider env vars
+- the real-provider replay can auto-enroll a disposable default sample voice profile from `assets/voice/source/nemu-enrollment-sample.mp3`
+
+Assistant-final contract only:
+
+```bash
+oomi openclaw debug assistant-final --text "Hey Justin! How is the testing going?" --json
+```
+
+Full local backend replay:
+
+```bash
+oomi openclaw debug tts-pipeline --text "When your voice reaches me, it gets turned into text, I read it and think about it, then I speak back through the managed chat session." --json
+```
+
+Real Qwen provider replay:
+
+```bash
+oomi openclaw debug tts-pipeline --text "When your voice reaches me, it gets turned into text, I read it and think about it, then I speak back through the managed chat session." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
+```
+
+What a good result looks like:
+- `backend.success = true`
+- `managed.assistantSpeechFinal.present = true`
+- `qwen.errorCode = null`
+- `qwen.audioDeltaCount > 0` when `--live-provider` is used
+
+This is the preferred pre-publish gate for managed voice regressions, because it is much faster than publishing to npm and testing through a live OpenClaw machine first.
+
+## Local OpenClaw Dev Harness
+
+For plugin/runtime work, the preferred pre-publish loop is:
+
+1. run the repo-local CLI directly from source
+2. run the same flow inside the Dockerized OpenClaw dev harness using a local packed tarball
+3. only then update a real OpenClaw machine
+
+Fast source smoke from the repo checkout:
+
+```bash
+node packages/oomi-ai/bin/oomi-ai.js openclaw debug persona-runtime --name "Chef Dev" --json
+```
+
+Containerized real-runtime smoke:
+
+```bash
+docker compose -f docker/openclaw-dev/compose.yml build openclaw-dev
+docker compose -f docker/openclaw-dev/compose.yml up -d openclaw-dev
+docker compose -f docker/openclaw-dev/compose.yml exec -T openclaw-dev openclaw gateway health --url ws://127.0.0.1:18789 --token dev-gateway-token --json
+docker compose -f docker/openclaw-dev/compose.yml exec -T openclaw-dev oomi-local openclaw debug persona-runtime --name "Chef Dev" --json
 ```
 
-Real Qwen provider replay:
+The local managed-chat smoke uses a dedicated session key separate from the browser shell so repeated sentinel prompts do not leak into the interactive conversation history.
+
+`oomi-local` is a deterministic container wrapper that executes the installed packed `oomi-ai` artifact directly with Node. In the Docker harness, it is only the package wrapper. The agent itself is the real OpenClaw runtime running in the foreground.
+
+Shared profile contract smoke:
+
+```bash
+node packages/oomi-ai/bin/oomi-ai.js openclaw profile init --profile-id oomi-dev-local --label "Oomi Local Dev" --backend-url http://127.0.0.1:3001 --device-token dev-device-token --json
+node packages/oomi-ai/bin/oomi-ai.js openclaw profile apply --profile ~/.openclaw/oomi-openclaw-profile.json --openclaw-home ~/.openclaw --json
+```
+
+What the harness does:
+
+- bootstraps an isolated OpenClaw home rooted at `HOME/.openclaw`
+- runs `openclaw onboard --non-interactive ...`
+- writes and applies `HOME/.openclaw/oomi-dev-profile.json` using the same shared profile contract the future onboarding UI and hosted-agent bootstrap should use
+- enables the Oomi channel account through that applied profile and relies on local OpenClaw plugin auto-discovery for the installed `oomi-ai` plugin
+- writes device identity material used by the `oomi-ai` bridge tooling
+- packs the local `packages/oomi-ai` checkout into a `.tgz`
+- installs that tarball globally in the container
+- installs the same tarball as a real OpenClaw plugin
+- defaults model auth to `oomi-managed` so onboarding/bootstrap does not require end-user provider keys
+- runs `openclaw gateway` as the foreground container process
+
+Useful env overrides for local integration:
 
-```bash
-oomi openclaw debug tts-pipeline --text "When your voice reaches me, it gets turned into text, I read it and think about it, then I speak back through the managed chat session." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
-```
+- `OOMI_DEV_BACKEND_URL`
+- `OOMI_DEV_DEVICE_TOKEN`
+- `OOMI_DEV_MODEL_AUTH_MODE`
+- `OPENCLAW_GATEWAY_TOKEN`
+- `OPENCLAW_GATEWAY_PASSWORD`
 
-What a good result looks like:
-- `backend.success = true`
-- `managed.assistantSpeechFinal.present = true`
-- `qwen.errorCode = null`
-- `qwen.audioDeltaCount > 0` when `--live-provider` is used
+Recommended local modes:
 
-This is the preferred pre-publish gate for managed voice regressions, because it is much faster than publishing to npm and testing through a live OpenClaw machine first.
+- onboarding/runtime checks without provider keys
+  - `OOMI_DEV_MODEL_AUTH_MODE=oomi-managed`
+- internal real-response smoke before publish
+  - `OPENROUTER_API_KEY=...`
+  - optional explicit override: `OOMI_DEV_MODEL_AUTH_MODE=provider-env`
 
-## Persona Scaffolding
+The default container config is intentionally safe for onboarding and runtime testing. It does not require a published npm version, and it does not require end-user provider keys.
 
-Use the scaffold flow when OpenClaw needs to build a managed persona app that will live inside Oomi:
+To make the Dockerized OpenClaw runtime actually answer managed chat locally today, add this to the repo `.env.local`:
 
 ```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_DEV_MODEL_AUTH_MODE=provider-env
+OPENROUTER_API_KEY=<your-openrouter-key>
 ```
 
-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
+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:
+
+```bash
+oomi personas scaffold market-analyst --name "Market Analyst" --description "Private app for reviewing my broker positions and risk." --out ~/.openclaw/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."
+oomi personas status market-analyst
+oomi personas stop market-analyst
+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 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.
+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 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:
+
+```bash
+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
 
 ## Bridge Health States
 
@@ -234,7 +346,7 @@ The bridge status file is written locally and should roughly be interpreted as:
 
 For voice support, a `voice_session_*` failure should be treated as narrower than a full provider outage.
 
-## Troubleshooting
+## Troubleshooting
 
 ### `invalid handshake: first request must be connect`
 
@@ -265,32 +377,32 @@ What to check:
 
 If the process is alive but runtime faults are being caught, expect `degraded` rather than an immediate hard stop.
 
-### Voice STT works but the agent does not answer
+### Voice STT works but the agent does not answer
 
 This usually means one of these:
 - the managed gateway/device side is not actually ready
 - the bridge or agent run failed after delivery
 - the OpenClaw run stopped with an upstream provider `network_error`
 
-In that situation, inspect:
-- `~/.openclaw/logs/gateway.log`
-- `~/.openclaw/logs/gateway.err.log`
-- the relevant session JSONL in `~/.openclaw/agents/main/sessions/`
-
-### Voice text works but cloned TTS fails with `MISSING_SPOKEN_METADATA`
-
-Meaning:
-- the assistant text arrived
-- the backend voice relay never received valid hidden `metadata.spoken`
-
-What to check:
-- run the local replay gate before publishing:
-  - `oomi openclaw debug assistant-final --text "..."`
-  - `oomi openclaw debug tts-pipeline --text "..."`
-- 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
+In that situation, inspect:
+- `~/.openclaw/logs/gateway.log`
+- `~/.openclaw/logs/gateway.err.log`
+- the relevant session JSONL in `~/.openclaw/agents/main/sessions/`
+
+### Voice text works but cloned TTS fails with `MISSING_SPOKEN_METADATA`
 
-## Developer Notes
+Meaning:
+- the assistant text arrived
+- the backend voice relay never received valid hidden `metadata.spoken`
+
+What to check:
+- run the local replay gate before publishing:
+  - `oomi openclaw debug assistant-final --text "..."`
+  - `oomi openclaw debug tts-pipeline --text "..."`
+- 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
@@ -301,44 +413,44 @@ If you are inspecting this package on npm, the main architectural points are:
   - `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
+  - one shared hidden managed-voice speech metadata helper used by both the extension and the local bridge
 
-If you are developing the plugin, test the packaged surface with:
-
-```bash
-cd packages/oomi-ai
-node --test test/*.test.mjs
-npm pack --dry-run
-```
-
-For managed voice changes, do not stop at the package tests. Run the local replay gate from the repo root as well, especially before publishing:
-
-```bash
-oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --json
-oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
-```
-
-## Release Process
-
-Before publishing:
-
-```bash
-cd packages/oomi-ai
-node --test test/*.test.mjs
-npm pack --dry-run
-```
-
-For voice-related changes, also run the repo-backed local replay gate before publish:
-
-```bash
-oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --json
-oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
-```
-
-Then publish the bumped version:
-
-```bash
-pnpm check
-pnpm publish --dry-run --no-git-checks --access public
-pnpm publish --access public
-```
+If you are developing the plugin, test the packaged surface with:
+
+```bash
+cd packages/oomi-ai
+node --test test/*.test.mjs
+npm pack --dry-run
+```
+
+For managed voice changes, do not stop at the package tests. Run the local replay gate from the repo root as well, especially before publishing:
+
+```bash
+oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --json
+oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
+```
+
+## Release Process
+
+Before publishing:
+
+```bash
+cd packages/oomi-ai
+node --test test/*.test.mjs
+npm pack --dry-run
+```
+
+For voice-related changes, also run the repo-backed local replay gate before publish:
+
+```bash
+oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --json
+oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
+```
+
+Then publish the bumped version:
+
+```bash
+pnpm check
+pnpm publish --dry-run --no-git-checks --access public
+pnpm publish --access public
+```