oomi-ai 0.2.10 → 0.2.13

package/README.md

@@ -65,9 +65,20 @@ oomi openclaw bridge ensure --detach   # start if needed; no-op if already runni
 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`.
 
+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:
@@ -121,6 +132,12 @@ Restart OpenClaw after running `oomi init` or `oomi openclaw install`.
   - `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
+```
 
 ## Package Audit + Publish (pnpm)
 ```

package/agent_instructions.md

@@ -29,6 +29,7 @@ If the user asks to connect OpenClaw to Oomi voice/web:
 7. Ensure exactly one bridge worker is running (singleton handler):
    - `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`

package/bin/oomi-ai.js

@@ -6,6 +6,7 @@ import { spawn, spawnSync } from 'child_process';
 import { createPrivateKey, createPublicKey, randomUUID, sign as cryptoSign } from 'crypto';
 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';
 
@@ -26,6 +27,11 @@ const BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS = parsePositiveInteger(
   process.env.OOMI_BRIDGE_CONNECT_CHALLENGE_TIMEOUT_MS,
   3000
 );
+const BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS = parsePositiveInteger(
+  process.env.OOMI_BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS,
+  30000
+);
+const BRIDGE_LAUNCHD_LABEL = 'ai.oomi.bridge';
 const DEVICE_IDENTITY_PATH = path.join(os.homedir(), '.openclaw', 'identity', 'device.json');
 const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
 
@@ -153,6 +159,8 @@ Commands:
 
   openclaw bridge [start|ensure|stop|restart|ps]
     Manage local OpenClaw-to-Oomi bridge lifecycle (singleton).
+  openclaw bridge service [install|start|stop|restart|status|uninstall]
+    Manage macOS launchd bridge supervision.
 
   openclaw pair
     Pair this OpenClaw host with Oomi and start bridge (single command).
@@ -208,6 +216,15 @@ function writeFile(filePath, content, options = undefined) {
   fs.writeFileSync(filePath, content, options);
 }
 
