oomi-ai 0.2.17 → 0.2.19

package/README.md

@@ -2,227 +2,270 @@
 
 OpenClaw channel plugin and bridge tooling for Oomi managed chat and voice.
 
-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
-
-## 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 And Upgrade
-
-Global install:
-
-```bash
-pnpm add -g oomi-ai@latest
-```
-
-Fallback:
-
-```bash
-npm install -g oomi-ai@latest
-```
-
-Install the OpenClaw plugin:
-
-```bash
-openclaw plugins install oomi-ai@latest
-```
-
-Upgrade an existing machine:
-
-```bash
-pnpm add -g oomi-ai@latest
-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
-
-Fast-path install flow:
-
-```bash
-oomi openclaw pair --app-url https://www.oomi.ai --no-start
-openclaw plugins install oomi-ai@latest
-oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai
-```
-
-Then apply the printed `channels.oomi.accounts.default` config and restart OpenClaw.
-
-## Configuration
-
-OpenClaw channel config lives under:
+## Current Focus
 
-```json
-{
-  "channels": {
-    "oomi": {
-      "defaultAccountId": "default",
-      "accounts": {
-        "default": {
-          "backendUrl": "https://api.oomi.ai",
-          "deviceToken": "...",
-          "defaultSessionKey": "agent:main:webchat:channel:oomi",
-          "requestTimeoutMs": 15000
-        }
-      }
-    }
-  }
-}
-```
-
-Required fields:
-- `backendUrl`
-- `deviceToken`
-
-Optional fields:
-- `defaultSessionKey`
-- `requestTimeoutMs`
+`0.2.19` adds the first live persona automation lane:
+- 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
+- end-to-end local persona startup from a structured orchestration payload
 
+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
+
+## 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 And Upgrade
+
+Global install:
+
+```bash
+pnpm add -g oomi-ai@latest
+```
+
+Fallback:
+
+```bash
+npm install -g oomi-ai@latest
+```
+
+Install the OpenClaw plugin:
+
+```bash
+openclaw plugins install oomi-ai@latest
+```
+
+Upgrade an existing machine:
+
+```bash
+pnpm add -g oomi-ai@latest
+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
+
+Fast-path install flow:
+
+```bash
+oomi openclaw pair --app-url https://www.oomi.ai --no-start
+openclaw plugins install oomi-ai@latest
+oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai
+```
+
+Then apply the printed `channels.oomi.accounts.default` config and restart OpenClaw.
+
+## Configuration
+
+OpenClaw channel config lives under:
+
+```json
+{
+  "channels": {
+    "oomi": {
+      "defaultAccountId": "default",
+      "accounts": {
+        "default": {
+          "backendUrl": "https://api.oomi.ai",
+          "deviceToken": "...",
+          "defaultSessionKey": "agent:main:webchat:channel:oomi",
+          "requestTimeoutMs": 15000
+        }
+      }
+    }
+  }
+}
+```
+
+Required fields:
+- `backendUrl`
+- `deviceToken`
+
+Optional fields:
+- `defaultSessionKey`
+- `requestTimeoutMs`
+
 ## Runtime Model
 
 There are two runtime contracts worth understanding.
-
-### Managed Text Chat
-
-Managed text chat uses the OpenClaw channel extension and the Oomi backend channel API.
-This path is the more stable contract and should be preferred when evaluating the plugin for normal chat.
-
-### Device-Backed Chat And Voice
-
-Device-backed chat and voice use the local bridge.
-That bridge:
-- keeps a broker socket open to Oomi
-- opens local gateway sessions on demand
-- enforces `connect`-first request ordering
-- preserves or synthesizes `idempotencyKey` for `chat.send`
-- keeps voice-session faults from poisoning normal provider health where possible
-
-This is the part of the package most likely to matter when debugging voice turn failures.
-
+
+### Managed Text Chat
+
+Managed text chat uses the OpenClaw channel extension and the Oomi backend channel API.
+This path is the more stable contract and should be preferred when evaluating the plugin for normal chat.
+
+### Device-Backed Chat And Voice
+
+Device-backed chat and voice use the local bridge.
+That bridge:
+- keeps a broker socket open to Oomi
+- opens local gateway sessions on demand
+- enforces `connect`-first request ordering
+- preserves or synthesizes `idempotencyKey` for `chat.send`
+- keeps voice-session faults from poisoning normal provider health where possible
+
+This is the part of the package most likely to matter when debugging voice turn failures.
+
 For managed voice replies, the extension also preserves an explicit hidden `metadata.spoken` sidecar when upstream provides one.
 If upstream does not provide one, the extension now synthesizes a bounded hidden fallback from the visible assistant text so backend TTS can speak a cleaner and more varied version without changing user-visible chat.
 
