oomi-ai 0.2.4 → 0.2.5

package/bin/oomi-ai.js

@@ -4,6 +4,8 @@ import os from 'os';
 import path from 'path';
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
+import net from 'net';
+import { lookup as dnsLookup } from 'dns/promises';
 import WebSocket from 'ws';
 import { ensureSessionBridge, forwardFrameToSession, flushSessionQueue } from './sessionBridgeState.js';
 
@@ -14,6 +16,8 @@ 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;
+const BRIDGE_RECONNECT_BASE_MS = 2000;
+const BRIDGE_RECONNECT_MAX_MS = 60000;
 
 function parsePositiveInteger(value, fallback) {
   const num = Number(value);
@@ -149,6 +153,9 @@ Commands:
   openclaw plugin
     Print OpenClaw extension install/config guidance for Oomi channel plugin.
 
+  openclaw status
+    Show bridge state + runtime health from local status files.
+
   personas sync
     Sync personas from the repo into the Oomi backend registry.
 
@@ -162,7 +169,7 @@ Common flags:
   --broker-http URL      Managed broker HTTPS URL (for pair claim)
   --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:3456)
+  --app-url URL          Oomi app URL used for pairing APIs; bridge can also refresh managed broker URLs from it
   --label TEXT           Pairing label shown in broker logs
   --session-key KEY      Session key used in generated connect URL
   --detach               Start bridge in background and exit
@@ -537,6 +544,10 @@ function resolveBridgeStatePath() {
   return path.join(os.homedir(), '.openclaw', 'oomi-bridge.json');
 }
 