+function xmlEscape(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
 function resolveWorkspace() {
   const envWorkspace = process.env.OPENCLAW_WORKSPACE || process.env.OPENCLAW_HOME;
   if (envWorkspace) return envWorkspace;
@@ -562,6 +579,14 @@ function resolveBridgeLockPath() {
   return path.join(os.homedir(), '.openclaw', 'oomi-bridge.lock');
 }
 
+function resolveBridgeLiveLogPath() {
+  return path.join(os.homedir(), '.openclaw', 'logs', 'oomi-bridge-live.log');
+}
+
+function resolveBridgeLaunchAgentPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${BRIDGE_LAUNCHD_LABEL}.plist`);
+}
+
 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)}`;
@@ -612,6 +637,28 @@ function updateBridgeStatus(partial) {
   return next;
 }
 
+function normalizeBridgeMetrics(value) {
+  if (!value || typeof value !== 'object') return {};
+  const next = {};
+  for (const [key, raw] of Object.entries(value)) {
+    const parsed = Number(raw);
+    next[key] = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 0;
+  }
+  return next;
+}
+
+function incrementBridgeMetric(metricKey, amount = 1) {
+  const normalizedKey = String(metricKey || '').trim();
+  if (!normalizedKey) return;
+  const delta = Number(amount);
+  if (!Number.isFinite(delta) || delta <= 0) return;
+
+  const current = readBridgeStatus();
+  const metrics = normalizeBridgeMetrics(current.metrics);
+  metrics[normalizedKey] = (metrics[normalizedKey] || 0) + Math.floor(delta);
+  updateBridgeStatus({ metrics });
+}
+
 function normalizePid(value) {
   const pid = Number(value);
   if (!Number.isInteger(pid) || pid <= 0) return null;
@@ -898,15 +945,51 @@ 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 shouldStripBridgeOnlyParams = method === 'chat.send' || method === 'chat.history';
+      if (!shouldStripBridgeOnlyParams) {
+        return { frameText, waitForChallenge: false };
+      }
+      const rawParams = frame.params && typeof frame.params === 'object' ? frame.params : {};
+      const sanitized = { ...rawParams };
+      let changed = false;
+      if (Object.prototype.hasOwnProperty.call(sanitized, 'correlationId')) {
+        delete sanitized.correlationId;
+        changed = true;
+      }
+      if (Object.prototype.hasOwnProperty.call(sanitized, 'metadata')) {
+        delete sanitized.metadata;
+        changed = true;
+      }
+      if (changed) {
+        frame.params = sanitized;
+        return { frameText: JSON.stringify(frame), waitForChallenge: false };
+      }
       return { frameText, waitForChallenge: false };
     }
 
-    const params = frame.params && typeof frame.params === 'object' ? frame.params : {};
+    const rawParams = frame.params && typeof frame.params === 'object' ? frame.params : {};
+    const params = {};
 
-    const client = params.client && typeof params.client === 'object' ? params.client : {};
-    const incomingClientId = typeof client.id === 'string' ? client.id.trim().toLowerCase() : '';
-    const incomingClientMode = typeof client.mode === 'string' ? client.mode.trim().toLowerCase() : '';
+    params.minProtocol = Number.isInteger(rawParams.minProtocol) && rawParams.minProtocol >= 1
+      ? rawParams.minProtocol
+      : 3;
+    params.maxProtocol = Number.isInteger(rawParams.maxProtocol) && rawParams.maxProtocol >= 1
+      ? rawParams.maxProtocol
+      : 3;
+
+    const clientInput = rawParams.client && typeof rawParams.client === 'object' ? rawParams.client : {};
+    const client = {};
+    const incomingClientId = typeof clientInput.id === 'string' ? clientInput.id.trim().toLowerCase() : '';
+    const incomingClientMode = typeof clientInput.mode === 'string' ? clientInput.mode.trim().toLowerCase() : '';
     const proxiedBrowserClient =
       incomingClientMode === 'webchat' ||
       incomingClientId === 'webchat-ui' ||
@@ -918,20 +1001,32 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
     // so Control UI/webchat Origin checks don't reject proxied sessions.
     client.id = proxiedBrowserClient
       ? 'node-host'
-      : (typeof client.id === 'string' && client.id.trim() ? client.id.trim() : 'node-host');
-    client.version = typeof client.version === 'string' && client.version.trim() ? client.version.trim() : '0.1.0';
+      : (typeof clientInput.id === 'string' && clientInput.id.trim() ? clientInput.id.trim() : 'node-host');
+    client.version = typeof clientInput.version === 'string' && clientInput.version.trim() ? clientInput.version.trim() : '0.1.0';
     client.platform = proxiedBrowserClient
       ? process.platform
-      : (typeof client.platform === 'string' && client.platform.trim() ? client.platform.trim() : process.platform);
+      : (typeof clientInput.platform === 'string' && clientInput.platform.trim() ? clientInput.platform.trim() : process.platform);
     client.mode = proxiedBrowserClient
       ? 'backend'
-      : (typeof client.mode === 'string' && client.mode.trim() ? client.mode.trim() : 'backend');
+      : (typeof clientInput.mode === 'string' && clientInput.mode.trim() ? clientInput.mode.trim() : 'backend');
+    if (typeof clientInput.displayName === 'string' && clientInput.displayName.trim()) {
+      client.displayName = clientInput.displayName.trim();
+    }
+    if (typeof clientInput.deviceFamily === 'string' && clientInput.deviceFamily.trim()) {
+      client.deviceFamily = clientInput.deviceFamily.trim();
+    }
+    if (typeof clientInput.modelIdentifier === 'string' && clientInput.modelIdentifier.trim()) {
+      client.modelIdentifier = clientInput.modelIdentifier.trim();
+    }
+    if (typeof clientInput.instanceId === 'string' && clientInput.instanceId.trim()) {
+      client.instanceId = clientInput.instanceId.trim();
+    }
     params.client = client;
 
-    params.role = typeof params.role === 'string' && params.role.trim() ? params.role.trim() : 'operator';
+    params.role = typeof rawParams.role === 'string' && rawParams.role.trim() ? rawParams.role.trim() : 'operator';
 
-    const existingScopes = Array.isArray(params.scopes)
-      ? params.scopes.filter((value) => typeof value === 'string' && value.trim())
+    const existingScopes = Array.isArray(rawParams.scopes)
+      ? rawParams.scopes.filter((value) => typeof value === 'string' && value.trim())
       : [];
     const requiredScopes = ['operator.read', 'operator.write'];
     for (const scope of requiredScopes) {
@@ -941,14 +1036,28 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
     }
     params.scopes = existingScopes;
 
-    if (!Array.isArray(params.caps)) {
-      params.caps = [];
-    }
-    if (!Array.isArray(params.commands)) {
-      params.commands = [];
+    params.caps = Array.isArray(rawParams.caps)
+      ? rawParams.caps.filter((value) => typeof value === 'string' && value.trim())
+      : [];
+
+    params.commands = Array.isArray(rawParams.commands)
+      ? rawParams.commands.filter((value) => typeof value === 'string' && value.trim())
+      : [];
+
+    if (rawParams.permissions && typeof rawParams.permissions === 'object') {
+      const permissions = {};
+      for (const [key, value] of Object.entries(rawParams.permissions)) {
+        const normalizedKey = typeof key === 'string' ? key.trim() : '';
+        if (!normalizedKey || typeof value !== 'boolean') continue;
+        permissions[normalizedKey] = value;
+      }
+      if (Object.keys(permissions).length > 0) {
+        params.permissions = permissions;
+      }
     }
-    if (!params.permissions || typeof params.permissions !== 'object') {
-      params.permissions = {};
+
+    if (typeof rawParams.pathEnv === 'string') {
+      params.pathEnv = rawParams.pathEnv;
     }
 
     const auth = {};
@@ -961,16 +1070,23 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
       params.auth = auth;
     }
 
+    if (typeof rawParams.locale === 'string' && rawParams.locale.trim()) {
+      params.locale = rawParams.locale;
+    }
+    if (typeof rawParams.userAgent === 'string' && rawParams.userAgent.trim()) {
+      params.userAgent = rawParams.userAgent;
+    }
+
     if (deviceIdentity) {
       if (!connectNonce) {
-        return { frameText: null, waitForChallenge: true };
+        return { frameText, waitForChallenge: true };
       }
-
       const signedAtMs = Date.now();
       const tokenForSignature =
         typeof auth.token === 'string' && auth.token.trim()
           ? auth.token.trim()
           : (typeof auth.deviceToken === 'string' && auth.deviceToken.trim() ? auth.deviceToken.trim() : '');
+      const nonceForSignature = connectNonce;
 
       const payload = buildDeviceAuthPayloadV3({
         deviceId: deviceIdentity.deviceId,
@@ -980,7 +1096,7 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
         scopes: existingScopes,
         signedAtMs,
         token: tokenForSignature,
-        nonce: connectNonce,
+        nonce: nonceForSignature,
         platform: client.platform,
         deviceFamily: typeof client.deviceFamily === 'string' ? client.deviceFamily : '',
       });
@@ -990,7 +1106,7 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
         publicKey: publicKeyRawBase64UrlFromPem(deviceIdentity.publicKeyPem),
         signature,
         signedAt: signedAtMs,
-        nonce: connectNonce,
+        nonce: nonceForSignature,
       };
     }
 
@@ -1009,6 +1125,53 @@ function parseJsonPayload(raw) {
   }
 }
 
+function extractCorrelationId(params) {
+  if (!params || typeof params !== 'object') return '';
+  if (typeof params.correlationId === 'string' && params.correlationId.trim()) {
+    return params.correlationId.trim();
+  }
+  const metadata = params.metadata;
+  if (metadata && typeof metadata === 'object' && typeof metadata.correlationId === 'string' && metadata.correlationId.trim()) {
+    return metadata.correlationId.trim();
+  }
+  return '';
+}
+
+function extractGatewayRequestMeta(frameText) {
+  const payload = parseJsonPayload(frameText);
+  if (!payload || typeof payload !== 'object') return null;
+  if (payload.type !== 'req') return null;
+  const requestId = typeof payload.id === 'string' ? payload.id.trim() : '';
+  const method = typeof payload.method === 'string' ? payload.method.trim() : '';
+  if (!requestId || !method) return null;
+
+  const params = payload.params && typeof payload.params === 'object' ? payload.params : {};
+  const correlationId = extractCorrelationId(params);
+  return { requestId, method, correlationId };
+}
+
+function extractGatewayResponseMeta(frameText) {
+  const payload = parseJsonPayload(frameText);
+  if (!payload || typeof payload !== 'object') return null;
+  if (payload.type !== 'res') return null;
+  const requestId = typeof payload.id === 'string' ? payload.id.trim() : '';
+  if (!requestId) return null;
+  return {
+    requestId,
+    ok: payload.ok === true,
+  };
+}
+
+function isGatewayRunStartedFrame(frameText) {
+  const payload = parseJsonPayload(frameText);
+  if (!payload || typeof payload !== 'object') return false;
+  if (payload.type !== 'event' || payload.event !== 'agent') return false;
+  const body = payload.payload;
+  if (!body || typeof body !== 'object') return false;
+  if (body.stream !== 'lifecycle') return false;
+  return body.data && typeof body.data === 'object' && body.data.phase === 'start';
+}
+
 function bridgeNowIso() {
   return new Date().toISOString();
 }
@@ -1175,11 +1338,20 @@ function startBridgeDetachedProcess(rawFlags = {}) {
   }
 
   const args = buildBridgeDetachArgs(rawFlags);
+  const logPath = resolveBridgeLiveLogPath();
+  ensureDir(path.dirname(logPath));
+  fs.appendFileSync(logPath, `[${new Date().toISOString()}] [bridge-supervisor] starting detached bridge\n`);
+  const logFd = fs.openSync(logPath, 'a');
   const child = spawn(process.execPath, args, {
     detached: true,
-    stdio: 'ignore',
+    stdio: ['ignore', logFd, logFd],
   });
   child.unref();
+  try {
+    fs.closeSync(logFd);
+  } catch {
+    // no-op
+  }
   return {
     pid: child.pid,
     alreadyRunning: false,
@@ -1291,6 +1463,128 @@ async function stopBridgeProcesses() {
   };
 }
 
+function assertMacOSLaunchdAvailable() {
+  if (process.platform !== 'darwin') {
+    throw new Error('Bridge service manager is only supported on macOS (launchd).');
+  }
+  if (typeof process.getuid !== 'function') {
+    throw new Error('Cannot resolve current UID for launchd domain.');
+  }
+}
+
+function launchctlDomain() {
+  assertMacOSLaunchdAvailable();
+  return `gui/${String(process.getuid())}`;
+}
+
+function launchctlServiceTarget() {
+  return `${launchctlDomain()}/${BRIDGE_LAUNCHD_LABEL}`;
+}
+
+function runLaunchctl(args, { allowFailure = false } = {}) {
+  const result = spawnSync('launchctl', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const status = Number.isInteger(result.status) ? result.status : 1;
+  const stdout = String(result.stdout || '').trim();
+  const stderr = String(result.stderr || '').trim();
+  if (status !== 0 && !allowFailure) {
+    throw new Error(
+      `launchctl ${args.join(' ')} failed (${status}): ${stderr || stdout || 'unknown launchctl error'}`
+    );
+  }
+  return { status, stdout, stderr };
+}
+
+function buildBridgeLaunchAgentPlist() {
+  const scriptPath = (() => {
+    try {
+      return fs.realpathSync(process.argv[1]);
+    } catch {
+      return process.argv[1];
+    }
+  })();
+  const programArgs = [process.execPath, scriptPath, 'openclaw', 'bridge', 'start'];
+  const bridgeLogPath = resolveBridgeLiveLogPath();
+  const argsXml = programArgs.map((arg) => `<string>${xmlEscape(arg)}</string>`).join('\n      ');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(BRIDGE_LAUNCHD_LABEL)}</string>
+  <key>ProgramArguments</key>
+  <array>
+      ${argsXml}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(os.homedir())}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>OOMI_SKIP_UPDATE_CHECK</key>
+    <string>1</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(bridgeLogPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(bridgeLogPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+function readBridgeLaunchdStatus() {
+  assertMacOSLaunchdAvailable();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+  const target = launchctlServiceTarget();
+  const printResult = runLaunchctl(['print', target], { allowFailure: true });
+  const loaded = printResult.status === 0;
+  const output = [printResult.stdout, printResult.stderr].filter(Boolean).join('\n');
+  const pidMatch = output.match(/\bpid\s*=\s*(\d+)/);
+  const lastExitMatch = output.match(/\blast exit code\s*=\s*(-?\d+)/i);
+
+  return {
+    plistPath,
+    target,
+    installed: fs.existsSync(plistPath),
+    loaded,
+    pid: pidMatch ? Number(pidMatch[1]) : null,
+    running: Boolean(pidMatch && Number(pidMatch[1]) > 0),
+    lastExitCode: lastExitMatch ? Number(lastExitMatch[1]) : null,
+    printOutput: output,
+  };
+}
+
+function startBridgeLaunchdService() {
+  assertMacOSLaunchdAvailable();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+  if (!fs.existsSync(plistPath)) {
+    throw new Error('Bridge service is not installed. Run: oomi openclaw bridge service install');
+  }
+  const domain = launchctlDomain();
+  const target = launchctlServiceTarget();
+  runLaunchctl(['bootout', domain, plistPath], { allowFailure: true });
+  runLaunchctl(['bootstrap', domain, plistPath]);
+  runLaunchctl(['enable', target], { allowFailure: true });
+  runLaunchctl(['kickstart', '-k', target], { allowFailure: true });
+}
+
+async function stopBridgeLaunchdService() {
+  assertMacOSLaunchdAvailable();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+  const domain = launchctlDomain();
+  runLaunchctl(['bootout', domain, plistPath], { allowFailure: true });
+  return stopBridgeProcesses();
+}
+
 async function resolveBridgeRuntimeConfig(flags, bridgeState) {
   const explicitBrokerHttp = String(flags['broker-http'] || '').trim();
   const explicitBrokerWs = String(flags['broker-ws'] || '').trim();
@@ -1469,6 +1763,188 @@ async function startOpenclawBridge(flags) {
     );
   };
 
+  const sendGatewayAck = (brokerSocket, {
+    sessionId,
+    requestId = '',
+    method = '',
+    correlationId = '',
+    stage = 'unknown',
+  }) => {
+    if (!sessionId) return;
+    if (requestId) {
+      const sessionBridge = activeGatewaySockets.get(sessionId);
+      if (sessionBridge && sessionBridge.pendingRequests instanceof Map) {
+        const pending = sessionBridge.pendingRequests.get(requestId);
+        if (pending) {
+          pending.lastSuccessfulHop = stage;
+          sessionBridge.pendingRequests.set(requestId, pending);
+        }
+      }
+    }
+    sendBrokerPayload(brokerSocket, {
+      action: 'gateway_ack',
+      type: 'gateway.ack',
+      sessionId,
+      requestId,
+      method,
+      correlationId,
+      stage,
+      ts: bridgeNowIso(),
+    });
+  };
+
+  const sendGatewayErrorResponse = (
+    brokerSocket,
+    {
+      sessionId,
+      requestMeta,
+      code = 'gateway_error',
+      message = 'Gateway request failed',
+      lastSuccessfulHop = '',
+      retryable = false,
+      details = null,
+    }
+  ) => {
+    if (!sessionId || !requestMeta || !requestMeta.requestId) return;
+    const errorPayload = {
+      code,
+      message,
+      correlationId: requestMeta.correlationId || '',
+    };
+    if (lastSuccessfulHop) {
+      errorPayload.lastSuccessfulHop = lastSuccessfulHop;
+    }
+    if (retryable === true) {
+      errorPayload.retryable = true;
+    }
+    if (details && typeof details === 'object') {
+      errorPayload.details = details;
+    }
+    const responseFrame = {
+      type: 'res',
+      id: requestMeta.requestId,
+      ok: false,
+      error: errorPayload,
+    };
+    sendBrokerPayload(brokerSocket, {
+      action: 'gateway_frame',
+      type: 'gateway.frame',
+      sessionId,
+      frame: JSON.stringify(responseFrame),
+    });
+  };
+
+  const classifyGatewayClose = (code, reasonText) => {
+    const reasonLower = String(reasonText || '').toLowerCase();
+    if (code === 1008 && reasonLower.includes('invalid connect params')) {
+      return {
+        errorCode: 'gateway_invalid_connect_params',
+        retryable: false,
+      };
+    }
+    if (code === 1008) {
+      return {
+        errorCode: 'gateway_policy_violation',
+        retryable: false,
+      };
+    }
+    if (code === 1003 || code === 1002) {
+      return {
+        errorCode: 'gateway_protocol_error',
+        retryable: false,
+      };
+    }
+    if (code === 1006) {
+      return {
+        errorCode: 'gateway_abnormal_close',
+        retryable: true,
+      };
+    }
+    return {
+      errorCode: 'gateway_closed',
+      retryable: true,
+    };
+  };
+
+  const clearPendingRequestTimeout = (sessionBridge, requestId) => {
+    if (!sessionBridge || !(sessionBridge.pendingRequestTimers instanceof Map)) return;
+    const existingTimer = sessionBridge.pendingRequestTimers.get(requestId);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+      sessionBridge.pendingRequestTimers.delete(requestId);
+    }
+  };
+
+  const clearAllPendingRequestTimeouts = (sessionBridge) => {
+    if (!sessionBridge || !(sessionBridge.pendingRequestTimers instanceof Map)) return;
+    for (const timer of sessionBridge.pendingRequestTimers.values()) {
+      clearTimeout(timer);
+    }
+    sessionBridge.pendingRequestTimers.clear();
+  };
+
+  const startPendingRequestTimeout = (brokerSocket, sessionId, sessionBridge, requestMeta) => {
+    if (!sessionBridge || !requestMeta || !requestMeta.requestId) return;
+    if (!(sessionBridge.pendingRequestTimers instanceof Map)) {
+      sessionBridge.pendingRequestTimers = new Map();
+    }
+    clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+    const timer = setTimeout(() => {
+      const pending = sessionBridge.pendingRequests instanceof Map
+        ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+        : null;
+      if (!pending) {
+        clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+        return;
+      }
+
+      if (requestMeta.method === 'connect') {
+        incrementBridgeMetric('connect_timeout_count');
+      } else if (requestMeta.method === 'chat.send') {
+        incrementBridgeMetric('chat_send_timeout_count');
+      } else {
+        incrementBridgeMetric('gateway_request_timeout_count');
+      }
+
+      const lastSuccessfulHop = typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+        ? pending.lastSuccessfulHop
+        : 'bridge.forwarded';
+      sendGatewayAck(brokerSocket, {
+        sessionId,
+        requestId: pending.requestId,
+        method: pending.method,
+        correlationId: pending.correlationId,
+        stage: 'gateway.timeout',
+      });
+      sendBrokerPayload(brokerSocket, {
+        action: 'log',
+        type: 'log',
+        sessionId,
+        level: 'warn',
+        message: `Gateway request timeout (${pending.method} ${pending.requestId}) after ${String(BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS)}ms`,
+      });
+      sendGatewayErrorResponse(brokerSocket, {
+        sessionId,
+        requestMeta: pending,
+        code: 'gateway_timeout',
+        message: `Gateway request timeout (${pending.method}) after ${String(BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS)}ms`,
+        lastSuccessfulHop,
+        retryable: true,
+        details: {
+          method: pending.method,
+          timeoutMs: BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS,
+        },
+      });
+
+      if (sessionBridge.pendingRequests instanceof Map) {
+        sessionBridge.pendingRequests.delete(pending.requestId);
+      }
+      clearPendingRequestTimeout(sessionBridge, pending.requestId);
+    }, BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS);
+
+    sessionBridge.pendingRequestTimers.set(requestMeta.requestId, timer);
+  };
+
   const parseBrokerEnvelope = (raw) => {
     const payload = parseJsonPayload(raw);
     if (!payload) return null;
@@ -1496,6 +1972,7 @@ async function startOpenclawBridge(flags) {
   const scheduleReconnect = () => {
     if (reconnectState.stopped || reconnectState.timer) return;
     reconnectState.attempt += 1;
+    incrementBridgeMetric('bridge_reconnect_scheduled_count');
     const failure =
       reconnectState.lastFailure ||
       classifyBridgeFailure({ reason: 'connection closed without classified error' });
@@ -1592,20 +2069,102 @@ async function startOpenclawBridge(flags) {
 
       clearChallengeTimer(sessionBridge);
       for (const pendingFrame of pending) {
+        const requestMeta = extractGatewayRequestMeta(pendingFrame);
         const prepared = prepareGatewayFrameForLocalGateway(pendingFrame, gateway, {
           connectNonce: sessionBridge.connectNonce,
           deviceIdentity: gatewayDeviceIdentity,
         });
         if (!prepared.frameText || prepared.waitForChallenge) {
+          if (requestMeta) {
+            const pending = sessionBridge.pendingRequests instanceof Map
+              ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+              : null;
+            const lastSuccessfulHop = pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+              ? pending.lastSuccessfulHop
+              : 'bridge.waiting_for_challenge';
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.dropped',
+            });
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: 'bridge_dropped',
+              message: 'Bridge dropped connect request after challenge handling.',
+              lastSuccessfulHop,
+              retryable: true,
+            });
+            if (sessionBridge.pendingRequests instanceof Map) {
+              sessionBridge.pendingRequests.delete(requestMeta.requestId);
+            }
+            clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+          }
           continue;
         }
         const result = forwardFrameToSession(sessionBridge, prepared.frameText);
         if (result === 'queued') {
           console.log(`[bridge] client.frame queued after challenge ${sessionId}`);
+          if (requestMeta) {
+            startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.queued',
+            });
+          }
         } else if (result === 'dropped') {
           console.log(`[bridge] client.frame dropped after challenge ${sessionId}`);
+          incrementBridgeMetric('bridge_drop_count');
+          if (requestMeta) {
+            const pending = sessionBridge.pendingRequests instanceof Map
+              ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+              : null;
+            const lastSuccessfulHop = pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+              ? pending.lastSuccessfulHop
+              : 'bridge.waiting_for_challenge';
+            clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+            if (sessionBridge.pendingRequests instanceof Map) {
+              sessionBridge.pendingRequests.delete(requestMeta.requestId);
+            }
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: 'bridge_dropped',
+              message: 'Bridge dropped request because gateway socket is not open.',
+              lastSuccessfulHop,
+              retryable: true,
+            });
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.dropped',
+            });
+          }
         } else {
           console.log(`[bridge] client.frame sent after challenge ${sessionId}`);
+          if (requestMeta) {
+            startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.forwarded',
+            });
+          }
         }
       }
     };
