oomi-ai 0.2.1 → 0.2.2

package/README.md

@@ -14,31 +14,36 @@ npm install -g oomi-ai
 
 ## Usage
 
-Install agent instructions only:
+Install as an OpenClaw channel extension (preferred architecture):
 ```
-oomi init
+openclaw plugins install oomi-ai@latest
 ```
 
-Install agent instructions + Oomi skill:
+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 install
+oomi openclaw plugin
 ```
 
-Start managed gateway bridge (OpenClaw host -> Oomi broker):
+Install agent instructions only:
 ```
-oomi openclaw bridge \
-  --broker-http https://your-signaling-service.example.com \
-  --broker-ws wss://your-signaling-service.example.com/cable \
-  --pair-code ABCD2345
+oomi init
 ```
 
-Bridge env config:
-- `OOMI_CHAT_BROKER_HTTP_URL`
-- `OOMI_CHAT_BROKER_DEVICE_WS_URL`
+Install agent instructions + Oomi skill:
+```
+oomi openclaw install
+```
 
-Pair + bootstrap bridge automatically from Oomi web backend:
+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 --detach
+oomi openclaw pair --app-url https://your-oomi-app.vercel.app --device-id my-openclaw-mac --no-start
 ```
 
 `--app-url` must be reachable from the OpenClaw host. If OpenClaw runs on a different machine/network, do not use `localhost` unless tunneled.
@@ -56,9 +61,10 @@ Agent-intent mapping (recommended):
 - 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 --detach`
-- If already paired and reconnecting:
-  - `oomi openclaw bridge --detach`
+  - `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.
@@ -79,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://.../cable --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

package/agent_instructions.md

@@ -19,14 +19,17 @@ If the user asks to connect OpenClaw to Oomi voice/web:
    - `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. Run:
-   - `oomi openclaw pair --app-url https://www.oomi.ai --detach`
-4. If already paired and reconnecting:
-   - `oomi openclaw bridge --detach`
-5. If user provides an app URL (for example "Connect yourself to Oomi. Use app URL <URL>."):
+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> --detach`
-6. Return this exact result format to the user:
+   - 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

@@ -142,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.
 
@@ -162,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
@@ -614,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;
@@ -818,10 +833,19 @@ async function startOpenclawBridge(flags) {
           sendBrokerPayload(brokerSocket, { action: 'gateway_frame', type: 'gateway.frame', sessionId, frame });
         });
 
-        gatewaySocket.on('close', () => {
-          console.log(`[bridge] gateway.close ${sessionId}`);
+        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);
-          sendBrokerPayload(brokerSocket, { action: 'gateway_closed', type: 'gateway.closed', sessionId });
+          sendBrokerPayload(brokerSocket, {
+            action: 'gateway_closed',
+            type: 'gateway.closed',
+            sessionId,
+            code,
+            reason: reasonText,
+          });
         });
 
         gatewaySocket.on('error', (err) => {
@@ -1009,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;
@@ -1050,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.1",
+  "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,7 +39,7 @@
   "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": {
@@ -34,6 +54,8 @@
   "license": "MIT",
   "files": [
     "bin/oomi-ai.js",
+    "openclaw.plugin.json",
+    "openclaw.extension.js",
     "agent_instructions.md",
     "README.md",
     "skills/oomi"

package/skills/oomi/agent_instructions.md

@@ -19,14 +19,17 @@ If the user asks to connect OpenClaw to Oomi voice/web:
    - `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. Run:
-   - `oomi openclaw pair --app-url https://www.oomi.ai --detach`
-4. If already paired and reconnecting:
-   - `oomi openclaw bridge --detach`
-5. If user provides an app URL (for example "Connect yourself to Oomi. Use app URL <URL>."):
+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> --detach`
-6. Return this exact result format to the user:
+   - Example: `oomi openclaw pair --app-url <URL> --no-start`
+8. Return this exact result format to the user:
    - `Oomi Connect Ready`
    - `Code: ...`
    - `Link: ...`