+function resolveBridgeStatusPath() {
+  return path.join(os.homedir(), '.openclaw', 'oomi-bridge-status.json');
+}
+
 function defaultDeviceId() {
   const host = os.hostname().toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'openclaw';
   return `oomi-${host}-${randomUUID().slice(0, 8)}`;
@@ -566,6 +577,27 @@ function writeBridgeState(nextState) {
   writeFile(statePath, JSON.stringify(nextState, null, 2) + '\n');
 }
 
+function readBridgeStatus() {
+  return readJsonSafe(resolveBridgeStatusPath()) || {};
+}
+
+function writeBridgeStatus(nextStatus) {
+  const statusPath = resolveBridgeStatusPath();
+  ensureDir(path.dirname(statusPath));
+  writeFile(statusPath, JSON.stringify(nextStatus, null, 2) + '\n');
+}
+
+function updateBridgeStatus(partial) {
+  const current = readBridgeStatus();
+  const next = {
+    ...current,
+    ...partial,
+    updatedAt: new Date().toISOString(),
+  };
+  writeBridgeStatus(next);
+  return next;
+}
+
 async function claimBridgeDeviceToken({ brokerHttp, pairCode, deviceId }) {
   const response = await fetch(`${brokerHttp.replace(/\/$/, '')}/v1/pair/claim`, {
     method: 'POST',
@@ -674,29 +706,219 @@ function parseJsonPayload(raw) {
   }
 }
 
+function bridgeNowIso() {
+  return new Date().toISOString();
+}
+
+function extractErrorCode(err) {
+  if (!err || typeof err !== 'object') return '';
+  const value = err.code;
+  return typeof value === 'string' ? value.trim().toUpperCase() : '';
+}
+
+function extractErrorMessage(err) {
+  if (!err) return '';
+  if (typeof err === 'string') return err.trim();
+  if (err instanceof Error) return err.message.trim();
+  return String(err).trim();
+}
+
+function classifyBridgeFailure({ err, reason = '', code = '', forceClass = '' } = {}) {
+  const errorCode = (code || extractErrorCode(err)).toUpperCase();
+  const message = [extractErrorMessage(err), String(reason || '').trim()].filter(Boolean).join(' | ');
+  const text = `${errorCode} ${message}`.toLowerCase();
+
+  let failureClass = forceClass || 'unknown';
+  let retryable = true;
+  let hint = 'Check broker URL, network path, and bridge token.';
+  let baseDelayMs = BRIDGE_RECONNECT_BASE_MS;
+
+  if (
+    errorCode === 'ENOTFOUND' ||
+    errorCode === 'EAI_AGAIN' ||
+    text.includes('enotfound') ||
+    text.includes('name resolution') ||
+    text.includes('dns')
+  ) {
+    failureClass = 'dns_resolution';
+    hint = 'Host resolution failed. Verify DNS/network access to the broker host.';
+    baseDelayMs = 5000;
+  } else if (
+    text.includes('unauthorized') ||
+    text.includes('forbidden') ||
+    text.includes('invalid token') ||
+    text.includes('token expired') ||
+    text.includes('broker rejected')
+  ) {
+    failureClass = 'auth_rejected';
+    retryable = false;
+    hint = 'Bridge token is invalid/expired. Re-run: oomi openclaw pair --app-url <url>.';
+    baseDelayMs = BRIDGE_RECONNECT_MAX_MS;
+  } else if (
+    errorCode === 'ECONNREFUSED' ||
+    errorCode === 'ENETUNREACH' ||
+    errorCode === 'EHOSTUNREACH' ||
+    errorCode === 'ETIMEDOUT' ||
+    text.includes('socket hang up') ||
+    text.includes('abnormal closure')
+  ) {
+    failureClass = 'network';
+    hint = 'Broker network path is unavailable. Check connectivity/firewall/proxy settings.';
+    baseDelayMs = 3000;
+  }
+
+  return {
+    errorCode: errorCode || 'UNKNOWN',
+    message: message || 'unknown bridge error',
+    failureClass,
+    retryable,
+    hint,
+    baseDelayMs,
+  };
+}
+
+function computeReconnectDelayMs(attempt, baseDelayMs) {
+  const growth = Math.min(BRIDGE_RECONNECT_MAX_MS, Math.round(baseDelayMs * (2 ** Math.max(0, attempt - 1))));
+  const jitter = Math.floor(growth * (Math.random() * 0.25));
+  return Math.min(BRIDGE_RECONNECT_MAX_MS, growth + jitter);
+}
+
+async function assertTcpReachable(urlValue, timeoutMs = 1500) {
+  const url = new URL(urlValue);
+  const host = url.hostname || '127.0.0.1';
+  const port = Number(url.port || (url.protocol === 'wss:' || url.protocol === 'https:' ? 443 : 80));
+  if (!Number.isFinite(port) || port <= 0) {
+    throw new Error(`Invalid port in URL: ${urlValue}`);
+  }
+
+  await new Promise((resolve, reject) => {
+    const socket = net.connect({ host, port });
+    let finished = false;
+    const done = (fn) => (value) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      socket.destroy();
+      fn(value);
+    };
+    const timer = setTimeout(done(reject), timeoutMs, new Error(`TCP connect timeout (${host}:${port})`));
+    socket.once('connect', done(resolve));
+    socket.once('error', done(reject));
+  });
+}
+
+async function runBridgePreflight({ brokerWs, gatewayUrl, gatewayConfigPath }) {
+  let brokerUrl;
+  try {
+    brokerUrl = new URL(brokerWs);
+  } catch {
+    throw new Error(`Invalid broker WS URL: ${brokerWs}`);
+  }
+  if (brokerUrl.protocol !== 'ws:' && brokerUrl.protocol !== 'wss:') {
+    throw new Error(`Broker WS URL must use ws:// or wss:// (received ${brokerUrl.protocol})`);
+  }
+
+  const brokerHost = brokerUrl.hostname;
+  if (!brokerHost) {
+    throw new Error('Broker WS URL is missing hostname.');
+  }
+  await dnsLookup(brokerHost);
+
+  let parsedGatewayUrl;
+  try {
+    parsedGatewayUrl = new URL(gatewayUrl);
+  } catch {
+    throw new Error(`Invalid local gateway URL (${gatewayUrl}) from ${gatewayConfigPath}`);
+  }
+  if (parsedGatewayUrl.protocol !== 'ws:') {
+    throw new Error(`Local gateway URL must use ws:// (received ${parsedGatewayUrl.protocol})`);
+  }
+  await assertTcpReachable(parsedGatewayUrl.toString());
+}
+
+function buildBridgeDetachArgs(rawFlags = {}) {
+  const orderedKeys = [
+    'broker-http',
+    'broker-ws',
+    'pair-code',
+    'app-url',
+    'device-id',
+    'device-token',
+  ];
+  const args = [process.argv[1], 'openclaw', 'bridge'];
+
+  for (const key of orderedKeys) {
+    const value = rawFlags[key];
+    if (value === undefined || value === null || value === false) continue;
+    if (value === true) {
+      args.push(`--${key}`);
+      continue;
+    }
+    const text = String(value).trim();
+    if (!text) continue;
+    args.push(`--${key}`, text);
+  }
+
+  return args;
+}
+
+function startBridgeDetachedProcess(rawFlags = {}) {
+  const args = buildBridgeDetachArgs(rawFlags);
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  return child.pid;
+}
+
+async function resolveBridgeRuntimeConfig(flags, bridgeState) {
+  const explicitBrokerHttp = String(flags['broker-http'] || '').trim();
+  const explicitBrokerWs = String(flags['broker-ws'] || '').trim();
+  const appUrl = String(flags['app-url'] || process.env.OOMI_APP_URL || '').trim();
+
+  let brokerHttp = String(explicitBrokerHttp || process.env.OOMI_CHAT_BROKER_HTTP_URL || bridgeState.brokerHttp || '').trim();
+  let brokerWs = String(explicitBrokerWs || process.env.OOMI_CHAT_BROKER_DEVICE_WS_URL || bridgeState.brokerWs || '').trim();
+  let managedConfigUsed = false;
+  let managedConfigError = '';
+
+  if (appUrl && (!explicitBrokerHttp || !explicitBrokerWs)) {
+    try {
+      const managedConfig = await fetchManagedGatewayConfig({ appUrl });
+      managedConfigUsed = true;
+      if (!explicitBrokerHttp) {
+        brokerHttp = String(managedConfig.brokerHttpUrl || '').trim();
+      }
+      if (!explicitBrokerWs) {
+        brokerWs = String(managedConfig.brokerDeviceWsUrl || '').trim();
+      }
+    } catch (err) {
+      managedConfigError = extractErrorMessage(err);
+      if (!brokerWs) {
+        throw err;
+      }
+    }
+  }
+
+  return {
+    appUrl,
+    brokerHttp,
+    brokerWs,
+    managedConfigUsed,
+    managedConfigError,
+  };
+}
+
 async function startOpenclawBridge(flags) {
   const bridgeState = readBridgeState();
-  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 runtimeConfig = await resolveBridgeRuntimeConfig(flags, bridgeState);
+  const brokerHttp = runtimeConfig.brokerHttp;
+  const brokerWs = runtimeConfig.brokerWs;
   const deviceId = resolveDeviceId(flags, bridgeState);
   const pairCode = String(flags['pair-code'] || '').trim().toUpperCase();
   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) {
+  if (!deviceToken && String(bridgeState.deviceId || '').trim() === deviceId) {
     deviceToken = String(bridgeState.deviceToken || '').trim();
   }
 
@@ -731,11 +953,64 @@ async function startOpenclawBridge(flags) {
     throw new Error(`Gateway auth token/password not found in ${gateway.configPath}.`);
   }
 
+  if (runtimeConfig.managedConfigUsed && runtimeConfig.appUrl) {
+    console.log(`[bridge] refreshed broker URLs from ${runtimeConfig.appUrl}`);
+  } else if (runtimeConfig.managedConfigError) {
+    console.warn(
+      `[bridge] failed to refresh broker URLs from app URL; using local/state broker config (${runtimeConfig.managedConfigError})`
+    );
+  }
+
+  try {
+    await runBridgePreflight({
+      brokerWs,
+      gatewayUrl: gateway.gatewayUrl,
+      gatewayConfigPath: gateway.configPath,
+    });
+  } catch (err) {
+    const failure = classifyBridgeFailure({ err });
+    updateBridgeStatus({
+      status: 'error',
+      deviceId,
+      brokerWs,
+      brokerHttp,
+      gatewayUrl: gateway.gatewayUrl,
+      lastDisconnectAt: bridgeNowIso(),
+      lastErrorCode: failure.errorCode,
+      lastErrorClass: failure.failureClass,
+      lastErrorMessage: failure.message,
+      hint: failure.hint,
+      consecutiveFailures: 0,
+      pid: process.pid,
+    });
+    throw new Error(`Bridge preflight failed (${failure.failureClass}): ${failure.message}. ${failure.hint}`);
+  }
+
+  updateBridgeStatus({
+    status: 'starting',
+    deviceId,
+    brokerWs,
+    brokerHttp,
+    gatewayUrl: gateway.gatewayUrl,
+    lastErrorCode: '',
+    lastErrorClass: '',
+    lastErrorMessage: '',
+    consecutiveFailures: 0,
+    pid: process.pid,
+    startedAt: bridgeNowIso(),
+  });
+
   console.log(`Starting OpenClaw bridge: device=${deviceId}`);
   console.log(`Local gateway: ${gateway.gatewayUrl}`);
   console.log(`Broker WS: ${brokerWs}`);
 
   const activeGatewaySockets = new Map();
+  const reconnectState = {
+    attempt: 0,
+    timer: null,
+    stopped: false,
+    lastFailure: null,
+  };
   const brokerPath = (() => {
     try {
       return new URL(brokerWs).pathname || '';
@@ -785,6 +1060,39 @@ async function startOpenclawBridge(flags) {
     return null;
   };
 
+  const scheduleReconnect = () => {
+    if (reconnectState.stopped || reconnectState.timer) return;
+    reconnectState.attempt += 1;
+    const failure =
+      reconnectState.lastFailure ||
+      classifyBridgeFailure({ reason: 'connection closed without classified error' });
+    const delayMs = computeReconnectDelayMs(reconnectState.attempt, failure.baseDelayMs);
+
+    console.warn(
+      `[bridge] reconnect scheduled in ${delayMs}ms (attempt ${reconnectState.attempt}, class=${failure.failureClass}, code=${failure.errorCode})`
+    );
+
+    updateBridgeStatus({
+      status: 'reconnecting',
+      deviceId,
+      brokerWs,
+      brokerHttp,
+      gatewayUrl: gateway.gatewayUrl,
+      lastDisconnectAt: bridgeNowIso(),
+      lastErrorCode: failure.errorCode,
+      lastErrorClass: failure.failureClass,
+      lastErrorMessage: failure.message,
+      hint: failure.hint,
+      consecutiveFailures: reconnectState.attempt,
+      pid: process.pid,
+    });
+
+    reconnectState.timer = setTimeout(() => {
+      reconnectState.timer = null;
+      connectBroker();
+    }, delayMs);
+  };
+
   const connectBroker = () => {
     const wsUrl = new URL(brokerWs);
     wsUrl.searchParams.set('token', deviceToken);
@@ -846,6 +1154,8 @@ async function startOpenclawBridge(flags) {
 
     brokerSocket.on('open', () => {
       console.log('[bridge] Connected to managed broker.');
+      reconnectState.attempt = 0;
+      reconnectState.lastFailure = null;
       if (!actionCableMode) return;
       brokerSocket.send(
         JSON.stringify({
@@ -856,6 +1166,20 @@ async function startOpenclawBridge(flags) {
       actionCableHeartbeat = setInterval(() => {
         sendBrokerPayload(brokerSocket, { action: 'heartbeat' });
       }, 15000);
+      updateBridgeStatus({
+        status: 'connected',
+        deviceId,
+        brokerWs,
+        brokerHttp,
+        gatewayUrl: gateway.gatewayUrl,
+        lastConnectedAt: bridgeNowIso(),
+        lastErrorCode: '',
+        lastErrorClass: '',
+        lastErrorMessage: '',
+        hint: '',
+        consecutiveFailures: 0,
+        pid: process.pid,
+      });
     });
 
     brokerSocket.on('message', (rawData) => {
@@ -868,12 +1192,61 @@ async function startOpenclawBridge(flags) {
       }
 
       if (payload.type === 'broker.disconnect') {
+        reconnectState.lastFailure = classifyBridgeFailure({
+          reason: String(payload.reason || 'unauthorized'),
+          forceClass: 'auth_rejected',
+        });
+        reconnectState.stopped = true;
         console.error(`[bridge] Broker rejected connection: ${String(payload.reason || 'unauthorized')}`);
+        console.error(`[bridge] ${reconnectState.lastFailure.hint}`);
+        updateBridgeStatus({
+          status: 'error',
+          deviceId,
+          brokerWs,
+          brokerHttp,
+          gatewayUrl: gateway.gatewayUrl,
+          lastDisconnectAt: bridgeNowIso(),
+          lastErrorCode: reconnectState.lastFailure.errorCode,
+          lastErrorClass: reconnectState.lastFailure.failureClass,
+          lastErrorMessage: reconnectState.lastFailure.message,
+          hint: reconnectState.lastFailure.hint,
+          consecutiveFailures: reconnectState.attempt + 1,
+          pid: process.pid,
+        });
+        try {
+          brokerSocket.close(4001, 'auth_rejected');
+        } catch {
+          // no-op
+        }
         return;
       }
 
       if (payload.type === 'broker.reject_subscription') {
         console.error('[bridge] Broker rejected DeviceChannel subscription.');
+        reconnectState.lastFailure = classifyBridgeFailure({
+          reason: 'broker rejected DeviceChannel subscription',
+          forceClass: 'auth_rejected',
+        });
+        reconnectState.stopped = true;
+        updateBridgeStatus({
+          status: 'error',
+          deviceId,
+          brokerWs,
+          brokerHttp,
+          gatewayUrl: gateway.gatewayUrl,
+          lastDisconnectAt: bridgeNowIso(),
+          lastErrorCode: reconnectState.lastFailure.errorCode,
+          lastErrorClass: reconnectState.lastFailure.failureClass,
+          lastErrorMessage: reconnectState.lastFailure.message,
+          hint: reconnectState.lastFailure.hint,
+          consecutiveFailures: reconnectState.attempt + 1,
+          pid: process.pid,
+        });
+        try {
+          brokerSocket.close(4002, 'subscription_rejected');
+        } catch {
+          // no-op
+        }
         return;
       }
 
@@ -924,7 +1297,8 @@ async function startOpenclawBridge(flags) {
         clearInterval(actionCableHeartbeat);
         actionCableHeartbeat = null;
       }
-      console.log(`[bridge] Broker disconnected (${code}) ${reason.toString()}`);
+      const reasonText = reason ? reason.toString() : '';
+      console.log(`[bridge] Broker disconnected (${code}) ${reasonText}`);
       for (const [sessionId, sessionBridge] of activeGatewaySockets.entries()) {
         activeGatewaySockets.delete(sessionId);
         try {
@@ -933,13 +1307,48 @@ async function startOpenclawBridge(flags) {
           // no-op
         }
       }
-      setTimeout(connectBroker, 2000);
+
+      if (reconnectState.stopped) {
+        return;
+      }
+
+      if (!reconnectState.lastFailure) {
+        reconnectState.lastFailure = classifyBridgeFailure({
+          reason: `socket closed code=${String(code)}${reasonText ? ` reason=${reasonText}` : ''}`,
+        });
+      }
+      scheduleReconnect();
     });
 
     brokerSocket.on('error', (err) => {
-      console.error('[bridge] Broker socket error:', err);
+      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}`);
+    });
+  };
+
+  const markStopped = (signal) => {
+    reconnectState.stopped = true;
+    if (reconnectState.timer) {
+      clearTimeout(reconnectState.timer);
+      reconnectState.timer = null;
+    }
+    updateBridgeStatus({
+      status: 'stopped',
+      deviceId,
+      brokerWs,
+      brokerHttp,
+      gatewayUrl: gateway.gatewayUrl,
+      lastDisconnectAt: bridgeNowIso(),
+      stopSignal: signal,
+      pid: process.pid,
     });
+    process.exit(0);
   };
+  process.once('SIGINT', () => markStopped('SIGINT'));
+  process.once('SIGTERM', () => markStopped('SIGTERM'));
 
   connectBroker();
   await new Promise(() => {});
@@ -1030,25 +1439,13 @@ async function pairAndStartOpenclawBridge(flags) {
   }
 
   if (detach) {
-    const args = [
-      process.argv[1],
-      'openclaw',
-      'bridge',
-      '--broker-http',
-      managedConfig.brokerHttpUrl,
-      '--broker-ws',
-      brokerWs,
-      '--device-id',
-      deviceId,
-      '--device-token',
-      deviceToken,
-    ];
-    const child = spawn(process.execPath, args, {
-      detached: true,
-      stdio: 'ignore',
+    const pid = startBridgeDetachedProcess({
+      'broker-http': managedConfig.brokerHttpUrl,
+      'broker-ws': brokerWs,
+      'device-id': deviceId,
+      'device-token': deviceToken,
     });
-    child.unref();
-    console.log(`Bridge started in background (pid: ${child.pid}).`);
+    console.log(`Bridge started in background (pid: ${pid}).`);
     return;
   }
 
@@ -1116,6 +1513,69 @@ async function createOpenclawInviteLink(flags) {
   }
 }
 
+function printOpenclawBridgeStatus(flags) {
+  const bridgeState = readBridgeState();
+  const runtimeStatus = readBridgeStatus();
+  const jsonOutput = isTruthyFlag(flags.json);
+  const redactToken = (value) => {
+    const text = String(value || '').trim();
+    if (!text) return '';
+    if (text.length <= 12) return '***';
+    return `${text.slice(0, 6)}...${text.slice(-6)}`;
+  };
+
+  const payload = {
+    bridgeStatePath: resolveBridgeStatePath(),
+    bridgeStatusPath: resolveBridgeStatusPath(),
+    bridgeState: {
+      brokerHttp: String(bridgeState.brokerHttp || ''),
+      brokerWs: String(bridgeState.brokerWs || ''),
+      deviceId: String(bridgeState.deviceId || ''),
+      deviceToken: redactToken(bridgeState.deviceToken),
+      claimedAt: bridgeState.claimedAt || null,
+      expiresAt: bridgeState.expiresAt || null,
+    },
+    runtime: runtimeStatus,
+  };
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('Oomi Bridge Status');
+  console.log('------------------');
+  console.log(`Bridge state: ${payload.bridgeStatePath}`);
+  console.log(`Runtime status: ${payload.bridgeStatusPath}`);
+  console.log(`Device: ${payload.bridgeState.deviceId || 'not paired'}`);
+  console.log(`Broker HTTP: ${payload.bridgeState.brokerHttp || 'not configured'}`);
+  console.log(`Broker WS: ${payload.bridgeState.brokerWs || 'not configured'}`);
+  if (payload.bridgeState.deviceToken) {
+    console.log(`Device token: ${payload.bridgeState.deviceToken}`);
+  }
+  if (payload.runtime && typeof payload.runtime === 'object' && Object.keys(payload.runtime).length > 0) {
+    console.log(`Runtime state: ${String(payload.runtime.status || 'unknown')}`);
+    if (payload.runtime.lastConnectedAt) {
+      console.log(`Last connected: ${payload.runtime.lastConnectedAt}`);
+    }
+    if (payload.runtime.lastDisconnectAt) {
+      console.log(`Last disconnected: ${payload.runtime.lastDisconnectAt}`);
+    }
+    if (payload.runtime.lastErrorClass || payload.runtime.lastErrorCode || payload.runtime.lastErrorMessage) {
+      console.log(
+        `Last error: ${String(payload.runtime.lastErrorClass || 'unknown')}/${String(payload.runtime.lastErrorCode || 'UNKNOWN')} ${String(payload.runtime.lastErrorMessage || '').trim()}`
+      );
+    }
+    if (payload.runtime.hint) {
+      console.log(`Hint: ${payload.runtime.hint}`);
+    }
+    return;
+  }
+
+  console.log('Runtime state: no bridge runtime status recorded yet.');
+  console.log('Run: oomi openclaw bridge --app-url https://www.oomi.ai');
+}
+
 function printOpenclawPluginSetup(flags) {
   const bridgeState = readBridgeState();
   const backendUrl = String(
@@ -1215,6 +1675,13 @@ async function main() {
   }
 
   if (command === 'openclaw' && subcommand === 'bridge') {
+    if (Boolean(args.flags.detach)) {
+      const detachedFlags = { ...args.flags };
+      delete detachedFlags.detach;
+      const pid = startBridgeDetachedProcess(detachedFlags);
+      console.log(`Bridge started in background (pid: ${pid}).`);
+      return;
+    }
     await startOpenclawBridge(args.flags);
     return;
   }
@@ -1229,6 +1696,11 @@ async function main() {
     return;
   }
 
+  if (command === 'openclaw' && subcommand === 'status') {
+    printOpenclawBridgeStatus(args.flags);
+    return;
+  }
+
   if (command === 'openclaw' && subcommand === 'plugin') {
     printOpenclawPluginSetup(args.flags);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Oomi CLI for OpenClaw setup",
   "bin": {
     "oomi": "bin/oomi-ai.js"