oomi-ai 0.3.8 → 0.4.0

package/bin/oomi-ai.js

@@ -8,6 +8,8 @@ import net from 'net';
 import { lookup as dnsLookup } from 'dns/promises';
 import { fileURLToPath } from 'url';
 import WebSocket from 'ws';
+import { LOCAL_PROTOCOL_MIN, LOCAL_PROTOCOL_MAX, probeGateway } from '../lib/gatewayProbe.js';
+import { LocalAgentRuntime, localAgentConfig, runLocalAgent, writePrivateJson, startChannelWorker } from '../lib/localAgent.js';
 import { createPersonaApiClient } from '../lib/personaApiClient.js';
 import { inferSpokenMetadataFromContent, normalizeSpokenMetadata } from '../lib/spokenMetadata.js';
 import {
@@ -31,6 +33,8 @@ import {
 } from '../lib/openclawProfile.js';
 import { ensureSessionBridge, flushSessionQueue, flushWaitingForConnect, forwardFrameToSession } from './sessionBridgeState.js';
 
+let bridgeConnectionName = '';
+
 const MARKER_START = '<oomi-agent-instructions>';
 const MARKER_END = '</oomi-agent-instructions>';
 
@@ -53,7 +57,6 @@ const BRIDGE_GATEWAY_REQUEST_TIMEOUT_MS = parsePositiveInteger(
   30000
 );
 const BRIDGE_LAUNCHD_LABEL = 'ai.oomi.bridge';
-const DEVICE_IDENTITY_PATH = resolveOpenclawIdentityPath();
 const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
 const BRIDGE_DEBUG_ENABLED = process.env.OOMI_BRIDGE_DEBUG === '1';
 
@@ -195,6 +198,20 @@ function usage() {
   console.log(`oomi <command>
 
 Commands:
+  connect --runtime openclaw|hermes|command [--name NAME] [--app-url URL]
+    Verify the selected local agent, pair once, start its bridge, and return an Auth Link.
+    Hermes: --profile PROFILE and --resume SESSION select the intended agent/session.
+    Other agents: --command '["/absolute/path/to/adapter"]' (JSON stdin / JSON stdout).
+    --cwd PATH selects the agent working directory; --name isolates multiple agents.
+  status [--name NAME]
+    Show broker connection and verified local agent health separately.
+  verify [--name NAME]
+    Send a harmless local test message and require a real agent reply.
+  invite [--name NAME] [--app-url URL]
+    Generate a fresh Auth Link from saved pairing without changing agents.
+  bridge [start|ensure|stop|restart|ps] [--name NAME] [--detach]
+    Manage only the named agent's bridge.
+
   init
     Install Oomi agent instructions into OpenClaw AGENTS.md.
 
@@ -233,7 +250,9 @@ Commands:
   persona-apps apply-action <slug>
     Apply an approved persona app action through the Oomi backend.
 
-  context health
+  context health [--window day|week|month|year|all|range] [--date YYYY-MM-DD]
+    [--from YYYY-MM-DD --to YYYY-MM-DD] [--shape summary|series|both]
+    [--group-by day|week|month|year] [--timezone IANA-zone] [--cursor YYYY-MM-DD]
     Show the latest account-linked health context available to this paired OpenClaw device.
   context health sync [--wait]
     Request the linked Oomi mobile app to sync fresh HealthKit context.
@@ -572,7 +591,10 @@ async function handlePersonaAppApplyActionCommand(slug, flags = {}) {
 
 async function handleContextHealthCommand(flags = {}) {
   const client = createCliPersonaApiClient(flags);
-  const payload = await client.getHealthContext();
+  const payload = await client.getHealthContext({
+    window: flags.window, date: flags.date, from: flags.from, to: flags.to,
+    shape: flags.shape, groupBy: flags['group-by'], timezone: flags.timezone, cursor: flags.cursor,
+  });
   printStructuredResult(payload, isTruthyFlag(flags.json));
 }
 
@@ -770,19 +792,19 @@ function readOpenclawDefaultSessionKey() {
 }
 
 function resolveBridgeStatePath() {
-  return resolveOpenclawBridgeStatePath();
+  return bridgeConnectionName ? path.join(connectionDirectory(), 'oomi-bridge.json') : resolveOpenclawBridgeStatePath();
 }
 
 function resolveBridgeStatusPath() {
-  return resolveOpenclawBridgeStatusPath();
+  return bridgeConnectionName ? path.join(connectionDirectory(), 'oomi-bridge-status.json') : resolveOpenclawBridgeStatusPath();
 }
 
 function resolveBridgeLockPath() {
-  return resolveOpenclawBridgeLockPath();
+  return bridgeConnectionName ? path.join(connectionDirectory(), 'oomi-bridge.lock') : resolveOpenclawBridgeLockPath();
 }
 
 function resolveBridgeLiveLogPath() {
-  return resolveOpenclawBridgeLiveLogPath();
+  return bridgeConnectionName ? path.join(connectionDirectory(), 'logs', 'oomi-bridge-live.log') : resolveOpenclawBridgeLiveLogPath();
 }
 
 function resolveBridgeLaunchAgentPlistPath() {
@@ -815,7 +837,7 @@ function readBridgeState() {
 function writeBridgeState(nextState) {
   const statePath = resolveBridgeStatePath();
   ensureDir(path.dirname(statePath));
-  writeFile(statePath, JSON.stringify(nextState, null, 2) + '\n');
+  writePrivateJson(statePath, nextState);
 }
 
 function readBridgeStatus() {
@@ -933,11 +955,11 @@ function isPidAlive(pid) {
 
 function isBridgeWorkerCommand(command) {
   const text = String(command || '').trim().toLowerCase();
-  if (!text.includes('openclaw bridge')) return false;
-  if (/\bopenclaw\s+bridge\s+(ps|stop|restart|ensure)\b/.test(text)) return false;
-  if (/\bopenclaw\s+bridge\s+start\b/.test(text)) return true;
-  if (/\bopenclaw\s+bridge(\s+--|$)/.test(text)) return true;
-  return false;
+  if (!/(?:oomi(?:-ai\.js)?|openclaw)\s+bridge\b/.test(text)) return false;
+  const connection = text.match(/--(?:connection|name)[=\s]+([a-z0-9_-]+)/)?.[1] || '';
+  if (connection !== bridgeConnectionName) return false;
+  if (/\bbridge\s+(ps|stop|restart|ensure|service)\b/.test(text)) return false;
+  return /\bbridge(?:\s+start)?(?:\s+--|$)/.test(text);
 }
 
 function isBridgeProcess(pid) {
@@ -1047,6 +1069,7 @@ function acquireBridgeLock(deviceId) {
 async function claimBridgeDeviceToken({ brokerHttp, pairCode, deviceId }) {
   const response = await fetch(`${brokerHttp.replace(/\/$/, '')}/v1/pair/claim`, {
     method: 'POST',
+    signal: AbortSignal.timeout(15000),
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ pairCode, deviceId }),
   });
@@ -1064,6 +1087,7 @@ async function requestManagedPairCode({ appUrl, label }) {
   const baseUrl = appUrl.replace(/\/$/, '');
   const response = await fetch(`${baseUrl}/api/gateway/managed/pair/start`, {
     method: 'POST',
+    signal: AbortSignal.timeout(15000),
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ label }),
   });
@@ -1080,6 +1104,7 @@ async function requestManagedPairCode({ appUrl, label }) {
 async function requestBrokerPairCode({ brokerHttp, adminKey, label }) {
   const response = await fetch(`${brokerHttp.replace(/\/$/, '')}/v1/pair/start`, {
     method: 'POST',
+    signal: AbortSignal.timeout(15000),
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${adminKey}`,
@@ -1099,6 +1124,7 @@ async function requestBrokerPairCode({ brokerHttp, adminKey, label }) {
 async function requestConnectInviteLink({ backendHttp, appUrl, sessionKey, deviceToken }) {
   const response = await fetch(`${backendHttp.replace(/\/$/, '')}/v1/invite_links/start`, {
     method: 'POST',
+    signal: AbortSignal.timeout(15000),
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${deviceToken}`,
@@ -1119,6 +1145,7 @@ async function fetchManagedGatewayConfig({ appUrl }) {
   const baseUrl = appUrl.replace(/\/$/, '');
   const response = await fetch(`${baseUrl}/api/gateway/managed/config`, {
     method: 'GET',
+    signal: AbortSignal.timeout(15000),
     headers: { 'Content-Type': 'application/json' },
   });
   const payload = await response.json().catch(() => ({}));
@@ -1218,11 +1245,12 @@ function buildDeviceAuthPayloadV3({
 }
 
 function loadGatewayDeviceIdentity() {
-  if (!fs.existsSync(DEVICE_IDENTITY_PATH)) {
+  const identityPath = resolveOpenclawIdentityPath();
+  if (!fs.existsSync(identityPath)) {
     return null;
   }
   try {
-    const parsed = JSON.parse(readFile(DEVICE_IDENTITY_PATH));
+    const parsed = JSON.parse(readFile(identityPath));
     if (
       parsed &&
       parsed.version === 1 &&
@@ -1312,12 +1340,8 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
     const rawParams = frame.params && typeof frame.params === 'object' ? frame.params : {};
     const params = {};
 
-    params.minProtocol = Number.isInteger(rawParams.minProtocol) && rawParams.minProtocol >= 1
-      ? rawParams.minProtocol
-      : 3;
-    params.maxProtocol = Number.isInteger(rawParams.maxProtocol) && rawParams.maxProtocol >= 1
-      ? rawParams.maxProtocol
-      : 3;
+    params.minProtocol = gatewayAuth.protocol || LOCAL_PROTOCOL_MIN;
+    params.maxProtocol = gatewayAuth.protocol || LOCAL_PROTOCOL_MAX;
 
     const clientInput = rawParams.client && typeof rawParams.client === 'object' ? rawParams.client : {};
     const client = {};
@@ -2174,6 +2198,7 @@ async function runBridgePreflight({ brokerWs, gatewayUrl, gatewayConfigPath }) {
     throw new Error('Broker WS URL is missing hostname.');
   }
   await dnsLookup(brokerHost);
+  if (gatewayUrl === 'local-agent:') return;
 
   let parsedGatewayUrl;
   try {
@@ -2197,6 +2222,7 @@ function buildBridgeDetachArgs(rawFlags = {}) {
     'device-token',
   ];
   const args = [process.argv[1], 'openclaw', 'bridge'];
+  if (bridgeConnectionName) args.push('--connection', bridgeConnectionName);
 
   for (const key of orderedKeys) {
     const value = rawFlags[key];
@@ -2262,6 +2288,10 @@ function listBridgeProcessPids() {
   const status = readBridgeStatus();
   addPid(status.pid);
 
+  // Named connections are owned by their own lock and status, including when a
+  // custom connections directory is used. Never sweep another installation.
+  if (bridgeConnectionName) return Array.from(pids);
+
   try {
     const result = spawnSync('ps', ['-Ao', 'pid=,command='], {
       encoding: 'utf8',
@@ -2491,7 +2521,7 @@ async function stopBridgeLaunchdService() {
 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();
+  const appUrl = String(flags['app-url'] || process.env.OOMI_APP_URL || bridgeState.appUrl || '').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();
@@ -2534,6 +2564,7 @@ async function startOpenclawBridge(flags) {
   }
 
   const bridgeState = readBridgeState();
+  if (bridgeState.openclawHome) process.env.OPENCLAW_HOME = bridgeState.openclawHome;
   const runtimeConfig = await resolveBridgeRuntimeConfig(flags, bridgeState);
   const brokerHttp = runtimeConfig.brokerHttp;
   const brokerWs = runtimeConfig.brokerWs;
@@ -2574,14 +2605,17 @@ async function startOpenclawBridge(flags) {
     console.log(`Claimed bridge device token for ${deviceId}.`);
   }
 
-  const gateway = readOpenclawGatewayConfig();
-  if (!gateway.token && !gateway.password) {
+  const localRuntime = bridgeState.localAgent
+    ? new LocalAgentRuntime(bridgeState.localAgent, path.dirname(resolveBridgeStatePath()), (health) => updateBridgeStatus(health))
+    : null;
+  const gateway = localRuntime ? { gatewayUrl: 'local-agent:', configPath: resolveBridgeStatePath() } : readOpenclawGatewayConfig();
+  if (!localRuntime && !gateway.token && !gateway.password) {
     throw new Error(`Gateway auth token/password not found in ${gateway.configPath}.`);
   }
-  const gatewayDeviceIdentity = loadGatewayDeviceIdentity();
-  if (!gatewayDeviceIdentity) {
+  const gatewayDeviceIdentity = localRuntime ? null : loadGatewayDeviceIdentity();
+  if (!localRuntime && !gatewayDeviceIdentity) {
     console.warn(
-      `[bridge] OpenClaw device identity not found at ${DEVICE_IDENTITY_PATH}; device-signed connect may fail on newer gateways.`
+      `[bridge] OpenClaw device identity not found at ${resolveOpenclawIdentityPath()}; device-signed connect may fail on newer gateways.`
     );
   }
 
@@ -2599,10 +2633,16 @@ async function startOpenclawBridge(flags) {
       gatewayUrl: gateway.gatewayUrl,
       gatewayConfigPath: gateway.configPath,
     });
+    if (!localRuntime) {
+      const result = await probeGateway({ gateway, deviceIdentity: gatewayDeviceIdentity, prepareFrame: prepareGatewayFrameForLocalGateway });
+      gateway.protocol = result.protocol;
+    }
+    updateBridgeStatus({ runtime: bridgeState.runtime || 'openclaw', runtimeReady: Boolean(bridgeState.verifiedAt), verifiedAt: bridgeState.verifiedAt || null, gatewayProtocol: gateway.protocol || null });
   } catch (err) {
     const failure = classifyBridgeFailure({ err });
     updateBridgeStatus({
       status: 'error',
+      runtimeReady: false,
       deviceId,
       brokerWs,
       brokerHttp,
@@ -2632,7 +2672,8 @@ async function startOpenclawBridge(flags) {
     startedAt: bridgeNowIso(),
   });
 
-  console.log(`Starting OpenClaw bridge: device=${deviceId}`);
+  console.log(`Starting ${bridgeState.runtime || 'openclaw'} bridge: device=${deviceId}`);
+  const stopChannelWorker = localRuntime ? startChannelWorker(bridgeState, localRuntime) : () => {};
   console.log(`Local gateway: ${gateway.gatewayUrl}`);
   console.log(`Broker WS: ${brokerWs}`);
   bridgeDebugLog(
@@ -3316,6 +3357,7 @@ async function startOpenclawBridge(flags) {
                 }
               }
             } else if (requestMeta.method === 'connect' && !responseMeta.ok) {
+              updateBridgeStatus({ status: 'degraded', runtimeReady: false, lastErrorCode: 'gateway_connect_rejected', lastErrorMessage: gatewayPayload?.error?.message || 'Local agent rejected the gateway handshake.', hint: 'Run oomi verify for this connection, repair the local runtime, and restart its bridge.' });
               const deferredFrames = Array.isArray(sessionBridge.waitingForConnect)
                 ? sessionBridge.waitingForConnect.splice(0, sessionBridge.waitingForConnect.length)
                 : [];
@@ -3353,6 +3395,12 @@ async function startOpenclawBridge(flags) {
           }
         }
 
+        if (gatewayPayload?.event === 'chat' && gatewayPayload.payload?.state === 'final') {
+          updateBridgeStatus({ runtimeReady: true, lastReplyAt: bridgeNowIso() });
+        } else if (gatewayPayload?.event === 'chat' && gatewayPayload.payload?.state === 'error') {
+          updateBridgeStatus({ status: 'degraded', runtimeReady: false, lastErrorMessage: gatewayPayload.payload.errorMessage || 'The local agent failed to answer.' });
+        }
+
         if (isGatewayRunStartedFrame(frame)) {
           sendGatewayAck(brokerSocket, {
             sessionId,
@@ -3445,7 +3493,7 @@ async function startOpenclawBridge(flags) {
       const sessionBridge = ensureSessionBridge({
         sessions: activeGatewaySockets,
         sessionId,
-        createSocket: () => new WebSocket(gateway.gatewayUrl),
+        createSocket: () => localRuntime ? localRuntime.socket() : new WebSocket(gateway.gatewayUrl),
       });
       if (sessionBridge) setupGatewaySession(sessionId, sessionBridge);
       return sessionBridge;
@@ -3798,8 +3846,10 @@ async function startOpenclawBridge(flags) {
     }));
   };
 
-  const markStopped = (signal) => {
+  const markStopped = async (signal) => {
     reconnectState.stopped = true;
+    stopChannelWorker();
+    if (localRuntime) await localRuntime.queue;
     if (reconnectState.timer) {
       clearTimeout(reconnectState.timer);
       reconnectState.timer = null;
@@ -3828,7 +3878,7 @@ async function startOpenclawBridge(flags) {
 
 async function pairAndStartOpenclawBridge(flags) {
   const bridgeState = readBridgeState();
-  const appUrl = String(flags['app-url'] || process.env.OOMI_APP_URL || 'http://127.0.0.1:3456').trim();
+  const appUrl = String(flags['app-url'] || process.env.OOMI_APP_URL || bridgeState.appUrl || 'https://www.oomi.ai').trim();
   const deviceId = resolveDeviceId(flags, bridgeState);
   const label = String(flags.label || `${deviceId}-bridge`).trim();
   const sessionKey = String(
@@ -3963,8 +4013,8 @@ async function createOpenclawInviteLink(flags) {
       bridgeState.brokerHttp ||
       ''
   ).trim();
-  const appUrl = String(flags['app-url'] || process.env.OOMI_APP_URL || 'http://127.0.0.1:3456').trim();
-  const configSessionKey = readOpenclawDefaultSessionKey();
+  const appUrl = String(flags['app-url'] || process.env.OOMI_APP_URL || bridgeState.appUrl || 'https://www.oomi.ai').trim();
+  const configSessionKey = bridgeConnectionName ? '' : readOpenclawDefaultSessionKey();
   const sessionKey = String(
     flags['session-key'] ||
       process.env.OOMI_SESSION_KEY ||
@@ -4013,6 +4063,7 @@ async function createOpenclawInviteLink(flags) {
 function printOpenclawBridgeStatus(flags) {
   const bridgeState = readBridgeState();
   const runtimeStatus = readBridgeStatus();
+  if (runtimeStatus.pid && !isBridgeProcess(runtimeStatus.pid)) { runtimeStatus.status = 'stopped'; runtimeStatus.runtimeReady = false; }
   const jsonOutput = isTruthyFlag(flags.json);
   const redactToken = (value) => {
     const text = String(value || '').trim();
@@ -4051,7 +4102,9 @@ function printOpenclawBridgeStatus(flags) {
     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')}`);
+    console.log(`Bridge state: ${String(payload.runtime.status || 'unknown')}`);
+    console.log(`Agent runtime: ${bridgeState.runtime || 'openclaw'}${bridgeState.localAgent?.profile ? ` (profile ${bridgeState.localAgent.profile})` : ''}`);
+    console.log(`Local reply verified: ${payload.runtime.runtimeReady ? 'yes' : 'no'}${payload.runtime.verifiedAt ? ` at ${payload.runtime.verifiedAt}` : ''}`);
     if (payload.runtime.lastConnectedAt) {
       console.log(`Last connected: ${payload.runtime.lastConnectedAt}`);
     }
@@ -4329,6 +4382,90 @@ async function handleBridgeLifecycleCommand(flags = {}, actionRaw = '') {
   );
 }
 
+function connectionDirectory() {
+  return path.join(process.env.OOMI_CONNECTIONS_DIR || path.join(os.homedir(), '.oomi', 'connections'), bridgeConnectionName);
+}
+
+async function verifyLocalAgent(state) {
+  if (state.openclawHome) process.env.OPENCLAW_HOME = state.openclawHome;
+  let result;
+  if (state.localAgent) {
+    await runLocalAgent(state.localAgent, {
+      sessionKey: `oomi:verify:${randomUUID()}`, idempotencyKey: randomUUID(), history: [],
+      message: 'Oomi connection check. Reply with OOMI_OK only. Do not use tools or change anything.',
+    });
+    result = { verifiedAt: new Date().toISOString() };
+  } else {
+    result = await probeGateway({ gateway: readOpenclawGatewayConfig(), deviceIdentity: loadGatewayDeviceIdentity(), prepareFrame: prepareGatewayFrameForLocalGateway, verifyReply: true, timeoutMs: 180000 });
+  }
+  return { runtime: state.runtime || 'openclaw', ...result };
+}
+
+async function connectLocalAgent(flags) {
+  const runtime = String(flags.runtime || '');
+  if (!['openclaw', 'hermes', 'command'].includes(runtime)) throw new Error('Specify --runtime openclaw, hermes, or command. Never select a different agent just because it is installed.');
+  const previous = readBridgeState();
+  if (previous.runtime && previous.runtime !== runtime) throw new Error('This connection belongs to a different runtime. Choose a different --name.');
+  const appUrl = String(flags['app-url'] || previous.appUrl || 'https://www.oomi.ai').replace(/\/$/, '');
+  if (previous.appUrl && previous.appUrl !== appUrl) throw new Error('This connection belongs to another Oomi site. Choose a different --name.');
+  const state = { ...previous, runtime, appUrl };
+  if (runtime === 'openclaw') state.openclawHome = previous.openclawHome || resolveOpenclawHome();
+  if (runtime !== 'openclaw') {
+    const saved = previous.localAgent;
+    state.localAgent = localAgentConfig({
+      ...flags,
+      command: flags.command || (saved ? JSON.stringify(saved.command) : undefined),
+      profile: flags.profile ?? saved?.profile,
+      'hermes-home': saved?.hermesHome,
+      resume: flags.resume ?? saved?.resume,
+      cwd: flags.cwd ?? saved?.cwd,
+    });
+    if (saved && JSON.stringify(saved) !== JSON.stringify(state.localAgent)) throw new Error('This name already identifies a different agent configuration. Use a new --name to change its command, profile, session, or working directory.');
+  }
+  console.log(`Verifying ${runtime}${state.localAgent?.profile ? ` profile ${state.localAgent.profile}` : ''} with a local test message...`);
+  try {
+    const verified = await verifyLocalAgent(state);
+    state.verifiedAt = verified.verifiedAt;
+  } catch (err) {
+    updateBridgeStatus({ runtime, runtimeReady: false, status: 'degraded', lastErrorMessage: err.message });
+    throw err;
+  }
+  if (!state.deviceToken) {
+    const config = await fetchManagedGatewayConfig({ appUrl });
+    state.brokerHttp = rewriteLoopbackBrokerUrlForAppHost(config.brokerHttpUrl, appUrl);
+    state.brokerWs = rewriteLoopbackBrokerUrlForAppHost(config.brokerDeviceWsUrl, appUrl);
+    const label = String(flags.label || flags.name || runtime);
+    const pair = await requestManagedPairCode({ appUrl, label });
+    state.deviceId = `${runtime}-${randomUUID()}`;
+    const claim = await claimBridgeDeviceToken({ brokerHttp: state.brokerHttp, pairCode: pair.pairCode, deviceId: state.deviceId });
+    state.deviceToken = claim.deviceToken;
+    state.sessionKey = String(flags['session-key'] || (runtime === 'openclaw' ? readOpenclawDefaultSessionKey() : '') || 'agent:main:webchat:channel:oomi');
+    state.claimedAt = new Date().toISOString();
+  }
+  // Stop this connection only; never leave a worker using an old adapter after a change.
+  const supervised = !bridgeConnectionName && process.platform === 'darwin' && readBridgeLaunchdStatus().installed;
+  const stopped = supervised ? await stopBridgeLaunchdService() : await stopBridgeProcesses();
+  if (stopped.stillAlive?.length) throw new Error('The existing bridge did not stop. Resolve it before reconnecting.');
+  writeBridgeState(state);
+  updateBridgeStatus({ status: 'starting', runtime, runtimeReady: true, verifiedAt: state.verifiedAt, lastErrorMessage: '' });
+  const child = supervised ? (startBridgeLaunchdService(), { pid: null }) : startBridgeDetachedProcess({ 'app-url': appUrl });
+  const deadline = Date.now() + 20000;
+  let connected = false;
+  while (Date.now() < deadline) {
+    const status = readBridgeStatus();
+    if (status.pid && (!child.pid || status.pid === child.pid) && status.status === 'connected') { connected = true; break; }
+    if ((!child.pid || status.pid === child.pid) && status.status === 'error') throw new Error(status.lastErrorMessage || 'Bridge startup failed.');
+    if (child.pid && !isPidAlive(child.pid)) throw new Error(`Bridge exited. Check ${resolveBridgeLiveLogPath()}.`);
+    await delay(200);
+  }
+  if (!connected) throw new Error('The local agent replied, but the Oomi bridge did not connect. Run oomi status for this connection.');
+  const invite = await requestConnectInviteLink({ backendHttp: state.brokerHttp, appUrl, sessionKey: state.sessionKey, deviceToken: state.deviceToken });
+  console.log(`Verified agent: ${runtime}${state.localAgent?.profile ? ` (${state.localAgent.profile})` : ''}`);
+  console.log('Oomi Connect Ready');
+  console.log(`Auth Link: ${invite.inviteUrl}`);
+  console.log('Open the Auth Link to approve ownership, then send a message in Oomi to verify delivery end to end.');
+}
+
 async function main() {
   const args = parseArgs(process.argv);
   const command = args.command;
@@ -4339,6 +4476,29 @@ async function main() {
     process.exit(0);
   }
 
+  const connection = args.flags.connection || args.flags.name || (command === 'connect' && args.flags.runtime !== 'openclaw' ? args.flags.runtime : '');
+  if (connection && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(connection)) throw new Error('Connection name must use lowercase letters, numbers, underscores, or hyphens.');
+  bridgeConnectionName = connection || '';
+
+  if (command === 'connect') return connectLocalAgent(args.flags);
+  if (command === 'verify') {
+    const state = readBridgeState();
+    if (!state.deviceToken) throw new Error('No saved connection. Run oomi connect with an explicit runtime first.');
+    try {
+      const result = await verifyLocalAgent(state);
+      writeBridgeState({ ...state, verifiedAt: result.verifiedAt });
+      updateBridgeStatus({ runtimeReady: true, verifiedAt: result.verifiedAt, lastErrorMessage: '' });
+      console.log(JSON.stringify(result, null, 2));
+    } catch (err) {
+      updateBridgeStatus({ runtimeReady: false, status: 'degraded', lastErrorMessage: err.message });
+      throw err;
+    }
+    return;
+  }
+  if (command === 'status') return printOpenclawBridgeStatus(args.flags);
+  if (command === 'invite') return createOpenclawInviteLink(args.flags);
+  if (command === 'bridge') return handleBridgeLifecycleCommand(args.flags, subcommand || 'start');
+
   await maybeNotifyUpdate(command);
 
   if (command === 'init') {
@@ -4363,6 +4523,7 @@ async function main() {
   if (command === 'openclaw' && subcommand === 'bridge') {
     const bridgeAction = String(args.positionals[0] || 'start').trim().toLowerCase();
     if (bridgeAction === 'service') {
+      if (bridgeConnectionName) throw new Error('Named connections use oomi bridge start --name NAME with your host process supervisor. The legacy OpenClaw service is only for the default connection.');
       const serviceAction = args.positionals[1] || 'status';
       await handleBridgeServiceCommand(serviceAction, args.flags);
       return;
@@ -4461,7 +4622,9 @@ async function main() {
 
 const __currentFilePath = fileURLToPath(import.meta.url);
 const __invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : '';
-const __isDirectExecution = Boolean(__invokedPath) && __invokedPath === path.resolve(__currentFilePath);
+const __isDirectExecution = Boolean(__invokedPath)
+  && fs.existsSync(__invokedPath)
+  && fs.realpathSync(__invokedPath) === fs.realpathSync(__currentFilePath);
 
 if (__isDirectExecution) {
   main().catch((err) => {

package/lib/gatewayProbe.js

@@ -0,0 +1,60 @@
+import WebSocket from 'ws';
+import { randomUUID } from 'node:crypto';
+
+// The broker's protocol is independent of the installed local gateway version.
+export const LOCAL_PROTOCOL_MIN = 3;
+export const LOCAL_PROTOCOL_MAX = 4;
+
+export function probeGateway({ gateway, deviceIdentity, prepareFrame, verifyReply = false, timeoutMs = 15000 }) {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(gateway.gatewayUrl);
+    const connectId = randomUUID();
+    const runId = randomUUID();
+    let settled = false;
+    let sent = false;
+    let protocol;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners('message');
+      socket.close();
+      if (error) reject(error); else resolve(result);
+    };
+    const timer = setTimeout(() => finish(new Error('Local agent verification timed out. Check its gateway, model credentials, and logs.')), timeoutMs);
+    const connect = (nonce = '') => {
+      if (sent) return;
+      const frame = prepareFrame(JSON.stringify({ type: 'req', id: connectId, method: 'connect', params: {} }), gateway, { deviceIdentity, connectNonce: nonce });
+      if (frame.waitForChallenge) return;
+      sent = true;
+      socket.send(frame.frameText);
+    };
+    socket.on('open', () => { if (!deviceIdentity) connect(); });
+    socket.on('error', (err) => finish(new Error(`Local gateway verification failed: ${err.message}`)));
+    socket.on('close', (code) => finish(new Error(`Local gateway closed before verification completed (${code}).`)));
+    socket.on('message', (raw) => {
+      let frame;
+      try { frame = JSON.parse(raw.toString()); } catch { return; }
+      if (frame.event === 'connect.challenge') connect(frame.payload?.nonce);
+      if (frame.type === 'res' && (frame.id === connectId || frame.id === runId) && !frame.ok) {
+        finish(new Error(`Local agent rejected ${frame.id === connectId ? 'connect' : 'verification'}: ${frame.error?.message || frame.error?.code || 'unknown error'}`));
+      } else if (frame.type === 'res' && frame.id === connectId && frame.ok) {
+        protocol = frame.payload?.protocol;
+        if (![3, 4].includes(protocol)) return finish(new Error('Local gateway returned an unsupported protocol version. Update oomi-ai.'));
+        if (!verifyReply) return finish(null, { protocol });
+        socket.send(JSON.stringify({ type: 'req', id: runId, method: 'chat.send', params: {
+          sessionKey: `agent:main:oomi:verify:${runId}`, idempotencyKey: runId,
+          message: 'Oomi connection check. Reply with OOMI_OK only. Do not use tools or change anything.',
+        } }));
+      } else if (verifyReply && frame.event === 'chat' && frame.payload?.runId === runId) {
+        if (frame.payload.state === 'error' || frame.payload.state === 'aborted') return finish(new Error('Local agent could not complete the verification message.'));
+        if (frame.payload.state === 'final') {
+          const content = frame.payload.message?.content;
+          const text = typeof content === 'string' ? content : (Array.isArray(content) ? content.map((part) => part.text || '').join('') : '');
+          if (!text.trim()) return finish(new Error('Local agent returned an empty verification reply.'));
+          finish(null, { protocol, verifiedAt: new Date().toISOString() });
+        }
+      }
+    });
+  });
+}