@@ -1619,11 +2178,21 @@ async function startOpenclawBridge(flags) {
       if (!Array.isArray(sessionBridge.pendingConnectFrames)) {
         sessionBridge.pendingConnectFrames = [];
       }
+      if (!(sessionBridge.pendingRequests instanceof Map)) {
+        sessionBridge.pendingRequests = new Map();
+      }
+      if (!(sessionBridge.pendingRequestTimers instanceof Map)) {
+        sessionBridge.pendingRequestTimers = new Map();
+      }
+      if (typeof sessionBridge.lastChatCorrelationId !== 'string') {
+        sessionBridge.lastChatCorrelationId = '';
+      }
       let connectTimeout = setTimeout(() => {
         if (gatewaySocket.readyState !== WebSocket.CONNECTING) return;
         console.error(
           `[bridge] gateway.connect_timeout ${sessionId} (${String(BRIDGE_GATEWAY_CONNECT_TIMEOUT_MS)}ms)`
         );
+        incrementBridgeMetric('gateway_connect_timeout_count');
         sendBrokerPayload(brokerSocket, {
           action: 'log',
           type: 'log',
@@ -1651,6 +2220,7 @@ async function startOpenclawBridge(flags) {
         const frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
         const gatewayPayload = parseJsonPayload(frame);
         if (gatewayPayload?.event === 'connect.challenge') {
+          console.log(`[bridge] gateway.connect.challenge ${sessionId}`);
           const nonce =
             gatewayPayload.payload && typeof gatewayPayload.payload.nonce === 'string'
               ? gatewayPayload.payload.nonce.trim()
@@ -1674,6 +2244,35 @@ async function startOpenclawBridge(flags) {
             flushPendingConnectFrames(sessionId, sessionBridge);
           }
         }
+
+        const responseMeta = extractGatewayResponseMeta(frame);
+        if (responseMeta && sessionBridge.pendingRequests instanceof Map) {
+          const requestMeta = sessionBridge.pendingRequests.get(responseMeta.requestId);
+          if (requestMeta) {
+            clearPendingRequestTimeout(sessionBridge, responseMeta.requestId);
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: responseMeta.ok ? 'gateway.accepted' : 'gateway.rejected',
+            });
+            if (!responseMeta.ok) {
+              incrementBridgeMetric('gateway_rejected_count');
+            }
+            sessionBridge.pendingRequests.delete(responseMeta.requestId);
+          }
+        }
+
+        if (isGatewayRunStartedFrame(frame)) {
+          sendGatewayAck(brokerSocket, {
+            sessionId,
+            method: 'chat.send',
+            correlationId: sessionBridge.lastChatCorrelationId || '',
+            stage: 'run.started',
+          });
+        }
+
         sendBrokerPayload(brokerSocket, { action: 'gateway_frame', type: 'gateway.frame', sessionId, frame });
       });
 
@@ -1684,9 +2283,41 @@ async function startOpenclawBridge(flags) {
         }
         clearChallengeTimer(sessionBridge);
         const reasonText = reason ? reason.toString() : '';
+        const closeMeta = classifyGatewayClose(code, reasonText);
         console.log(
           `[bridge] gateway.close ${sessionId} code=${String(code)}${reasonText ? ` reason=${reasonText}` : ''}`
         );
+        if (sessionBridge.pendingRequests instanceof Map) {
+          for (const requestMeta of sessionBridge.pendingRequests.values()) {
+            if (!requestMeta || typeof requestMeta !== 'object') continue;
+            const lastSuccessfulHop = typeof requestMeta.lastSuccessfulHop === 'string' && requestMeta.lastSuccessfulHop
+              ? requestMeta.lastSuccessfulHop
+              : 'bridge.forwarded';
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId || '',
+              method: requestMeta.method || '',
+              correlationId: requestMeta.correlationId || '',
+              stage: 'gateway.closed',
+            });
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: closeMeta.errorCode,
+              message: reasonText
+                ? `Gateway closed (${String(code)}): ${reasonText}`
+                : `Gateway closed (${String(code)})`,
+              lastSuccessfulHop,
+              retryable: closeMeta.retryable,
+              details: {
+                closeCode: code,
+                closeReason: reasonText,
+              },
+            });
+          }
+          sessionBridge.pendingRequests.clear();
+        }
+        clearAllPendingRequestTimeouts(sessionBridge);
         activeGatewaySockets.delete(sessionId);
         sendBrokerPayload(brokerSocket, {
           action: 'gateway_closed',
@@ -1843,6 +2474,22 @@ async function startOpenclawBridge(flags) {
         console.log(`[bridge] client.frame ${sessionId}`);
         const sessionBridge = getOrCreateGatewaySession(sessionId);
         if (!sessionBridge) return;
+        const requestMeta = extractGatewayRequestMeta(frame);
+        if (requestMeta) {
+          if (!(sessionBridge.pendingRequests instanceof Map)) {
+            sessionBridge.pendingRequests = new Map();
+          }
+          if (!(sessionBridge.pendingRequestTimers instanceof Map)) {
+            sessionBridge.pendingRequestTimers = new Map();
+          }
+          sessionBridge.pendingRequests.set(requestMeta.requestId, {
+            ...requestMeta,
+            lastSuccessfulHop: 'broker.accepted',
+          });
+          if (requestMeta.method === 'chat.send' && requestMeta.correlationId) {
+            sessionBridge.lastChatCorrelationId = requestMeta.correlationId;
+          }
+        }
         const prepared = prepareGatewayFrameForLocalGateway(frame, gateway, {
           connectNonce: sessionBridge.connectNonce,
           deviceIdentity: gatewayDeviceIdentity,
@@ -1850,16 +2497,103 @@ async function startOpenclawBridge(flags) {
         if (prepared.waitForChallenge) {
           queueConnectUntilChallenge(sessionId, sessionBridge, frame);
           console.log(`[bridge] client.frame waiting for challenge ${sessionId}`);
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.waiting_for_challenge',
+            });
+          }
           return;
         }
         if (!prepared.frameText) {
+          if (requestMeta) {
+            const pending = sessionBridge.pendingRequests instanceof Map
+              ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+              : null;
+            const lastSuccessfulHop = pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+              ? pending.lastSuccessfulHop
+              : 'broker.accepted';
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.dropped',
+            });
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: 'bridge_dropped',
+              message: 'Bridge dropped request before forwarding to gateway.',
+              lastSuccessfulHop,
+              retryable: true,
+            });
+            if (sessionBridge.pendingRequests instanceof Map) {
+              sessionBridge.pendingRequests.delete(requestMeta.requestId);
+            }
+            clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+          }
           return;
         }
         const result = forwardFrameToSession(sessionBridge, prepared.frameText);
         if (result === 'queued') {
           console.log(`[bridge] client.frame queued ${sessionId}`);
+          if (requestMeta) {
+            startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.queued',
+            });
+          }
         } else if (result === 'dropped') {
           console.log(`[bridge] client.frame dropped (socket not open) ${sessionId}`);
+          incrementBridgeMetric('bridge_drop_count');
+          if (requestMeta) {
+            const pending = sessionBridge.pendingRequests instanceof Map
+              ? sessionBridge.pendingRequests.get(requestMeta.requestId)
+              : null;
+            const lastSuccessfulHop = pending && typeof pending.lastSuccessfulHop === 'string' && pending.lastSuccessfulHop
+              ? pending.lastSuccessfulHop
+              : 'broker.accepted';
+            clearPendingRequestTimeout(sessionBridge, requestMeta.requestId);
+            if (sessionBridge.pendingRequests instanceof Map) {
+              sessionBridge.pendingRequests.delete(requestMeta.requestId);
+            }
+            sendGatewayErrorResponse(brokerSocket, {
+              sessionId,
+              requestMeta,
+              code: 'bridge_dropped',
+              message: 'Bridge dropped request because gateway socket is not open.',
+              lastSuccessfulHop,
+              retryable: true,
+            });
+          }
+          if (requestMeta) {
+            sendGatewayAck(brokerSocket, {
+              sessionId,
+              requestId: requestMeta.requestId,
+              method: requestMeta.method,
+              correlationId: requestMeta.correlationId,
+              stage: 'bridge.dropped',
+            });
+          }
+        } else if (requestMeta) {
+          startPendingRequestTimeout(brokerSocket, sessionId, sessionBridge, requestMeta);
+          sendGatewayAck(brokerSocket, {
+            sessionId,
+            requestId: requestMeta.requestId,
+            method: requestMeta.method,
+            correlationId: requestMeta.correlationId,
+            stage: 'bridge.forwarded',
+          });
         }
         return;
       }
