oomi-ai 0.2.12 → 0.2.14

package/README.md

@@ -1,148 +1,224 @@
 # oomi-ai
 
-CLI to install Oomi agent instructions and skills into OpenClaw, plus sync personas to the Oomi backend registry.
+OpenClaw channel plugin and bridge tooling for Oomi managed chat and voice.
 
-## Install
-```
-pnpm add -g oomi-ai
+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
 ```
-npm install -g oomi-ai
+
+Install the OpenClaw plugin:
+
+```bash
+openclaw plugins install oomi-ai@latest
 ```
 
-## Usage
+Upgrade an existing machine:
 
-Install as an OpenClaw channel extension (preferred architecture):
+```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
+        }
+      }
+    }
+  }
+}
 ```
 
-This package now ships an OpenClaw channel plugin (`openclaw.plugin.json`) with channel id `oomi`.
-Channel account config fields (`channels.oomi.accounts.<accountId>`):
+Required fields:
 - `backendUrl`
 - `deviceToken`
-- `defaultSessionKey` (optional, default `agent:main:webchat:channel:oomi`)
-- `requestTimeoutMs` (optional)
 
-Print plugin install/config guidance from local pair state:
-```
-oomi openclaw plugin
-```
+Optional fields:
+- `defaultSessionKey`
+- `requestTimeoutMs`
 
-Install agent instructions only:
-```
-oomi init
-```
+## Runtime Model
 
-Install agent instructions + Oomi skill:
-```
-oomi openclaw install
-```
+There are two runtime contracts worth understanding.
 
-Pair and provision device token from Oomi web backend:
-```
-oomi openclaw pair --app-url https://your-oomi-app.vercel.app --device-id my-openclaw-mac --no-start
-```
+### Managed Text Chat
 
-`--app-url` must be reachable from the OpenClaw host. If OpenClaw runs on a different machine/network, do not use `localhost` unless tunneled.
+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.
 
-This prints:
-- `Auth invite URL: https://.../connect/<single-use-token>`
-- A copy-ready block for the user:
-  - `Oomi Connect Ready`
-  - `Auth Link: ...`
+### Device-Backed Chat And Voice
 
-If you need a fresh auth link later (without re-pairing), run:
-```
-oomi openclaw invite --app-url https://your-oomi-app.vercel.app
-```
+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
 
-Bridge lifecycle handler (singleton, one bridge per host/device):
-```
-oomi openclaw bridge ensure --detach   # start if needed; no-op if already running
-oomi openclaw bridge ps                # list bridge pids
-oomi openclaw bridge stop              # stop all bridge workers
-oomi openclaw bridge restart --detach  # clean restart as background worker
-tail -f ~/.openclaw/logs/oomi-bridge-live.log  # detached bridge logs
-```
-`oomi openclaw bridge --detach` is equivalent to `oomi openclaw bridge start --detach`.
+This is the part of the package most likely to matter when debugging voice turn failures.
 
-macOS launchd supervision (recommended for durability):
-```
-oomi openclaw bridge service install      # install + start service
-oomi openclaw bridge service status
-oomi openclaw bridge service restart
-oomi openclaw bridge service stop
-oomi openclaw bridge service uninstall
-```
-Optional: `oomi openclaw bridge service install --no-start` to install without starting.
-
-Agent-intent mapping (recommended):
-- If user says `Connect yourself to Oomi. Use app URL https://www.oomi.ai.`
-- Run:
-  - `curl -fsSL https://www.oomi.ai/install.sh | bash`
-  - or `pnpm add -g oomi-ai@latest` (`npm install -g oomi-ai@latest` fallback)
-  - `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`
-  - Apply `channels.oomi.accounts.default` config and restart OpenClaw.
-
-Important distinction:
-- `pairCode` is one-time and used internally by the pair/bootstrap flow.
-- Invite auth links are the required user flow.
-- Managed chat connect now uses OpenClaw challenge auth (`connect.challenge` nonce + signed device payload) in the local bridge path.
-
-Sync personas from the repo into the backend registry:
-```
-oomi personas sync --backend-url http://localhost:3001
-```
+## Bridge Health States
 
-Create a new persona (and sync it):
-```
-oomi personas create chef --name "Oomi Chef" --summary "Cooking ideas and nutrition guidance"
-```
+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
 
-Optional flags:
-```
-oomi init --workspace /path/to/openclaw/workspace
-oomi init --agents-file /path/to/AGENTS.md
-oomi openclaw install --skills-dir /path/to/openclaw/skills
-oomi openclaw pair --app-url https://your-oomi-app.vercel.app --no-start
-oomi openclaw pair --app-url https://your-oomi-app.vercel.app --json
-oomi personas sync --root /path/to/oomi
-oomi personas create creator --status active --chat-session agent:main:webchat:channel:oomi-creator
-```
+For voice support, a `voice_session_*` failure should be treated as narrower than a full provider outage.
 
-Defaults:
-- Agent instructions are written to `$OPENCLAW_WORKSPACE/AGENTS.md` (if set), otherwise `~/.openclaw/workspace/AGENTS.md`.
-- Skills are installed to `~/.openclaw/skills` and `~/clawd/skills` if present.
-
-Restart OpenClaw after running `oomi init` or `oomi openclaw install`.
-
-## Update Notifications
-- `oomi` checks npm for a newer `oomi-ai` version on normal commands (cached, best-effort).
-- When an update is available it prints:
-  - `pnpm add -g oomi-ai@latest`
-  - fallback: `npm install -g oomi-ai@latest`
-- Optional env controls:
-  - `OOMI_SKIP_UPDATE_CHECK=1` disables checks
-  - `OOMI_UPDATE_CHECK_INTERVAL_MS=<ms>` changes check interval
-  - `OOMI_UPDATE_CHECK_TIMEOUT_MS=<ms>` changes network timeout
-  - `OOMI_BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS=<ms>` changes local gateway socket connect timeout
-  - `OOMI_BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS=<ms>` changes wait timeout for gateway `connect.challenge` nonce
-  - `OOMI_BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS=<ms>` changes timeout for forwarded gateway `connect`/`chat.send` request responses
-
-Bridge alert helper (reads `~/.openclaw/oomi-bridge-status.json` counters):
-```
-node <repo-root>/scripts/openclaw/bridge-alert-check.mjs
+## 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
+
+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
 ```
 
