oomi-ai 0.2.0 → 0.2.2

package/README.md

@@ -14,7 +14,24 @@ npm install -g oomi-ai
 
 ## Usage
 
-Install agent instructions only (backwards compatible):
+Install as an OpenClaw channel extension (preferred architecture):
+```
+openclaw plugins install oomi-ai@latest
+```
+
+This package now ships an OpenClaw channel plugin (`openclaw.plugin.json`) with channel id `oomi`.
+Channel account config fields (`channels.oomi.accounts.<accountId>`):
+- `backendUrl`
+- `deviceToken`
+- `defaultSessionKey` (optional, default `agent:main:webchat:channel:oomi`)
+- `requestTimeoutMs` (optional)
+
+Print plugin install/config guidance from local pair state:
+```
+oomi openclaw plugin
+```
+
+Install agent instructions only:
 ```
 oomi init
 ```
@@ -24,18 +41,12 @@ Install agent instructions + Oomi skill:
 oomi openclaw install
 ```
 
-Start managed gateway bridge (OpenClaw host -> Oomi broker):
+Pair and provision device token from Oomi web backend:
 ```
-oomi openclaw bridge \
-  --broker-http https://your-broker.modal.run \
-  --broker-ws wss://your-broker.modal.run/ws/device \
-  --pair-code ABCD2345
+oomi openclaw pair --app-url https://your-oomi-app.vercel.app --device-id my-openclaw-mac --no-start
 ```
 
-Pair + bootstrap bridge automatically from Oomi web backend:
-```
-oomi openclaw pair --app-url https://your-oomi-app.vercel.app --device-id my-openclaw-mac --detach
-```
+`--app-url` must be reachable from the OpenClaw host. If OpenClaw runs on a different machine/network, do not use `localhost` unless tunneled.
 
 This prints:
 - `Connect code: <device-id>`
@@ -45,6 +56,20 @@ This prints:
   - `Code: ...`
   - `Link: ...`
 
+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.
+- `connect code` is the stable device id used by browser connect (`managed://<device-id>`).
+
 Sync personas from the repo into the backend registry:
 ```
 oomi personas sync --backend-url http://localhost:3001
@@ -60,9 +85,7 @@ 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 bridge --broker-ws wss://.../ws/device --device-token <token>
 oomi openclaw pair --app-url https://your-oomi-app.vercel.app --no-start
-oomi openclaw pair --app-url https://your-oomi-app.vercel.app --detach
 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
@@ -74,9 +97,19 @@ Defaults:
 
 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
+
 ## Package Audit + Publish (pnpm)
 ```
-cd /Users/nemu/projects/oomi/packages/oomi-ai
+cd <repo-root>/packages/oomi-ai
 pnpm check
 pnpm publish --dry-run --no-git-checks --access public
 pnpm publish --access public

package/agent_instructions.md

@@ -15,10 +15,21 @@ Aliases allowed (if needed): wave -> Waving, walk -> Walking, idle -> Idle, sit/
 
 If the user asks to connect OpenClaw to Oomi voice/web:
 