-## Bridge Health States
-
-The bridge status file is written locally and should roughly be interpreted as:
-- `starting`: process booting or waiting for managed subscription
-- `connected`: broker connected and managed subscription confirmed
-- `reconnecting`: broker or gateway transport dropped and reconnect is scheduled
-- `degraded`: bridge is still alive but hit a runtime fault that needs attention
-- `error`: startup or auth-level failure that prevents useful operation
-- `stopped`: bridge is not running or was intentionally stopped
-
-For voice support, a `voice_session_*` failure should be treated as narrower than a full provider outage.
+## Persona Scaffolding
 
-## Troubleshooting
+Use the scaffold flow when OpenClaw needs to build a managed persona app that will live inside Oomi:
 
-### `invalid handshake: first request must be connect`
-
-Meaning:
-- a gateway request was forwarded before the session had accepted `connect`
-
-What to check:
-- update to the latest `oomi-ai`
-- restart the bridge worker
-- confirm only one active bridge worker exists for the device
-
-### `duplicate plugin id detected`
-
-Meaning:
-- OpenClaw can see more than one `oomi-ai` plugin source
-
-What to check:
-- ensure there is only one active install under OpenClaw plugin discovery paths
-- remove stale local extension copies before reinstalling
-
-### Bridge keeps flipping between `reconnecting`, `degraded`, or `stopped`
-
-What to check:
-- `oomi openclaw bridge ps`
-- `oomi openclaw bridge service status`
-- `tail -f ~/.openclaw/logs/oomi-bridge-live.log`
-- `tail -f ~/.openclaw/logs/gateway.log`
-
-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
-
-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/`
-
-## Developer Notes
+```bash
+oomi personas scaffold market-analyst --name "Market Analyst" --description "Private app for reviewing my broker positions and risk." --out ~/.openclaw/personas/market-analyst
+```
 
-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
-  - hidden managed-voice speech metadata forwarding, with a synthesized fallback when upstream does not provide `metadata.spoken`
+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
 
-If you are developing the plugin, test the packaged surface with:
+Additional persona runtime commands:
 
 ```bash
-cd packages/oomi-ai
-node --test test/*.test.mjs
-npm pack --dry-run
+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."
 ```
 
-## Release Process
-
-Before publishing:
+Recommended agent flow:
 
 ```bash
-cd packages/oomi-ai
-node --test test/*.test.mjs
-npm pack --dry-run
+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.
+
+## Bridge Health States
+
+The bridge status file is written locally and should roughly be interpreted as:
+- `starting`: process booting or waiting for managed subscription
+- `connected`: broker connected and managed subscription confirmed
+- `reconnecting`: broker or gateway transport dropped and reconnect is scheduled
+- `degraded`: bridge is still alive but hit a runtime fault that needs attention
+- `error`: startup or auth-level failure that prevents useful operation
+- `stopped`: bridge is not running or was intentionally stopped
+
+For voice support, a `voice_session_*` failure should be treated as narrower than a full provider outage.
+
+## Troubleshooting
+
+### `invalid handshake: first request must be connect`
+
+Meaning:
+- a gateway request was forwarded before the session had accepted `connect`
+
+What to check:
+- update to the latest `oomi-ai`
+- restart the bridge worker
+- confirm only one active bridge worker exists for the device
+
+### `duplicate plugin id detected`
+
+Meaning:
+- OpenClaw can see more than one `oomi-ai` plugin source
+
+What to check:
+- ensure there is only one active install under OpenClaw plugin discovery paths
+- remove stale local extension copies before reinstalling
+
+### Bridge keeps flipping between `reconnecting`, `degraded`, or `stopped`
+
+What to check:
+- `oomi openclaw bridge ps`
+- `oomi openclaw bridge service status`
+- `tail -f ~/.openclaw/logs/oomi-bridge-live.log`
+- `tail -f ~/.openclaw/logs/gateway.log`
+
+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
+
+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/`
+
+## 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
+  - hidden managed-voice speech metadata forwarding, with a synthesized fallback when upstream does not provide `metadata.spoken`
+
+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
+```
+
+## Release Process
+
+Before publishing:
+
+```bash
+cd packages/oomi-ai
+node --test test/*.test.mjs
+npm pack --dry-run
+```
+
 Then publish the bumped version:
 
 ```bash
-npm publish --access public
+pnpm check
+pnpm publish --dry-run --no-git-checks --access public
+pnpm publish --access public
 ```