-## Package Audit + Publish (pnpm)
+## Release Process
+
+Before publishing:
+
+```bash
+cd packages/oomi-ai
+node --test test/*.test.mjs
+npm pack --dry-run
 ```
-cd <repo-root>/packages/oomi-ai
-pnpm check
-pnpm publish --dry-run --no-git-checks --access public
-pnpm publish --access public
+
+Then publish the bumped version:
+
+```bash
+npm publish --access public
 ```

package/agent_instructions.md

@@ -1,46 +1,156 @@
-# Oomi Avatar Control
+# Oomi OpenClaw Operator Guide
 
-Before using avatar commands, call `get_avatar_capabilities` and prefer canonical values.
-Inline tags are stripped from user-visible text.
+Use these instructions when you need to connect, repair, or verify an OpenClaw machine that should talk to Oomi.
 
-Use inline tags like:
-- [anim:Waving], [anim:Walking], [anim:Idle], [anim:Sitting Idle]
-- [face:happy], [face:sad], [face:surprised], [face:focused], [face:gentle], [face:thinking]
-- [gesture:nod], [gesture:think], [gesture:shrug], [gesture:wave], [gesture:bow]
-- [look:camera], [look:left], [look:right], [look:up], [look:down]
+## Primary Goal
 
-Aliases allowed (if needed): wave -> Waving, walk -> Walking, idle -> Idle, sit/sitting -> Sitting Idle
+Get OpenClaw into a state where:
+- Oomi managed text chat works
+- Oomi device-backed voice can start cleanly
+- the bridge is supervised or restartable
+- the user never has to paste raw pair identifiers or gateway secrets manually when managed connect is available
 
-## Oomi Connect Flow
+## Standard Connect Flow
 
-If the user asks to connect OpenClaw to Oomi voice/web:
+If the user asks to connect OpenClaw to Oomi chat or voice:
 
-1. Refresh bootstrap/update first:
+1. Refresh bootstrap first:
    - `curl -fsSL https://www.oomi.ai/install.sh | bash`
-2. Ensure `oomi-ai` is installed (`pnpm add -g oomi-ai@latest`).
-   - Fallback: `npm install -g oomi-ai@latest`
-3. Pair device token without starting legacy bridge:
+2. Ensure `oomi-ai` is installed:
+   - `pnpm add -g oomi-ai@latest`
+   - fallback: `npm install -g oomi-ai@latest`
+3. Pair the device without starting a legacy one-off flow:
    - `oomi openclaw pair --app-url https://www.oomi.ai --no-start`
-4. Install OpenClaw plugin:
+4. Install the OpenClaw plugin:
    - `openclaw plugins install oomi-ai@latest`
-5. Configure channel account (`channels.oomi.accounts.default`) from:
+5. Print the config block and secrets:
    - `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai`
-6. Restart OpenClaw.
-7. Ensure exactly one bridge worker is running (singleton handler):
+6. Apply the printed `channels.oomi.accounts.default` config.
+7. Restart OpenClaw.
+8. Start or repair the bridge:
    - `oomi openclaw bridge ensure --detach`