-1. Ensure `oomi-ai` is installed (`pnpm add -g oomi-ai`).
-2. Run:
-   - `oomi openclaw pair --app-url https://oomi.ai --detach`
-3. Return this exact result format to the user:
+1. Refresh bootstrap/update 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:
+   - `oomi openclaw pair --app-url https://www.oomi.ai --no-start`
+4. Install OpenClaw plugin:
+   - `openclaw plugins install oomi-ai@latest`
+5. Configure channel account (`channels.oomi.accounts.default`) from:
+   - `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai`
+6. Restart OpenClaw.
+7. 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`
+8. Return this exact result format to the user:
    - `Oomi Connect Ready`
    - `Code: ...`
    - `Link: ...`

package/bin/oomi-ai.js

@@ -10,6 +10,121 @@ const MARKER_START = '<oomi-agent-instructions>';
 const MARKER_END = '</oomi-agent-instructions>';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+const UPDATE_STATE_FILE = path.join(os.homedir(), '.openclaw', 'oomi-ai-update-check.json');
+const DEFAULT_UPDATE_CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
+const DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 1200;
+
+function parsePositiveInteger(value, fallback) {
+  const num = Number(value);
+  if (!Number.isFinite(num) || num <= 0) return fallback;
+  return Math.floor(num);
+}
+
+function readJsonSafe(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFile(filePath));
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonSafe(filePath, value) {
+  try {
+    ensureDir(path.dirname(filePath));
+    writeFile(filePath, JSON.stringify(value, null, 2) + '\n');
+  } catch {
+    // best-effort cache write
+  }
+}
+
+function currentPackageVersion() {
+  const packageJsonPath = path.join(PACKAGE_ROOT, 'package.json');
+  const packageJson = readJsonSafe(packageJsonPath);
+  const version = typeof packageJson?.version === 'string' ? packageJson.version.trim() : '';
+  return version;
+}
+
+function parseVersionTuple(version) {
+  if (typeof version !== 'string') return null;
+  const cleaned = version.trim().replace(/^v/i, '').split('-')[0];
+  const parts = cleaned.split('.');
+  if (parts.length < 3) return null;
+  const major = Number(parts[0]);
+  const minor = Number(parts[1]);
+  const patch = Number(parts[2]);
+  if (![major, minor, patch].every((n) => Number.isInteger(n) && n >= 0)) return null;
+  return [major, minor, patch];
+}
+
+function compareVersions(a, b) {
+  const av = parseVersionTuple(a);
+  const bv = parseVersionTuple(b);
+  if (!av || !bv) return 0;
+  for (let i = 0; i < 3; i += 1) {
+    if (av[i] < bv[i]) return -1;
+    if (av[i] > bv[i]) return 1;
+  }
+  return 0;
+}
+
+async function fetchLatestPublishedVersion(pkgName) {
+  const timeoutMs = parsePositiveInteger(
+    process.env.OOMI_UPDATE_CHECK_TIMEOUT_MS,
+    DEFAULT_UPDATE_CHECK_TIMEOUT_MS
+  );
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkgName)}/latest`, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+      },
+      signal: controller.signal,
+    });
+    if (!response.ok) return '';
+    const payload = await response.json().catch(() => ({}));
+    const version = typeof payload?.version === 'string' ? payload.version.trim() : '';
+    return version;
+  } catch {
+    return '';
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function maybeNotifyUpdate(command) {
+  if (isTruthyFlag(process.env.OOMI_SKIP_UPDATE_CHECK)) return;
+  if (!command || command === 'help' || command === '--help') return;
+
+  const currentVersion = currentPackageVersion();
+  if (!currentVersion) return;
+
+  const intervalMs = parsePositiveInteger(
+    process.env.OOMI_UPDATE_CHECK_INTERVAL_MS,
+    DEFAULT_UPDATE_CHECK_INTERVAL_MS
+  );
+  const now = Date.now();
+  const state = readJsonSafe(UPDATE_STATE_FILE) || {};
+  const lastCheckedAt = Number(state.lastCheckedAt || 0);
+  if (Number.isFinite(lastCheckedAt) && lastCheckedAt > 0 && now - lastCheckedAt < intervalMs) {
+    return;
+  }
+
+  const latestVersion = await fetchLatestPublishedVersion('oomi-ai');
+  writeJsonSafe(UPDATE_STATE_FILE, {
+    lastCheckedAt: now,
+    latestVersion: latestVersion || String(state.latestVersion || ''),
+  });
+  if (!latestVersion) return;
+
+  if (compareVersions(currentVersion, latestVersion) < 0) {
+    console.warn(`[oomi] Update available: oomi-ai ${currentVersion} -> ${latestVersion}`);
+    console.warn('[oomi] Update command: pnpm add -g oomi-ai@latest');
+    console.warn('[oomi] Fallback update command: npm install -g oomi-ai@latest');
+  }
+}
 
 function usage() {
   console.log(`oomi <command>
@@ -27,6 +142,9 @@ Commands:
   openclaw pair
     Pair this OpenClaw host with Oomi and start bridge (single command).
 
+  openclaw plugin
+    Print OpenClaw extension install/config guidance for Oomi channel plugin.
+
   personas sync
     Sync personas from the repo into the Oomi backend registry.
 
@@ -38,7 +156,7 @@ Common flags:
   --workspace PATH       Override OpenClaw workspace root
   --skills-dir PATH      Override skills install dir
   --broker-http URL      Managed broker HTTPS URL (for pair claim)
-  --broker-ws URL        Managed broker device WS URL (wss://.../ws/device)
+  --broker-ws URL        Managed broker device WS URL (wss://.../cable)
   --pair-code CODE       One-time pairing code from Oomi
   --app-url URL          Oomi app URL used for pairing APIs (default: http://127.0.0.1:3000)
   --label TEXT           Pairing label shown in broker logs
@@ -47,6 +165,7 @@ Common flags:
   --no-start             Pair and save token, but do not start bridge
   --device-id ID         Bridge device identifier (default: host name)
   --device-token TOKEN   Existing bridge device token
+  --show-secrets         Print full token values in diagnostic output
   --json                 Print pairing result as JSON (for automation)
   --backend-url URL      Override Oomi backend URL
   --root PATH            Override repo root path for persona discovery
@@ -499,6 +618,17 @@ function injectGatewayAuth(frameText, gatewayAuth) {
       return frameText;
     }
     const params = frame.params && typeof frame.params === 'object' ? frame.params : {};
+    const existingScopes = Array.isArray(params.scopes)
+      ? params.scopes.filter((value) => typeof value === 'string' && value.trim())
+      : [];
+    const requiredScopes = ['operator.read', 'operator.write'];
+    for (const scope of requiredScopes) {
+      if (!existingScopes.includes(scope)) {
+        existingScopes.push(scope);
+      }
+    }
+    params.scopes = existingScopes;
+
     const auth = {};
     if (gatewayAuth.token) auth.token = gatewayAuth.token;
     else if (gatewayAuth.password) auth.password = gatewayAuth.password;
@@ -523,19 +653,39 @@ function parseJsonPayload(raw) {
 
 async function startOpenclawBridge(flags) {
   const bridgeState = readBridgeState();
-  const brokerHttp = String(flags['broker-http'] || process.env.OOMI_MANAGED_BROKER_HTTP_URL || bridgeState.brokerHttp || '').trim();
-  const brokerWs = String(flags['broker-ws'] || process.env.OOMI_MANAGED_BROKER_DEVICE_WS_URL || bridgeState.brokerWs || '').trim();
+  const brokerHttp = String(
+    flags['broker-http'] ||
+      process.env.OOMI_CHAT_BROKER_HTTP_URL ||
+      bridgeState.brokerHttp ||
+      ''
+  ).trim();
+  const brokerWs = String(
+    flags['broker-ws'] ||
+      process.env.OOMI_CHAT_BROKER_DEVICE_WS_URL ||
+      bridgeState.brokerWs ||
+      ''
+  ).trim();
   const deviceId = resolveDeviceId(flags, bridgeState);
   const pairCode = String(flags['pair-code'] || '').trim().toUpperCase();
-  let deviceToken = String(flags['device-token'] || bridgeState.deviceToken || '').trim();
+  const explicitDeviceToken = String(flags['device-token'] || '').trim();
+  const canReuseStateToken =
+    String(bridgeState.deviceId || '').trim() === deviceId &&
+    String(bridgeState.brokerWs || '').trim() === brokerWs &&
+    String(bridgeState.brokerHttp || '').trim() === brokerHttp;
+  let deviceToken = explicitDeviceToken;
+  if (!deviceToken && canReuseStateToken) {
+    deviceToken = String(bridgeState.deviceToken || '').trim();
+  }
 
   if (!brokerWs) {
-    throw new Error('Missing broker device websocket URL. Set --broker-ws or OOMI_MANAGED_BROKER_DEVICE_WS_URL.');
+    throw new Error('Missing broker device websocket URL. Set --broker-ws or OOMI_CHAT_BROKER_DEVICE_WS_URL.');
   }
 
   if (!deviceToken) {
     if (!brokerHttp || !pairCode) {
-      throw new Error('No saved device token. Provide --pair-code and --broker-http to claim one.');
+      throw new Error(
+        'No valid saved device token for this device/broker. Provide --pair-code and --broker-http to claim one.'
+      );
     }
     const claimed = await claimBridgeDeviceToken({ brokerHttp, pairCode, deviceId });
     deviceToken = String(claimed.deviceToken || '').trim();
@@ -563,22 +713,95 @@ async function startOpenclawBridge(flags) {
   console.log(`Broker WS: ${brokerWs}`);
 
   const activeGatewaySockets = new Map();
+  const brokerPath = (() => {
+    try {
+      return new URL(brokerWs).pathname || '';
+    } catch {
+      return '';
+    }
+  })();
+  const actionCableMode = brokerPath.endsWith('/cable');
+  const deviceChannelIdentifier = JSON.stringify({ channel: 'DeviceChannel' });
+
+  const sendBrokerPayload = (brokerSocket, payload) => {
+    if (brokerSocket.readyState !== WebSocket.OPEN) return;
+    if (!actionCableMode) {
+      brokerSocket.send(JSON.stringify(payload));
+      return;
+    }
+    brokerSocket.send(
+      JSON.stringify({
+        command: 'message',
+        identifier: deviceChannelIdentifier,
+        data: JSON.stringify(payload),
+      })
+    );
+  };
+
+  const parseBrokerEnvelope = (raw) => {
+    const payload = parseJsonPayload(raw);
+    if (!payload) return null;
+    if (!actionCableMode) return payload;
+
+    if (payload.type === 'welcome' || payload.type === 'ping') return null;
+    if (payload.type === 'confirm_subscription') return { type: 'device.subscribed' };
+    if (payload.type === 'disconnect') {
+      return {
+        type: 'broker.disconnect',
+        reason: String(payload.reason || ''),
+      };
+    }
+    if (payload.type === 'reject_subscription') {
+      return {
+        type: 'broker.reject_subscription',
+      };
+    }
+    if (payload.message && typeof payload.message === 'object') {
+      return payload.message;
+    }
+    return null;
+  };
 
   const connectBroker = () => {
     const wsUrl = new URL(brokerWs);
     wsUrl.searchParams.set('token', deviceToken);
 
     const brokerSocket = new WebSocket(wsUrl.toString());
+    let actionCableHeartbeat = null;
 
     brokerSocket.on('open', () => {
       console.log('[bridge] Connected to managed broker.');
+      if (!actionCableMode) return;
+      brokerSocket.send(
+        JSON.stringify({
+          command: 'subscribe',
+          identifier: deviceChannelIdentifier,
+        })
+      );
+      actionCableHeartbeat = setInterval(() => {
+        sendBrokerPayload(brokerSocket, { action: 'heartbeat' });
+      }, 15000);
     });
 
     brokerSocket.on('message', (rawData) => {
       const text = typeof rawData === 'string' ? rawData : rawData.toString();
-      const payload = parseJsonPayload(text);
+      const payload = parseBrokerEnvelope(text);
       if (!payload || typeof payload.type !== 'string') return;
 
+      if (payload.type === 'device.subscribed') {
+        return;
+      }
+
+      if (payload.type === 'broker.disconnect') {
+        console.error(`[bridge] Broker rejected connection: ${String(payload.reason || 'unauthorized')}`);
+        return;
+      }
+
+      if (payload.type === 'broker.reject_subscription') {
+        console.error('[bridge] Broker rejected DeviceChannel subscription.');
+        return;
+      }
+
       if (payload.type === 'device.ready') {
         console.log(`[bridge] Broker ready for device ${payload.deviceId || deviceId}.`);
         return;
@@ -587,27 +810,53 @@ async function startOpenclawBridge(flags) {
       if (payload.type === 'client.open') {
         const sessionId = String(payload.sessionId || '').trim();
         if (!sessionId || activeGatewaySockets.has(sessionId)) return;
+        console.log(`[bridge] client.open ${sessionId}`);
         const gatewaySocket = new WebSocket(gateway.gatewayUrl);
-        activeGatewaySockets.set(sessionId, gatewaySocket);
+        const sessionBridge = {
+          socket: gatewaySocket,
+          queue: [],
+        };
+        activeGatewaySockets.set(sessionId, sessionBridge);
+
+        gatewaySocket.on('open', () => {
+          console.log(`[bridge] gateway.open ${sessionId}`);
+          while (sessionBridge.queue.length > 0 && gatewaySocket.readyState === WebSocket.OPEN) {
+            const nextFrame = sessionBridge.queue.shift();
+            if (typeof nextFrame === 'string' && nextFrame) {
+              gatewaySocket.send(nextFrame);
+            }
+          }
+        });
 
         gatewaySocket.on('message', (gatewayRaw) => {
           const frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
-          if (brokerSocket.readyState === WebSocket.OPEN) {
-            brokerSocket.send(JSON.stringify({ type: 'gateway.frame', sessionId, frame }));
-          }
+          sendBrokerPayload(brokerSocket, { action: 'gateway_frame', type: 'gateway.frame', sessionId, frame });
         });
 
-        gatewaySocket.on('close', () => {
+        gatewaySocket.on('close', (code, reason) => {
+          const reasonText = reason ? reason.toString() : '';
+          console.log(
+            `[bridge] gateway.close ${sessionId} code=${String(code)}${reasonText ? ` reason=${reasonText}` : ''}`
+          );
           activeGatewaySockets.delete(sessionId);
-          if (brokerSocket.readyState === WebSocket.OPEN) {
-            brokerSocket.send(JSON.stringify({ type: 'gateway.closed', sessionId }));
-          }
+          sendBrokerPayload(brokerSocket, {
+            action: 'gateway_closed',
+            type: 'gateway.closed',
+            sessionId,
+            code,
+            reason: reasonText,
+          });
         });
 
         gatewaySocket.on('error', (err) => {
-          if (brokerSocket.readyState === WebSocket.OPEN) {
-            brokerSocket.send(JSON.stringify({ type: 'log', level: 'error', message: `Gateway socket error (${sessionId}): ${String(err)}` }));
-          }
+          console.error(`[bridge] gateway.error ${sessionId}: ${String(err)}`);
+          sendBrokerPayload(brokerSocket, {
+            action: 'log',
+            type: 'log',
+            sessionId,
+            level: 'error',
+            message: `Gateway socket error (${sessionId}): ${String(err)}`,
+          });
         });
         return;
       }
@@ -616,30 +865,47 @@ async function startOpenclawBridge(flags) {
         const sessionId = String(payload.sessionId || '').trim();
         const frame = typeof payload.frame === 'string' ? payload.frame : '';
         if (!sessionId || !frame) return;
-        const gatewaySocket = activeGatewaySockets.get(sessionId);
-        if (!gatewaySocket || gatewaySocket.readyState !== WebSocket.OPEN) return;
+        console.log(`[bridge] client.frame ${sessionId}`);
+        const sessionBridge = activeGatewaySockets.get(sessionId);
+        if (!sessionBridge || !sessionBridge.socket) {
+          console.log(`[bridge] client.frame dropped (no session) ${sessionId}`);
+          return;
+        }
+        const gatewaySocket = sessionBridge.socket;
         const frameWithAuth = injectGatewayAuth(frame, gateway);
-        gatewaySocket.send(frameWithAuth);
+        if (gatewaySocket.readyState === WebSocket.OPEN) {
+          gatewaySocket.send(frameWithAuth);
+        } else if (gatewaySocket.readyState === WebSocket.CONNECTING) {
+          console.log(`[bridge] client.frame queued ${sessionId}`);
+          sessionBridge.queue.push(frameWithAuth);
+        } else {
+          console.log(`[bridge] client.frame dropped (socket not open) ${sessionId}`);
+        }
         return;
       }
 
       if (payload.type === 'client.close') {
         const sessionId = String(payload.sessionId || '').trim();
-        const gatewaySocket = activeGatewaySockets.get(sessionId);
-        if (gatewaySocket) {
+        console.log(`[bridge] client.close ${sessionId}`);
+        const sessionBridge = activeGatewaySockets.get(sessionId);
+        if (sessionBridge && sessionBridge.socket) {
           activeGatewaySockets.delete(sessionId);
-          gatewaySocket.close(1000, 'client_closed');
+          sessionBridge.socket.close(1000, 'client_closed');
         }
         return;
       }
     });
 
     brokerSocket.on('close', (code, reason) => {
+      if (actionCableHeartbeat) {
+        clearInterval(actionCableHeartbeat);
+        actionCableHeartbeat = null;
+      }
       console.log(`[bridge] Broker disconnected (${code}) ${reason.toString()}`);
-      for (const [sessionId, gatewaySocket] of activeGatewaySockets.entries()) {
+      for (const [sessionId, sessionBridge] of activeGatewaySockets.entries()) {
         activeGatewaySockets.delete(sessionId);
         try {
-          gatewaySocket.close(1001, 'broker_disconnected');
+          sessionBridge.socket.close(1001, 'broker_disconnected');
         } catch {
           // no-op
         }
@@ -664,7 +930,6 @@ async function pairAndStartOpenclawBridge(flags) {
   const sessionKey = String(
     flags['session-key'] ||
     process.env.OOMI_SESSION_KEY ||
-    process.env.NEXT_PUBLIC_SESSION_KEY ||
     'agent:main:webchat:channel:oomi'
   ).trim();
   const detach = Boolean(flags.detach);
@@ -768,6 +1033,73 @@ async function pairAndStartOpenclawBridge(flags) {
   });
 }
 
+function printOpenclawPluginSetup(flags) {
+  const bridgeState = readBridgeState();
+  const backendUrl = String(
+    flags['backend-url'] ||
+      process.env.OOMI_BACKEND_URL ||
+      process.env.OOMI_CHAT_BROKER_HTTP_URL ||
+      bridgeState.brokerHttp ||
+      ''
+  ).trim();
+  const deviceToken = String(
+    flags['device-token'] ||
+      bridgeState.deviceToken ||
+      ''
+  ).trim();
+  const showSecrets = isTruthyFlag(flags['show-secrets']);
+  const redactToken = (value) => {
+    if (!value) return '';
+    if (showSecrets) return value;
+    if (value.length <= 12) return '***';
+    return `${value.slice(0, 6)}...${value.slice(-6)}`;
+  };
+  const defaultSessionKey = String(
+    flags['session-key'] ||
+      process.env.OOMI_SESSION_KEY ||
+      'agent:main:webchat:channel:oomi'
+  ).trim();
+
+  console.log('OpenClaw Oomi Plugin Setup');
+  console.log('--------------------------');
+  console.log('1) Install extension package in OpenClaw:');
+  console.log('   openclaw plugins install oomi-ai@latest');
+  console.log('');
+  console.log('2) Configure OpenClaw channel account (channels.oomi.accounts.default):');
+  console.log(
+    JSON.stringify(
+      {
+        channels: {
+          oomi: {
+            defaultAccountId: 'default',
+            accounts: {
+              default: {
+                enabled: true,
+                backendUrl,
+                deviceToken: redactToken(deviceToken),
+                defaultSessionKey,
+              },
+            },
+          },
+        },
+      },
+      null,
+      2
+    )
+  );
+  if (deviceToken && !showSecrets) {
+    console.log('Token is redacted by default. Use --show-secrets to print full values.');
+    console.log(`Bridge state file: ${resolveBridgeStatePath()}`);
+  }
+  console.log('');
+
+  if (!backendUrl || !deviceToken) {
+    console.log('Missing backend/device credentials in local state.');
+    console.log('Run: oomi openclaw pair --app-url https://www.oomi.ai --no-start');
+    console.log('Then run: oomi openclaw plugin');
+  }
+}
+
 async function main() {
   const args = parseArgs(process.argv);
   const command = args.command;
@@ -778,6 +1110,8 @@ async function main() {
     process.exit(0);
   }
 
+  await maybeNotifyUpdate(command);
+
   if (command === 'init') {
     const agentsPath = resolveAgentsFile(args.flags['agents-file'], args.flags.workspace);
     installInstructions(agentsPath);
@@ -807,6 +1141,11 @@ async function main() {
     return;
   }
 
+  if (command === 'openclaw' && subcommand === 'plugin') {
+    printOpenclawPluginSetup(args.flags);
+    return;
+  }
+
   if (command === 'personas' && subcommand === 'sync') {
     await syncPersonas({ backendUrl: args.flags['backend-url'], root: args.flags.root });
     return;

package/openclaw.extension.js

@@ -0,0 +1,247 @@
+const CHANNEL_ID = 'oomi';
+const DEFAULT_SESSION_KEY = 'agent:main:webchat:channel:oomi';
+const DEFAULT_TIMEOUT_MS = 15000;
+
+function toString(value, fallback = '') {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function toNumber(value, fallback, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  const normalized = Math.floor(value);
+  if (normalized < min) return fallback;
+  if (normalized > max) return max;
+  return normalized;
+}
+
+function parseAccounts(rawAccounts) {
+  if (!rawAccounts || typeof rawAccounts !== 'object') return {};
+  const accounts = {};
+
+  for (const [accountId, raw] of Object.entries(rawAccounts)) {
+    if (!raw || typeof raw !== 'object') continue;
+    accounts[accountId] = {
+      enabled: raw.enabled !== false,
+      backendUrl: toString(raw.backendUrl),
+      deviceToken: toString(raw.deviceToken),
+      defaultSessionKey: toString(raw.defaultSessionKey, DEFAULT_SESSION_KEY),
+      requestTimeoutMs: toNumber(raw.requestTimeoutMs, DEFAULT_TIMEOUT_MS, { min: 2000, max: 120000 }),
+    };
+  }
+
+  return accounts;
+}
+
+function normalizeConfig(cfg = {}) {
+  const channelConfig = cfg?.channels?.[CHANNEL_ID] || {};
+  const configuredAccounts = parseAccounts(channelConfig.accounts);
+  const accountIds = Object.keys(configuredAccounts);
+  const defaultAccountId = toString(channelConfig.defaultAccountId, accountIds[0] || 'default');
+
+  if (!configuredAccounts[defaultAccountId]) {
+    configuredAccounts[defaultAccountId] = {
+      enabled: true,
+      backendUrl: '',
+      deviceToken: '',
+      defaultSessionKey: DEFAULT_SESSION_KEY,
+      requestTimeoutMs: DEFAULT_TIMEOUT_MS,
+    };
+  }
+
+  return {
+    defaultAccountId,
+    accounts: configuredAccounts,
+  };
+}
+
+function resolveAccount(cfg, accountId) {
+  const normalized = normalizeConfig(cfg);
+  const resolvedId = toString(accountId, normalized.defaultAccountId);
+  const account = normalized.accounts[resolvedId];
+  if (!account) {
+    return {
+      accountId: resolvedId,
+      account: null,
+    };
+  }
+
+  return {
+    accountId: resolvedId,
+    account,
+  };
+}
+
+function extractText(payload) {
+  if (!payload) return '';
+  if (typeof payload === 'string') return payload.trim();
+
+  const direct = [payload.text, payload.message, payload.content, payload.body];
+  for (const value of direct) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+
+  if (Array.isArray(payload.content)) {
+    return payload.content
+      .filter((part) => part && typeof part === 'object' && part.type === 'text' && typeof part.text === 'string')
+      .map((part) => part.text.trim())
+      .filter(Boolean)
+      .join('\n');
+  }
+
+  return '';
+}
+
+function extractConversationKey(payload) {
+  const candidates = [
+    payload?.conversationKey,
+    payload?.threadId,
+    payload?.target?.conversationKey,
+    payload?.target?.threadId,
+    payload?.target?.id,
+    payload?.metadata?.conversationKey,
+    payload?.metadata?.threadId,
+  ];
+
+  for (const candidate of candidates) {
+    const value = toString(candidate);
+    if (value) return value;
+  }
+
+  return '';
+}
+
+function extractUserId(payload) {
+  const candidates = [
+    payload?.userId,
+    payload?.target?.userId,
+    payload?.metadata?.userId,
+  ];
+
+  for (const candidate of candidates) {
+    const value = toString(candidate);
+    if (value) return value;
+  }
+
+  return '';
+}
+
+async function postJson({ url, token, body, timeoutMs }) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    const payload = await response.json().catch(() => ({}));
+    return {
+      ok: response.ok,
+      status: response.status,
+      payload,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+const oomiChannelPlugin = {
+  id: CHANNEL_ID,
+  meta: {
+    name: 'Oomi',
+    description: 'Managed Oomi channel plugin.',
+  },
+  capabilities: {
+    chatTypes: ['direct'],
+    media: {
+      images: false,
+      audio: false,
+      files: false,
+    },
+    threads: true,
+  },
+
+  config(cfg) {
+    return normalizeConfig(cfg);
+  },
+
+  listAccountIds(cfg) {
+    const normalized = normalizeConfig(cfg);
+    return Object.entries(normalized.accounts)
+      .filter(([, account]) => account.enabled !== false)
+      .map(([accountId]) => accountId);
+  },
+
+  outbound: {
+    deliveryMode: 'direct',
+
+    async sendText(payload = {}) {
+      const { cfg, accountId } = payload;
+      const { accountId: resolvedAccountId, account } = resolveAccount(cfg, accountId);
+
+      if (!account || account.enabled === false) {
+        return {
+          ok: false,
+          error: `oomi account is disabled or missing (${resolvedAccountId})`,
+        };
+      }
+      if (!account.backendUrl || !account.deviceToken) {
+        return {
+          ok: false,
+          error: `oomi account is missing backendUrl/deviceToken (${resolvedAccountId})`,
+        };
+      }
+
+      const content = extractText(payload);
+      if (!content) {
+        return {
+          ok: false,
+          error: 'oomi outbound message content is empty',
+        };
+      }
+
+      const conversationKey = extractConversationKey(payload);
+      const userId = extractUserId(payload);
+      const sessionKey = toString(payload?.sessionKey || payload?.metadata?.sessionKey, account.defaultSessionKey);
+
+      const response = await postJson({
+        url: `${account.backendUrl}/v1/channel/plugin/messages`,
+        token: account.deviceToken,
+        timeoutMs: account.requestTimeoutMs,
+        body: {
+          conversationKey,
+          userId,
+          sessionKey,
+          content,
+          source: 'openclaw.channel',
+          metadata: {
+            accountId: resolvedAccountId,
+          },
+        },
+      });
+
+      if (!response.ok) {
+        const reason = toString(response.payload?.error, `status ${response.status}`);
+        return {
+          ok: false,
+          error: `oomi plugin message publish failed: ${reason}`,
+        };
+      }
+
+      return {
+        ok: true,
+        providerMessageId: toString(response.payload?.message?.messageId),
+      };
+    },
+  },
+};
+
+export default function register(api) {
+  api.registerChannel({ plugin: oomiChannelPlugin });
+}

package/openclaw.plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "oomi-ai",
+  "name": "Oomi Channel Plugin",
+  "description": "Managed Oomi channel integration for OpenClaw.",
+  "version": "0.2.1",
+  "author": "Oomi",
+  "license": "MIT",
+  "openclawVersion": ">=0.5.0",
+  "channels": [
+    "oomi"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Oomi CLI for OpenClaw setup",
   "bin": {
     "oomi": "bin/oomi-ai.js"
@@ -9,6 +9,26 @@
   "engines": {
     "node": ">=18"
   },
+  "openclaw": {
+    "extensions": [
+      "./openclaw.extension.js"
+    ],
+    "channel": {
+      "id": "oomi",
+      "label": "Oomi",
+      "selectionLabel": "Oomi (Managed)",
+      "docsPath": "/channels/oomi",
+      "docsLabel": "oomi",
+      "blurb": "Managed channel transport for Oomi chat.",
+      "aliases": [
+        "oomi-ai"
+      ]
+    },
+    "install": {
+      "npmSpec": "oomi-ai",
+      "defaultChoice": "npm"
+    }
+  },
   "keywords": [
     "oomi",
     "openclaw",
@@ -19,23 +39,25 @@
   "homepage": "https://oomi.ai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/crispcode-io/oomi.git",
+    "url": "git+https://github.com/crispcode-io/oomi.git",
     "directory": "packages/oomi-ai"
   },
   "bugs": {
     "url": "https://github.com/crispcode-io/oomi/issues"
   },
+  "scripts": {
+    "check": "node --check bin/oomi-ai.js"
+  },
   "dependencies": {
     "ws": "^8.19.0"
   },
   "license": "MIT",
   "files": [
     "bin/oomi-ai.js",
+    "openclaw.plugin.json",
+    "openclaw.extension.js",
     "agent_instructions.md",
     "README.md",
     "skills/oomi"
-  ],
-  "scripts": {
-    "check": "node --check bin/oomi-ai.js"
-  }
-}
+  ]
+}

package/skills/oomi/agent_instructions.md

@@ -15,10 +15,21 @@ Aliases allowed (if needed): wave -> Waving, walk -> Walking, idle -> Idle, sit/
 
 If the user asks to connect OpenClaw to Oomi voice/web:
 
-1. Ensure `oomi-ai` is installed (`pnpm add -g oomi-ai`).
-2. Run:
-   - `oomi openclaw pair --app-url https://oomi.ai --detach`
-3. Return this exact result format to the user:
+1. Refresh bootstrap/update 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:
+   - `oomi openclaw pair --app-url https://www.oomi.ai --no-start`
+4. Install OpenClaw plugin:
+   - `openclaw plugins install oomi-ai@latest`
+5. Configure channel account (`channels.oomi.accounts.default`) from:
+   - `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai`
+6. Restart OpenClaw.
+7. 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`
+8. Return this exact result format to the user:
    - `Oomi Connect Ready`
    - `Code: ...`
    - `Link: ...`