@@ -1870,6 +2604,10 @@ async function startOpenclawBridge(flags) {
         const sessionBridge = activeGatewaySockets.get(sessionId);
         if (sessionBridge && sessionBridge.socket) {
           clearChallengeTimer(sessionBridge);
+          if (sessionBridge.pendingRequests instanceof Map) {
+            sessionBridge.pendingRequests.clear();
+          }
+          clearAllPendingRequestTimeouts(sessionBridge);
           activeGatewaySockets.delete(sessionId);
           sessionBridge.socket.close(1000, 'client_closed');
         }
@@ -1884,8 +2622,13 @@ async function startOpenclawBridge(flags) {
       }
       const reasonText = reason ? reason.toString() : '';
       console.log(`[bridge] Broker disconnected (${code}) ${reasonText}`);
+      incrementBridgeMetric('bridge_disconnect_count');
       for (const [sessionId, sessionBridge] of activeGatewaySockets.entries()) {
         clearChallengeTimer(sessionBridge);
+        if (sessionBridge.pendingRequests instanceof Map) {
+          sessionBridge.pendingRequests.clear();
+        }
+        clearAllPendingRequestTimeouts(sessionBridge);
         activeGatewaySockets.delete(sessionId);
         try {
           sessionBridge.socket.close(1001, 'broker_disconnected');
@@ -1907,6 +2650,7 @@ async function startOpenclawBridge(flags) {
     });
 
     brokerSocket.on('error', (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}`
@@ -2160,6 +2904,16 @@ function printOpenclawBridgeStatus(flags) {
     if (payload.runtime.hint) {
       console.log(`Hint: ${payload.runtime.hint}`);
     }
+    if (payload.runtime.metrics && typeof payload.runtime.metrics === 'object') {
+      const metrics = normalizeBridgeMetrics(payload.runtime.metrics);
+      const metricPairs = Object.entries(metrics);
+      if (metricPairs.length > 0) {
+        console.log('Metrics:');
+        for (const [name, value] of metricPairs) {
+          console.log(`  ${name}: ${value}`);
+        }
+      }
+    }
     return;
   }
 
@@ -2234,27 +2988,109 @@ function printOpenclawPluginSetup(flags) {
   }
 }
 
+async function handleBridgeServiceCommand(actionRaw = '', flags = {}) {
+  assertMacOSLaunchdAvailable();
+  const action = String(actionRaw || 'status').trim().toLowerCase();
+  const plistPath = resolveBridgeLaunchAgentPlistPath();
+
+  if (action === 'install') {
+    ensureDir(path.dirname(plistPath));
+    writeFile(plistPath, buildBridgeLaunchAgentPlist());
+    console.log(`Installed bridge launchd plist: ${plistPath}`);
+    if (isTruthyFlag(flags['no-start'])) {
+      console.log('Service install complete. Start with: oomi openclaw bridge service start');
+      return;
+    }
+    startBridgeLaunchdService();
+    incrementBridgeMetric('bridge_start_count');
+    console.log(`Bridge service started: ${launchctlServiceTarget()}`);
+    return;
+  }
+
+  if (action === 'uninstall') {
+    await stopBridgeLaunchdService();
+    if (fs.existsSync(plistPath)) {
+      fs.unlinkSync(plistPath);
+    }
+    console.log(`Removed bridge launchd plist: ${plistPath}`);
+    return;
+  }
+
+  if (action === 'start') {
+    startBridgeLaunchdService();
+    incrementBridgeMetric('bridge_start_count');
+    console.log(`Bridge service started: ${launchctlServiceTarget()}`);
+    return;
+  }
+
+  if (action === 'stop') {
+    const stopped = await stopBridgeLaunchdService();
+    if (Array.isArray(stopped.found) && stopped.found.length > 0) {
+      console.log(`Stopped bridge workers: ${stopped.stopped.join(', ') || 'none'}.`);
+    } else {
+      console.log('No bridge workers running.');
+    }
+    console.log(`Bridge service stopped: ${launchctlServiceTarget()}`);
+    return;
+  }
+
+  if (action === 'restart') {
+    await stopBridgeLaunchdService();
+    startBridgeLaunchdService();
+    incrementBridgeMetric('bridge_restart_count');
+    console.log(`Bridge service restarted: ${launchctlServiceTarget()}`);
+    return;
+  }
+
+  if (action === 'status') {
+    const status = readBridgeLaunchdStatus();
+    console.log('Bridge Service Status');
+    console.log('---------------------');
+    console.log(`Label: ${BRIDGE_LAUNCHD_LABEL}`);
+    console.log(`Target: ${status.target}`);
+    console.log(`Plist: ${status.plistPath}`);
+    console.log(`Installed: ${status.installed ? 'yes' : 'no'}`);
+    console.log(`Loaded: ${status.loaded ? 'yes' : 'no'}`);
+    console.log(`Running: ${status.running ? 'yes' : 'no'}`);
+    if (status.pid) {
+      console.log(`PID: ${status.pid}`);
+    }
+    if (status.lastExitCode !== null) {
+      console.log(`Last exit code: ${status.lastExitCode}`);
+    }
+    return;
+  }
+
+  throw new Error(
+    `Unknown bridge service action: ${action}. Use: oomi openclaw bridge service [install|start|stop|restart|status|uninstall]`
+  );
+}
+
 async function startBridgeLifecycle(flags = {}) {
   if (Boolean(flags.detach)) {
     const detachedFlags = { ...flags };
     delete detachedFlags.detach;
     const result = startBridgeDetachedProcess(detachedFlags);
     if (result.alreadyRunning) {
+      incrementBridgeMetric('duplicate_start_attempt_count');
       console.log(`Bridge already running (pid: ${result.pid}).`);
       return;
     }
+    incrementBridgeMetric('bridge_start_count');
     console.log(`Bridge started in background (pid: ${result.pid}).`);
     return;
   }
 
   const running = findRunningBridgeProcess();
   if (running) {
+    incrementBridgeMetric('duplicate_start_attempt_count');
     console.log(
       `Bridge already running (pid ${running.pid})${running.deviceId ? ` for device ${running.deviceId}` : ''}.`
     );
     return;
   }
 
+  incrementBridgeMetric('bridge_start_count');
   await startOpenclawBridge(flags);
 }
 
@@ -2293,6 +3129,7 @@ async function handleBridgeLifecycleCommand(flags = {}, actionRaw = '') {
   }
 
   if (action === 'restart') {
+    incrementBridgeMetric('bridge_restart_count');
     const result = await stopBridgeProcesses();
     if (result.found.length > 0) {
       console.log(`Stopped bridge processes: ${result.stopped.join(', ') || 'none'}.`);
@@ -2346,7 +3183,12 @@ async function main() {
   }
 
   if (command === 'openclaw' && subcommand === 'bridge') {
-    const bridgeAction = args.positionals[0] || 'start';
+    const bridgeAction = String(args.positionals[0] || 'start').trim().toLowerCase();
+    if (bridgeAction === 'service') {
+      const serviceAction = args.positionals[1] || 'status';
+      await handleBridgeServiceCommand(serviceAction, args.flags);
+      return;
+    }
     await handleBridgeLifecycleCommand(args.flags, bridgeAction);
     return;
   }
@@ -2390,7 +3232,24 @@ async function main() {
   process.exit(1);
 }
 
-main().catch((err) => {
-  console.error(err instanceof Error ? err.message : err);
-  process.exit(1);
-});
+const __currentFilePath = fileURLToPath(import.meta.url);
+const __invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : '';
+const __isDirectExecution = Boolean(__invokedPath) && __invokedPath === path.resolve(__currentFilePath);
+
+if (__isDirectExecution) {
+  main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  });
+}
+
+export {
+  prepareGatewayFrameForLocalGateway,
+  classifyBridgeFailure,
+  computeReconnectDelayMs,
+  extractGatewayRequestMeta,
+  extractGatewayResponseMeta,
+  isGatewayRunStartedFrame,
+  isBridgeWorkerCommand,
+  parsePositiveInteger,
+};

package/openclaw.extension.js

@@ -32,8 +32,22 @@ function parseAccounts(rawAccounts) {
   return accounts;
 }
 
+function extractChannelConfig(cfg = {}) {
+  if (!cfg || typeof cfg !== 'object') return {};
+  if (cfg.channels && typeof cfg.channels === 'object' && cfg.channels[CHANNEL_ID] && typeof cfg.channels[CHANNEL_ID] === 'object') {
+    return cfg.channels[CHANNEL_ID];
+  }
+  if (cfg[CHANNEL_ID] && typeof cfg[CHANNEL_ID] === 'object') {
+    return cfg[CHANNEL_ID];
+  }
+  if (cfg.accounts && typeof cfg.accounts === 'object') {
+    return cfg;
+  }
+  return {};
+}
+
 function normalizeConfig(cfg = {}) {
-  const channelConfig = cfg?.channels?.[CHANNEL_ID] || {};
+  const channelConfig = extractChannelConfig(cfg);
   const configuredAccounts = parseAccounts(channelConfig.accounts);
   const accountIds = Object.keys(configuredAccounts);
   const defaultAccountId = toString(channelConfig.defaultAccountId, accountIds[0] || 'default');
@@ -125,6 +139,45 @@ function extractUserId(payload) {
   return '';
 }
 
+function nextMessageId() {
+  return `oomi_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function extractMessageId(payload) {
+  const candidates = [
+    payload?.messageId,
+    payload?.id,
+    payload?.requestId,
+    payload?.idempotencyKey,
+    payload?.metadata?.messageId,
+    payload?.metadata?.idempotencyKey,
+  ];
+
+  for (const candidate of candidates) {
+    const value = toString(candidate);
+    if (value) return value;
+  }
+
+  return nextMessageId();
+}
+
+function extractCorrelationId(payload) {
+  const candidates = [
+    payload?.correlationId,
+    payload?.metadata?.correlationId,
+    payload?.requestId,
+    payload?.messageId,
+    payload?.id,
+  ];
+
+  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);
@@ -221,12 +274,16 @@ const oomiChannelPlugin = {
       const conversationKey = extractConversationKey(payload);
       const userId = extractUserId(payload);
       const sessionKey = toString(payload?.sessionKey || payload?.metadata?.sessionKey, account.defaultSessionKey);
+      const messageId = extractMessageId(payload);
+      const correlationId = extractCorrelationId(payload);
 
       const response = await postJson({
         url: `${account.backendUrl}/v1/channel/plugin/messages`,
         token: account.deviceToken,
         timeoutMs: account.requestTimeoutMs,
         body: {
+          messageId,
+          correlationId,
           conversationKey,
           userId,
           sessionKey,
@@ -234,15 +291,18 @@ const oomiChannelPlugin = {
           source: 'openclaw.channel',
           metadata: {
             accountId: resolvedAccountId,
+            correlationId,
           },
         },
       });
 
       if (!response.ok) {
         const reason = toString(response.payload?.error, `status ${response.status}`);
+        const code = toString(response.payload?.errorCode);
         return {
           ok: false,
-          error: `oomi plugin message publish failed: ${reason}`,
+          error: `oomi plugin message publish failed: ${reason}${code ? ` (code=${code})` : ''}`,
+          code,
         };
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.10",
+  "version": "0.2.13",
   "description": "Oomi CLI for OpenClaw setup",
   "bin": {
     "oomi": "bin/oomi-ai.js"
@@ -47,7 +47,7 @@
   },
   "scripts": {
     "check": "node --check bin/oomi-ai.js",
-    "test": "node --test test/sessionBridgeState.test.mjs"
+    "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
     "ws": "^8.19.0"

package/skills/oomi/agent_instructions.md

@@ -29,6 +29,7 @@ If the user asks to connect OpenClaw to Oomi voice/web:
 7. Ensure exactly one bridge worker is running (singleton handler):
    - `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`