-   - If stale/disconnected: `oomi openclaw bridge restart --detach`
-   - On macOS, prefer supervised mode: `oomi openclaw bridge service install`
-8. If user provides an app URL (for example "Connect yourself to Oomi. Use app URL <URL>."):
-   - Use that URL directly in the pair command.
-   - Example: `oomi openclaw pair --app-url <URL> --no-start`
-9. Return this exact result format to the user:
-   - `Oomi Connect Ready`
-   - `Auth Link: ...`
-   - No extra narrative text before or after those lines.
-
-Primary UX requirement:
-- Never ask the user to enter raw pairing identifiers.
-- The user should open the auth link, complete sign-in, and land directly in connected chat.
-- Return `/connect/<invite-token>` auth links only.
-
-Do not ask users to paste gateway IP/token/password when managed connect is available.
+   - if stale: `oomi openclaw bridge restart --detach`
+   - on macOS, prefer supervision: `oomi openclaw bridge service install`
+
+If the user provides a specific app URL, use it directly in the pair flow:
+- `oomi openclaw pair --app-url <URL> --no-start`
+
+## Required User-Facing Result
+
+When pairing completes successfully, return this exact format:
+- `Oomi Connect Ready`
+- `Auth Link: ...`
+
+Do not add extra narrative before or after those lines.
+Do not ask the user to enter raw pair codes, gateway passwords, or nonce values manually.
+
+## Runtime Checks
+
+Use these commands to inspect the installed machine:
+
+```bash
+oomi openclaw bridge ps
+oomi openclaw bridge service status
+oomi openclaw status
+tail -f ~/.openclaw/logs/oomi-bridge-live.log
+tail -f ~/.openclaw/logs/gateway.log
+tail -f ~/.openclaw/logs/gateway.err.log
+```
+
+Useful local files:
+- `~/.openclaw/oomi-bridge-status.json`
+- `~/.openclaw/logs/oomi-bridge-live.log`
+- `~/.openclaw/logs/gateway.log`
+- `~/.openclaw/logs/gateway.err.log`
+- `~/.openclaw/agents/main/sessions/*.jsonl`
+
+## Healthy State
+
+Treat the machine as healthy when all of the following are true:
+- OpenClaw loads the `oomi-ai` plugin without duplicate-id conflicts
+- `channels.oomi.accounts.default` is populated with a valid `backendUrl` and `deviceToken`
+- the bridge shows `connected` after managed subscription is confirmed
+- text chat reaches the Oomi assistant
+- voice STT can produce `asr.final`
+- assistant replies can come back without the bridge dropping into `stopped`
+
+Bridge status meanings:
+- `starting`: bridge booting or waiting for managed subscription
+- `connected`: ready for managed chat and voice traffic
+- `reconnecting`: transport dropped and retry is scheduled
+- `degraded`: bridge caught a runtime fault but is still alive
+- `error`: startup/auth failure blocked useful operation
+- `stopped`: not running or intentionally stopped
+
+## Troubleshooting
+
+### Duplicate plugin id warning
+
+Symptom:
+- OpenClaw reports `duplicate plugin id detected`
+
+Action:
+- ensure only one active `oomi-ai` plugin install is discoverable
+- remove stale extension copies before reinstalling
+
+### `invalid handshake: first request must be connect`
+
+Meaning:
+- a gateway request was sent before `connect` had been accepted
+
+Action:
+- update `oomi-ai`
+- restart the bridge
+- confirm only one bridge worker is running
+
+### Device is linked but voice start still fails
+
+Meaning:
+- linked ownership is not enough; the device side still needs to be live
+
+Action:
+- confirm the device websocket is actually online
+- confirm the bridge is `connected`
+- restart the bridge if it is stuck in `reconnecting` or `degraded`
+
+### STT works but the assistant does not reply
+
+Meaning:
+- the voice turn likely reached Oomi, but the managed gateway or OpenClaw run failed later
+
+Action:
+- inspect `gateway.log`, `gateway.err.log`, and the session JSONL
+- check for `network_error`, auth failures, or repeated bridge restarts
+
+### Bridge keeps restarting with `reason: stopped`
+
+Action:
+- confirm the newest `oomi-ai` is installed
+- inspect `~/.openclaw/logs/oomi-bridge-live.log` for runtime exceptions
+- use supervised mode on macOS: `oomi openclaw bridge service install`
+- if the process is alive but faulted, expect `degraded` rather than an immediate hard stop on newer bridge builds
+
+## Voice Notes
+
+Voice depends on the same Oomi plugin and bridge layer as managed chat.
+That means:
+- if plugin install or bridge health is wrong, voice replies will also fail
+- STT can succeed even when assistant reply delivery is broken later in the run
+- a `voice_session_*` failure should be investigated, but it should not automatically be treated as proof that all normal Oomi chat is down
+
+## Avatar Commands
+
+Before using avatar commands, call `get_avatar_capabilities` and prefer canonical values.
+Inline tags are stripped from user-visible text.
+
+Use inline tags like:
+- `[anim:Waving]`, `[anim:Walking]`, `[anim:Idle]`, `[anim:Sitting Idle]`
+- `[face:happy]`, `[face:sad]`, `[face:surprised]`, `[face:focused]`, `[face:gentle]`, `[face:thinking]`
+- `[gesture:nod]`, `[gesture:think]`, `[gesture:shrug]`, `[gesture:wave]`, `[gesture:bow]`
+- `[look:camera]`, `[look:left]`, `[look:right]`, `[look:up]`, `[look:down]`
+
+Aliases allowed if needed:
+- `wave -> Waving`
+- `walk -> Walking`
+- `idle -> Idle`
+- `sit` or `sitting -> Sitting Idle`

package/bin/oomi-ai.js

@@ -8,7 +8,7 @@ import net from 'net';
 import { lookup as dnsLookup } from 'dns/promises';
 import { fileURLToPath } from 'url';
 import WebSocket from 'ws';
-import { ensureSessionBridge, forwardFrameToSession, flushSessionQueue } from './sessionBridgeState.js';
+import { ensureSessionBridge, flushSessionQueue, flushWaitingForConnect, forwardFrameToSession } from './sessionBridgeState.js';
 
 const MARKER_START = '<oomi-agent-instructions>';
 const MARKER_END = '</oomi-agent-instructions>';
@@ -637,6 +637,59 @@ function updateBridgeStatus(partial) {
   return next;
 }
 
+function resolveBridgeStatusForBrokerOpen({ actionCableMode, deviceSubscribed }) {
+  if (!actionCableMode) {
+    return 'connected';
+  }
+  return deviceSubscribed ? 'connected' : 'starting';
+}
+
+function classifyBridgeSessionScope(sessionId) {
+  const normalized = String(sessionId || '').trim();
+  return normalized.startsWith('voice_session_') ? 'voice' : 'default';
+}
+
+function resolveBridgeStatusForRuntimeFault({ currentStatus, sessionId }) {
+  if (classifyBridgeSessionScope(sessionId) === 'voice') {
+    return currentStatus === 'connected' ? 'connected' : currentStatus || 'starting';
+  }
+  if (currentStatus === 'connected' || currentStatus === 'reconnecting' || currentStatus === 'degraded') {
+    return 'degraded';
+  }
+  return 'error';
+}
+
+function runBridgeCallbackSafely(callback, onError) {
+  return (...args) => {
+    try {
+      return callback(...args);
+    } catch (err) {
+      onError(err instanceof Error ? err : new Error(String(err)));
+      return undefined;
+    }
+  };
+}
+
+function createBridgeProcessFaultHandler({ readStatus, onReport, onExit }) {
+  return ({ phase, error }) => {
+    const normalizedError = error instanceof Error ? error : new Error(String(error || 'unknown process fault'));
+    const currentStatus = String(readStatus?.()?.status || '').trim();
+    const nextStatus = resolveBridgeStatusForRuntimeFault({ currentStatus, sessionId: '' });
+
+    onReport?.({
+      phase,
+      status: nextStatus,
+      error: normalizedError,
+      currentStatus,
+      shouldExit: nextStatus === 'error',
+    });
+
+    if (nextStatus === 'error') {
+      onExit?.(1);
+    }
+  };
+}
+
 function normalizeBridgeMetrics(value) {
   if (!value || typeof value !== 'object') return {};
   const next = {};
@@ -945,7 +998,64 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
 
   try {
     const frame = JSON.parse(frameText);
-    if (frame?.type !== 'req' || frame?.method !== 'connect') {
+    if (frame?.type !== 'req') {
+      return { frameText, waitForChallenge: false };
+    }
+    const method = typeof frame.method === 'string' ? frame.method.trim() : '';
+    if (!method) {
+      return { frameText, waitForChallenge: false };
+    }
+
+    if (method !== 'connect') {
+      const rawParams = frame.params && typeof frame.params === 'object' ? frame.params : {};
+      if (method === 'chat.send') {
+        const sanitized = {};
+        if (typeof rawParams.sessionKey === 'string' && rawParams.sessionKey.trim()) {
+          sanitized.sessionKey = rawParams.sessionKey.trim();
+        }
+        if (typeof rawParams.message === 'string') {
+          sanitized.message = rawParams.message;
+        }
+        if (typeof rawParams.thinking === 'boolean') {
+          sanitized.thinking = rawParams.thinking;
+        }
+        if (typeof rawParams.deliver === 'string' && rawParams.deliver.trim()) {
+          sanitized.deliver = rawParams.deliver.trim();
+        }
+        if (Array.isArray(rawParams.attachments)) {
+          sanitized.attachments = rawParams.attachments;
+        }
+        if (Number.isFinite(rawParams.timeoutMs) && rawParams.timeoutMs > 0) {
+          sanitized.timeoutMs = Math.floor(rawParams.timeoutMs);
+        }
+
+        const idempotencyKeyCandidates = [
+          rawParams.idempotencyKey,
+          rawParams.requestId,
+          rawParams.correlationId,
+          frame.id,
+        ];
+        const idempotencyKey = idempotencyKeyCandidates.find((value) => typeof value === 'string' && value.trim());
+        if (typeof idempotencyKey === 'string' && idempotencyKey.trim()) {
+          sanitized.idempotencyKey = idempotencyKey.trim();
+        }
+
+        frame.params = sanitized;
+        return { frameText: JSON.stringify(frame), waitForChallenge: false };
+      }
+
+      if (method === 'chat.history') {
+        const sanitized = {};
+        if (typeof rawParams.sessionKey === 'string' && rawParams.sessionKey.trim()) {
+          sanitized.sessionKey = rawParams.sessionKey.trim();
+        }
+        if (Number.isFinite(rawParams.limit) && rawParams.limit > 0) {
+          sanitized.limit = Math.floor(rawParams.limit);
+        }
+        frame.params = sanitized;
+        return { frameText: JSON.stringify(frame), waitForChallenge: false };
+      }
+
       return { frameText, waitForChallenge: false };
     }
 
@@ -1720,6 +1830,82 @@ async function startOpenclawBridge(flags) {
   })();
   const actionCableMode = brokerPath.endsWith('/cable');
   const deviceChannelIdentifier = JSON.stringify({ channel: 'DeviceChannel' });
+  let deviceChannelSubscribed = false;
+
+  const reportBridgeRuntimeFault = ({ phase, sessionId = '', error }) => {
+    const message = error instanceof Error ? error.message : String(error || 'unknown bridge callback error');
+    const currentStatus = String(readBridgeStatus().status || '').trim();
+    const nextStatus = resolveBridgeStatusForRuntimeFault({ currentStatus, sessionId });
+    incrementBridgeMetric('bridge_callback_error_count');
+    console.error(
+      `[bridge] callback.error phase=${phase}${sessionId ? ` session=${sessionId}` : ''}: ${message}`
+    );
+    updateBridgeStatus({
+      status: nextStatus,
+      deviceId,
+      brokerWs,
+      brokerHttp,
+      gatewayUrl: gateway.gatewayUrl,
+      lastDisconnectAt: bridgeNowIso(),
+      lastErrorCode: 'bridge_callback_error',
+      lastErrorClass: 'internal',
+      lastErrorMessage: `${phase}: ${message}`,
+      hint:
+        classifyBridgeSessionScope(sessionId) === 'voice'
+          ? 'A voice-session bridge callback failed, but provider health remains available for normal chat.'
+          : 'The bridge caught an internal callback error and kept running.',
+      pid: process.pid,
+    });
+  };
+
+  const reportBridgeProcessFault = ({ phase, status, error }) => {
+    const message = error instanceof Error ? error.message : String(error || 'unknown bridge process fault');
+    incrementBridgeMetric('bridge_process_fault_count');
+    console.error(`[bridge] process.error phase=${phase}: ${message}`);
+    updateBridgeStatus({
+      status,
+      deviceId,
+      brokerWs,
+      brokerHttp,
+      gatewayUrl: gateway.gatewayUrl,
+      lastDisconnectAt: bridgeNowIso(),
+      lastErrorCode: 'bridge_process_fault',
+      lastErrorClass: 'internal',
+      lastErrorMessage: `${phase}: ${message}`,
+      hint:
+        status === 'error'
+          ? 'The bridge hit a runtime fault before it was fully connected and will restart.'
+          : 'The bridge caught a process-level runtime fault and stayed alive in degraded mode.',
+      pid: process.pid,
+    });
+  };
+
+  const handleBridgeProcessFault = createBridgeProcessFaultHandler({
+    readStatus: readBridgeStatus,
+    onReport: ({ phase, status, error }) => {
+      reportBridgeProcessFault({ phase, status, error });
+    },
+    onExit: (code) => {
+      reconnectState.stopped = true;
+      if (reconnectState.timer) {
+        clearTimeout(reconnectState.timer);
+        reconnectState.timer = null;
+      }
+      releaseBridgeLock();
+      process.exit(code);
+    },
+  });
+
+  const uncaughtExceptionHandler = (error) => {
+    handleBridgeProcessFault({ phase: 'process.uncaughtException', error });
+  };
+
+  const unhandledRejectionHandler = (reason) => {
+    handleBridgeProcessFault({ phase: 'process.unhandledRejection', error: reason });
+  };
+
+  process.on('uncaughtException', uncaughtExceptionHandler);
+  process.on('unhandledRejection', unhandledRejectionHandler);
 
   const sendBrokerPayload = (brokerSocket, payload) => {
     if (brokerSocket.readyState !== WebSocket.OPEN) return;
@@ -2157,6 +2343,12 @@ async function startOpenclawBridge(flags) {
       if (!(sessionBridge.pendingRequestTimers instanceof Map)) {
         sessionBridge.pendingRequestTimers = new Map();
       }
+      if (sessionBridge.connectAccepted !== true) {
+        sessionBridge.connectAccepted = false;
+      }
+      if (!Array.isArray(sessionBridge.waitingForConnect)) {
+        sessionBridge.waitingForConnect = [];
+      }
       if (typeof sessionBridge.lastChatCorrelationId !== 'string') {
         sessionBridge.lastChatCorrelationId = '';
       }
@@ -2189,7 +2381,7 @@ async function startOpenclawBridge(flags) {
         flushSessionQueue(sessionBridge);
       });
 
-      gatewaySocket.on('message', (gatewayRaw) => {
+      gatewaySocket.on('message', runBridgeCallbackSafely((gatewayRaw) => {
         const frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
         const gatewayPayload = parseJsonPayload(frame);
         if (gatewayPayload?.event === 'connect.challenge') {
@@ -2230,6 +2422,86 @@ async function startOpenclawBridge(flags) {
               correlationId: requestMeta.correlationId,
               stage: responseMeta.ok ? 'gateway.accepted' : 'gateway.rejected',
             });
+            if (requestMeta.method === 'connect' && responseMeta.ok) {
+              const releasedFrames = flushWaitingForConnect(sessionBridge);
+              for (const released of releasedFrames) {
+                const releasedMeta = extractGatewayRequestMeta(released.frameText);
+                if (!releasedMeta) continue;
+
+                if (released.result === 'queued') {
+                  startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, releasedMeta);
+                  sendGatewayAck(brokerSocket, {
+                    sessionId,
+                    requestId: releasedMeta.requestId,
+                    method: releasedMeta.method,
+                    correlationId: releasedMeta.correlationId,
+                    stage: 'bridge.queued',
+                  });
+                } else if (released.result === 'dropped') {
+                  const pending = sessionBridge.pendingRequests.get(releasedMeta.requestId);
+                  const lastSuccessfulHop =
+                    pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+                      ? pending.lastSuccessfulHop
+                      : 'bridge.waiting_for_connect';
+                  clearPendingRequestTimeout(sessionBridge, releasedMeta.requestId);
+                  sessionBridge.pendingRequests.delete(releasedMeta.requestId);
+                  sendGatewayErrorResponse(brokerSocket, {
+                    sessionId,
+                    requestMeta: releasedMeta,
+                    code: 'bridge_dropped',
+                    message: 'Bridge dropped deferred request because gateway socket is not open.',
+                    lastSuccessfulHop,
+                    retryable: true,
+                  });
+                  sendGatewayAck(brokerSocket, {
+                    sessionId,
+                    requestId: releasedMeta.requestId,
+                    method: releasedMeta.method,
+                    correlationId: releasedMeta.correlationId,
+                    stage: 'bridge.dropped',
+                  });
+                } else {
+                  startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, releasedMeta);
+                  sendGatewayAck(brokerSocket, {
+                    sessionId,
+                    requestId: releasedMeta.requestId,
+                    method: releasedMeta.method,
+                    correlationId: releasedMeta.correlationId,
+                    stage: 'bridge.forwarded',
+                  });
+                }
+              }
+            } else if (requestMeta.method === 'connect' && !responseMeta.ok) {
+              const deferredFrames = Array.isArray(sessionBridge.waitingForConnect)
+                ? sessionBridge.waitingForConnect.splice(0, sessionBridge.waitingForConnect.length)
+                : [];
+              for (const deferredFrame of deferredFrames) {
+                const deferredMeta = extractGatewayRequestMeta(deferredFrame);
+                if (!deferredMeta) continue;
+                const pending = sessionBridge.pendingRequests.get(deferredMeta.requestId);
+                const lastSuccessfulHop =
+                  pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+                    ? pending.lastSuccessfulHop
+                    : 'bridge.waiting_for_connect';
+                clearPendingRequestTimeout(sessionBridge, deferredMeta.requestId);
+                sessionBridge.pendingRequests.delete(deferredMeta.requestId);
+                sendGatewayErrorResponse(brokerSocket, {
+                  sessionId,
+                  requestMeta: deferredMeta,
+                  code: 'gateway_connect_failed',
+                  message: 'Bridge could not forward request because gateway connect did not complete.',
+                  lastSuccessfulHop,
+                  retryable: true,
+                });
+                sendGatewayAck(brokerSocket, {
+                  sessionId,
+                  requestId: deferredMeta.requestId,
+                  method: deferredMeta.method,
+                  correlationId: deferredMeta.correlationId,
+                  stage: 'gateway.rejected',
+                });
+              }
+            }
             if (!responseMeta.ok) {
               incrementBridgeMetric('gateway_rejected_count');
             }
@@ -2247,9 +2519,11 @@ async function startOpenclawBridge(flags) {
         }
 
         sendBrokerPayload(brokerSocket, { action: 'gateway_frame', type: 'gateway.frame', sessionId, frame });
-      });
+      }, (error) => {
+        reportBridgeRuntimeFault({ phase: 'gateway.message', sessionId, error });
+      }));
 
-      gatewaySocket.on('close', (code, reason) => {
+      gatewaySocket.on('close', runBridgeCallbackSafely((code, reason) => {
         if (connectTimeout) {
           clearTimeout(connectTimeout);
           connectTimeout = null;
@@ -2299,9 +2573,11 @@ async function startOpenclawBridge(flags) {
           code,
           reason: reasonText,
         });
-      });
+      }, (error) => {
+        reportBridgeRuntimeFault({ phase: 'gateway.close', sessionId, error });
+      }));
 
-      gatewaySocket.on('error', (err) => {
+      gatewaySocket.on('error', runBridgeCallbackSafely((err) => {
         if (connectTimeout && gatewaySocket.readyState !== WebSocket.CONNECTING) {
           clearTimeout(connectTimeout);
           connectTimeout = null;
@@ -2314,7 +2590,9 @@ async function startOpenclawBridge(flags) {
           level: 'error',
           message: `Gateway socket error (${sessionId}): ${String(err)}`,
         });
-      });
+      }, (error) => {
+        reportBridgeRuntimeFault({ phase: 'gateway.error', sessionId, error });
+      }));
     };
 
     const getOrCreateGatewaySession = (sessionId) => {
@@ -2333,18 +2611,22 @@ async function startOpenclawBridge(flags) {
       console.log('[bridge] Connected to managed broker.');
       reconnectState.attempt = 0;
       reconnectState.lastFailure = null;
-      if (!actionCableMode) return;
-      brokerSocket.send(
-        JSON.stringify({
-          command: 'subscribe',
-          identifier: deviceChannelIdentifier,
-        })
-      );
-      actionCableHeartbeat = setInterval(() => {
-        sendBrokerPayload(brokerSocket, { action: 'heartbeat' });
-      }, 15000);
+      if (actionCableMode) {
+        brokerSocket.send(
+          JSON.stringify({
+            command: 'subscribe',
+            identifier: deviceChannelIdentifier,
+          })
+        );
+        actionCableHeartbeat = setInterval(() => {
+          sendBrokerPayload(brokerSocket, { action: 'heartbeat' });
+        }, 15000);
+      }
       updateBridgeStatus({
-        status: 'connected',
+        status: resolveBridgeStatusForBrokerOpen({
+          actionCableMode,
+          deviceSubscribed: deviceChannelSubscribed,
+        }),
         deviceId,
         brokerWs,
         brokerHttp,
@@ -2359,12 +2641,27 @@ async function startOpenclawBridge(flags) {
       });
     });
 
-    brokerSocket.on('message', (rawData) => {
+    brokerSocket.on('message', runBridgeCallbackSafely((rawData) => {
       const text = typeof rawData === 'string' ? rawData : rawData.toString();
       const payload = parseBrokerEnvelope(text);
       if (!payload || typeof payload.type !== 'string') return;
 
       if (payload.type === 'device.subscribed') {
+        deviceChannelSubscribed = true;
+        updateBridgeStatus({
+          status: 'connected',
+          deviceId,
+          brokerWs,
+          brokerHttp,
+          gatewayUrl: gateway.gatewayUrl,
+          lastConnectedAt: bridgeNowIso(),
+          lastErrorCode: '',
+          lastErrorClass: '',
+          lastErrorMessage: '',
+          hint: '',
+          consecutiveFailures: 0,
+          pid: process.pid,
+        });
         return;
       }
 
@@ -2511,7 +2808,22 @@ async function startOpenclawBridge(flags) {
           }
           return;
         }
-        const result = forwardFrameToSession(sessionBridge, prepared.frameText);
+        const result = forwardFrameToSession(sessionBridge, prepared.frameText, {
+          requiresConnectAccepted: Boolean(requestMeta && requestMeta.method !== 'connect'),
+        });
+        if (result === 'waiting_for_connect') {
+          console.log(`[bridge] client.frame waiting for connect ${sessionId}`);
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.waiting_for_connect',
+            });
+          }
+          return;
+        }
         if (result === 'queued') {
           console.log(`[bridge] client.frame queued ${sessionId}`);
           if (requestMeta) {
@@ -2586,9 +2898,11 @@ async function startOpenclawBridge(flags) {
         }
         return;
       }
-    });
+    }, (error) => {
+      reportBridgeRuntimeFault({ phase: 'broker.message', error });
+    }));
 
-    brokerSocket.on('close', (code, reason) => {
+    brokerSocket.on('close', runBridgeCallbackSafely((code, reason) => {
       if (actionCableHeartbeat) {
         clearInterval(actionCableHeartbeat);
         actionCableHeartbeat = null;
@@ -2620,16 +2934,20 @@ async function startOpenclawBridge(flags) {
         });
       }
       scheduleReconnect();
-    });
+    }, (error) => {
+      reportBridgeRuntimeFault({ phase: 'broker.close', error });
+    }));
 
-    brokerSocket.on('error', (err) => {
+    brokerSocket.on('error', runBridgeCallbackSafely((err) => {
       incrementBridgeMetric('bridge_socket_error_count');
       reconnectState.lastFailure = classifyBridgeFailure({ err });
       console.error(
         `[bridge] Broker socket error [${reconnectState.lastFailure.failureClass}/${reconnectState.lastFailure.errorCode}]: ${reconnectState.lastFailure.message}`
       );
       console.error(`[bridge] ${reconnectState.lastFailure.hint}`);
-    });
+    }, (error) => {
+      reportBridgeRuntimeFault({ phase: 'broker.error', error });
+    }));
   };
 
   const markStopped = (signal) => {
@@ -2638,6 +2956,8 @@ async function startOpenclawBridge(flags) {
       clearTimeout(reconnectState.timer);
       reconnectState.timer = null;
     }
+    process.off('uncaughtException', uncaughtExceptionHandler);
+    process.off('unhandledRejection', unhandledRejectionHandler);
     updateBridgeStatus({
       status: 'stopped',
       deviceId,
@@ -3219,7 +3539,12 @@ if (__isDirectExecution) {
 export {
   prepareGatewayFrameForLocalGateway,
   classifyBridgeFailure,
+  classifyBridgeSessionScope,
+  createBridgeProcessFaultHandler,
   computeReconnectDelayMs,
+  resolveBridgeStatusForBrokerOpen,
+  resolveBridgeStatusForRuntimeFault,
+  runBridgeCallbackSafely,
   extractGatewayRequestMeta,
   extractGatewayResponseMeta,
   isGatewayRunStartedFrame,

package/bin/sessionBridgeState.js

@@ -12,7 +12,12 @@ export function ensureSessionBridge({ sessions, sessionId, createSocket }) {
   if (existing) return existing;
 
   const socket = createSocket(id);
-  const next = { socket, queue: [] };
+  const next = {
+    socket,
+    queue: [],
+    connectAccepted: false,
+    waitingForConnect: [],
+  };
   sessions.set(id, next);
   return next;
 }
@@ -20,11 +25,19 @@ export function ensureSessionBridge({ sessions, sessionId, createSocket }) {
 /**
  * Forward a frame to the gateway socket or queue it while connecting.
  */
-export function forwardFrameToSession(sessionBridge, frameText) {
+export function forwardFrameToSession(sessionBridge, frameText, options = {}) {
   if (!sessionBridge || !sessionBridge.socket || typeof frameText !== 'string' || !frameText) {
     return 'dropped';
   }
 
+  if (options.requiresConnectAccepted === true && sessionBridge.connectAccepted !== true) {
+    if (!Array.isArray(sessionBridge.waitingForConnect)) {
+      sessionBridge.waitingForConnect = [];
+    }
+    sessionBridge.waitingForConnect.push(frameText);
+    return 'waiting_for_connect';
+  }
+
   const { socket } = sessionBridge;
   if (socket.readyState === WS_OPEN) {
     socket.send(frameText);
@@ -39,6 +52,20 @@ export function forwardFrameToSession(sessionBridge, frameText) {
   return 'dropped';
 }
 
+export function flushWaitingForConnect(sessionBridge) {
+  if (!sessionBridge) return [];
+
+  sessionBridge.connectAccepted = true;
+  const pending = Array.isArray(sessionBridge.waitingForConnect)
+    ? sessionBridge.waitingForConnect.splice(0, sessionBridge.waitingForConnect.length)
+    : [];
+
+  return pending.map((frameText) => ({
+    frameText,
+    result: forwardFrameToSession(sessionBridge, frameText),
+  }));
+}
+
 export function flushSessionQueue(sessionBridge) {
   if (!sessionBridge || !sessionBridge.socket) return;
   const socket = sessionBridge.socket;

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.12",
-  "description": "Oomi CLI for OpenClaw setup",
+  "version": "0.2.14",
+  "description": "Oomi OpenClaw channel plugin and bridge tooling",
   "bin": {
     "oomi": "bin/oomi-ai.js"
   },

package/skills/oomi/SKILL.md

@@ -1,102 +1,140 @@
 ---
 name: oomi
-description: Interact with the Oomi 3D Avatar application to retrieve health data, set goals, and control the avatar persona.
+description: Support Oomi OpenClaw installs, bridge health, managed chat and voice setup, and avatar control.
 ---
 
 # Oomi Skill
 
-This skill allows you to interact with the running Oomi application (localhost). You can fetch user activity data, set new goals, and sync context.
+Use this skill when you need to:
+- connect an OpenClaw machine to Oomi
+- repair the Oomi plugin or bridge on a machine
+- inspect managed chat or voice health
+- control the Oomi avatar with inline tags
 
-## Prerequisites
+## Primary Operator Workflow
 
-- The Oomi Next.js app must be running locally (`npm run dev`) at `http://localhost:3000`.
+If the user wants OpenClaw connected to Oomi:
 
-## Configuration
+1. Ensure `oomi-ai` is installed or updated:
+```bash
+pnpm add -g oomi-ai@latest
+```
+Fallback:
+```bash
+npm install -g oomi-ai@latest
+```
+
+2. Pair the device:
+```bash
+oomi openclaw pair --app-url https://www.oomi.ai --no-start
+```
+
+3. Install the plugin:
+```bash
+openclaw plugins install oomi-ai@latest
+```
+
+4. Print config guidance:
+```bash
+oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai
+```
+
+5. Apply the `channels.oomi.accounts.default` config and restart OpenClaw.
 
-Before using the skill, run the setup script to configure the API URL:
-```python
-python3 skills/oomi/setup.py
+6. Start or repair the bridge:
+```bash
+oomi openclaw bridge ensure --detach
+```
+If stale:
+```bash
+oomi openclaw bridge restart --detach
+```
+On macOS, prefer supervised mode:
+```bash
+oomi openclaw bridge service install
 ```
-Default URL is `http://localhost:3000/api/skill`.
 
-## Tools
+## Health Checks
+
+Use these when chat or voice is failing:
+
+```bash
+oomi openclaw bridge ps
+oomi openclaw bridge service status
+oomi openclaw status
+tail -f ~/.openclaw/logs/oomi-bridge-live.log
+tail -f ~/.openclaw/logs/gateway.log
+tail -f ~/.openclaw/logs/gateway.err.log
+```
+
+Interpret bridge states like this:
+- `starting`: booting or waiting for managed subscription
+- `connected`: ready for managed traffic
+- `reconnecting`: retry scheduled after transport failure
+- `degraded`: bridge caught a runtime fault but is still alive
+- `error`: startup or auth failure blocked operation
+- `stopped`: not running or intentionally shut down
+
+## Common Failures
+
+### Duplicate plugin id
+- Cause: multiple discoverable `oomi-ai` installs
+- Action: remove stale plugin copies and reinstall once
+
+### `invalid handshake: first request must be connect`
+- Cause: gateway request ordering broke
+- Action: update `oomi-ai`, restart the bridge, confirm only one bridge worker exists
+
+### STT works but the assistant does not reply
+- Cause: the voice turn reached Oomi, but the managed gateway or OpenClaw run failed later
+- Action: inspect `gateway.log`, `gateway.err.log`, and the session JSONL for that run
+
+## Local Oomi API Tools
+
+These scripts interact with the local Oomi application when it is running.
 
 ### `get_data`
-Fetches the user's latest health and activity data from the Oomi app.
+Fetch the latest user activity data.
 
-**Usage:**
-```python
+```bash
 python3 skills/oomi/scripts/get_data.py
 ```
 
-**Returns:**
-JSON string containing:
-- `steps`: Daily step count
-- `sleep`: Sleep duration in hours
-- `energy`: Calculated energy level (0-100)
-- `mood`: Current user mood (if tracked)
-
 ### `set_goal`
-Sets a new activity or behavior goal for the user in the Oomi app.
+Set a new goal in the local Oomi app.
 
-**Usage:**
-```python
+```bash
 python3 skills/oomi/scripts/send_goal.py --type "steps" --value 10000 --message "Let's hit 10k today!"
 ```
 
-**Arguments:**
-- `--type`: Type of goal (e.g., "steps", "sleep", "focus")
-- `--value`: Target value (number)
-- `--message`: Motivational message to display to the user
-
 ### `sync`
-Performs a full context sync, updating Oomi with the Agent's current understanding of the user's state.
+Sync local context.
 
-**Usage:**
-```python
+```bash
 python3 skills/oomi/scripts/sync.py
 ```
 
 ### `get_avatar_capabilities`
-Returns the current avatar command schema (supported animations, expressions, gestures, and aliases).
+Read the avatar command schema before emitting inline avatar tags.
 
-**Usage:**
-```python
+```bash
 python3 skills/oomi/scripts/get_avatar_capabilities.py
 ```
 
-**Returns:**
-JSON containing:
-- `commands.anim.values` (supported animation names)
-- `commands.anim.aliases` (accepted shorthand -> animation name)
-- `commands.face.values` (supported expressions)
-- `commands.gesture.values` (supported gestures)
-- `commands.look.values` (supported look targets)
-
 ### `install_agent_instructions`
-Installs Oomi avatar command instructions into an OpenClaw `AGENTS.md` file.
+Install packaged Oomi operator instructions into an OpenClaw `AGENTS.md` file.
 
-**Usage:**
-```python
+```bash
 python3 skills/oomi/scripts/install_agent_instructions.py
 ```
 
-**Options:**
-- `--agents-file` Path to the `AGENTS.md` file (defaults to `OPENCLAW_WORKSPACE/AGENTS.md` or repo `AGENTS.md`).
-- `--instructions-file` Override the instructions markdown file.
-
-## Persona Control (Inline)
-
-In addition to these scripts, you can control the avatar's visualization directly in your text responses using the following tags. These tags are invisible to the user.
-
-- **Animations (canonical)**: `[anim:Waving]`, `[anim:Walking]`, `[anim:Idle]`, `[anim:Sitting Idle]`
-  - **Aliases**: `wave -> Waving`, `walk -> Walking`, `idle -> Idle`, `sit/sitting -> Sitting Idle`
-- **Expressions**: `[face:happy]`, `[face:sad]`, `[face:surprised]`, `[face:focused]`, `[face:gentle]`, `[face:thinking]`, `[face:curious]`, `[face:confused]`
-- **Gestures**: `[gesture:nod]`, `[gesture:think]`, `[gesture:shrug]`, `[gesture:wave]`, `[gesture:bow]`
-- **Gaze**: `[look:camera]`, `[look:left]`, `[look:right]`, `[look:up]`, `[look:down]`
+## Avatar Control
 
-**Example:**
-"I see you didn't sleep well last night. [face:worried] [gesture:think] Maybe we should take it easy today?"
+Before emitting avatar commands, call `get_avatar_capabilities` and prefer canonical values.
+Use aliases only when explicitly needed.
 
-**Recommended instruction for agents:**
-Before emitting avatar commands, call `get_avatar_capabilities` and prefer canonical values. Use aliases only if explicitly needed.
+Supported inline tags include:
+- animations: `[anim:Waving]`, `[anim:Walking]`, `[anim:Idle]`, `[anim:Sitting Idle]`
+- expressions: `[face:happy]`, `[face:sad]`, `[face:surprised]`, `[face:focused]`, `[face:gentle]`, `[face:thinking]`
+- gestures: `[gesture:nod]`, `[gesture:think]`, `[gesture:shrug]`, `[gesture:wave]`, `[gesture:bow]`
+- gaze: `[look:camera]`, `[look:left]`, `[look:right]`, `[look:up]`, `[look:down]`