oomi-ai 0.8.1 → 0.8.2

package/README.md

@@ -82,7 +82,9 @@ oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, Hermes uses `chat --quiet --query-file -` and resumes the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
 
 The command verifies a real local reply, reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 

package/agent_instructions.md

@@ -135,7 +135,9 @@ oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, Hermes uses `chat --quiet --query-file -` and resumes the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
 
 The first connection verifies a real local reply (reconnects reuse verification), reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 

package/bin/oomi-ai.js

@@ -3360,7 +3360,7 @@ 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.' });
+          updateBridgeStatus({ ...(localRuntime && gatewayPayload.payload.runtimeReady === true ? { runtimeReady: true } : { status: 'degraded', runtimeReady: false }), lastErrorMessage: gatewayPayload.payload.errorMessage || 'The local agent failed to answer.' });
         }
 
         if (isGatewayRunStartedFrame(frame)) {

package/lib/hermesGateway.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import WebSocket from 'ws';
+
+// Only fixed, sanitized messages cross the bridge. Gateway diagnostics may contain
+// credentials, private history or tool output; never interpolate them into errors.
+export class HermesTurnError extends Error {
+  constructor(code, message, { notStarted = false, runtimeReady = true } = {}) {
+    super(message); this.code = code; this.notStarted = notStarted; this.runtimeReady = runtimeReady;
+  }
+}
+const refused = (code, message) => new HermesTurnError(code, message, { notStarted: true });
+export function hermesRefusal(reason) {
+  if (reason === 'SESSION_NOT_OWNED') return refused('hermes_session_owned', 'This conversation is open in Hermes, but Oomi could not attach to it. Keep the same chat and update Hermes and Oomi on that computer, then retry.');
+  if (reason === 'MAX_CONCURRENT_SESSIONS') return refused('hermes_session_limit', 'Hermes has reached its active conversation limit. Free a conversation slot or raise the limit in Hermes, then retry.');
+  if (reason === 'SESSION_COORDINATION_UNAVAILABLE') return refused('hermes_coordination_unavailable', 'Hermes could not verify conversation ownership. Check Hermes on that computer, then retry.');
+  return null;
+}
+function readLocalJson(file, missing) {
+  try {
+    if (fs.statSync(file).size > 1024 * 1024) throw new Error();
+    return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+  } catch (err) {
+    if (err.code === 'ENOENT') return missing;
+    throw hermesRefusal('SESSION_COORDINATION_UNAVAILABLE');
+  }
+}
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (err) { return err.code !== 'ESRCH'; }
+}
+function findOwner(config, sessionId) {
+  const profile = config.profile || 'default';
+  if (!config.hermesHome || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(profile)) throw hermesRefusal('SESSION_COORDINATION_UNAVAILABLE');
+  const home = profile === 'default' ? config.hermesHome : path.join(config.hermesHome, 'profiles', profile);
+  const raw = readLocalJson(path.join(home, 'runtime', 'active_sessions.json'), []);
+  const entries = Array.isArray(raw) ? raw : raw?.entries;
+  if (!Array.isArray(entries) || entries.some(e => !e || typeof e.session_id !== 'string' || !Number.isInteger(e.pid) || e.pid <= 0)) throw hermesRefusal('SESSION_COORDINATION_UNAVAILABLE');
+  const owners = entries.filter(e => e.session_id === sessionId && alive(e.pid));
+  if (!owners.length) return null; // CLI still acquires Hermes's own exclusive lease.
+  if (owners.length !== 1) throw hermesRefusal('SESSION_COORDINATION_UNAVAILABLE');
+  const owner = owners[0];
+  const ledger = readLocalJson(path.join(config.hermesHome, 'spawn-ledger.json'), []);
+  const hosts = new Set(['', '0.0.0.0', '127.0.0.1', '::', '::1', 'localhost']);
+  const candidates = Array.isArray(ledger) ? ledger.filter(e => e?.pid === owner.pid && e.isolated !== true && ['serve', 'dashboard'].includes(e.purpose) && hosts.has(e.host || '') && Number.isInteger(e.port) && e.port > 0 && e.port <= 65535) : [];
+  if (!owner.metadata?.live_session_id || candidates.length !== 1) throw hermesRefusal('SESSION_NOT_OWNED');
+  const backend = candidates[0];
+  return { pid: owner.pid, liveId: owner.metadata.live_session_id, profile, base: `http://${backend.host === '::1' ? '[::1]' : '127.0.0.1'}:${backend.port}` };
+}
+
+async function servedToken(base, signal) {
+  // Match Hermes Desktop's supported loopback discovery. Never follow redirects,
+  // read credential stores, or bypass a gateway login when no token is served.
+  const response = await fetch(`${base}/`, { signal, redirect: 'error' });
+  if (!response.ok) throw new Error();
+  let html = '';
+  for await (const chunk of response.body) {
+    html += Buffer.from(chunk).toString('utf8');
+    if (html.length > 1024 * 1024) throw new Error();
+  }
+  const match = html.match(/window\.__HERMES_SESSION_TOKEN__\s*=\s*("(?:\\.|[^"\\])*")/);
+  const token = match && JSON.parse(match[1]);
+  if (typeof token !== 'string' || !token || token.length > 8192) throw new Error();
+  return token;
+}
+
+function connect(owner, token, signal, onEvent) {
+  const socket = new WebSocket(`${owner.base.replace(/^http/, 'ws')}/api/ws?token=${encodeURIComponent(token)}`, { handshakeTimeout: 5000, maxPayload: 4 * 1024 * 1024, followRedirects: false });
+  const pending = new Map();
+  let sequence = 0, failure;
+  let readyResolve, readyReject;
+  const ready = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+  ready.catch(() => {});
+  const readyTimer = setTimeout(() => { fail(); socket.terminate(); }, 5000);
+  const fail = (err = new Error()) => {
+    if (failure) return;
+    failure = err; clearTimeout(readyTimer); readyReject(err);
+    for (const p of pending.values()) { clearTimeout(p.timer); p.reject(err); }
+    pending.clear(); onEvent(null, err);
+  };
+  const abort = () => { fail(); socket.terminate(); };
+  signal.addEventListener('abort', abort, { once: true });
+  socket.on('error', () => fail());
+  socket.on('close', () => fail());
+  socket.on('message', data => {
+    try {
+      for (const line of data.toString().split('\n').filter(s => s.trim())) {
+        const frame = JSON.parse(line);
+        if (frame.method === 'event') {
+          if (frame.params?.type === 'gateway.ready') { clearTimeout(readyTimer); readyResolve(); }
+          else onEvent(frame.params);
+        } else if (pending.has(frame.id)) {
+          const p = pending.get(frame.id); pending.delete(frame.id); clearTimeout(p.timer);
+          if (frame.error) p.reject(hermesRefusal(p.method === 'prompt.submit' && frame.error.code === 4090 && frame.error.data?.reason) || new Error());
+          else p.resolve(frame.result);
+        }
+      }
+    } catch { fail(); }
+  });
+  return {
+    ready,
+    rpc(method, params = {}) {
+      if (failure || signal.aborted) return Promise.reject(failure || new Error());
+      const id = ++sequence;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { pending.delete(id); reject(new Error()); }, 10000);
+        pending.set(id, { resolve, reject, timer, method });
+        socket.send(JSON.stringify({ jsonrpc: '2.0', id, method, params: { ...params, profile: owner.profile } }), err => { if (err) fail(); });
+      });
+    },
+    close() { signal.removeEventListener('abort', abort); fail(); socket.terminate(); },
+  };
+}
+
+/** Attach to the exact existing owner, or return null when CLI lease acquisition is appropriate. */
+export async function runSharedHermesTurn(config, request, { signal, timeoutMs = 180000 } = {}) {
+  if (!request.runtimeSessionId) return null;
+  const owner = findOwner(config, request.runtimeSessionId);
+  if (!owner) return null;
+  // Hermes's image.attach stages media globally for the next sender. Refuse until
+  // the gateway supports atomic message+media admission; never steal desktop photos.
+  if (request.imagePaths?.length) throw refused('hermes_shared_photo', 'Photos in an open Hermes desktop conversation are not supported yet. Send this photo from Hermes desktop in the same chat.');
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(abort, timeoutMs);
+  let client, heartbeat, dispatched = false, userRowId;
+  const early = [];
+  let completeResolve, completeReject;
+  const completed = new Promise((resolve, reject) => { completeResolve = resolve; completeReject = reject; });
+  completed.catch(() => {});
+  const final = payload => {
+    if (payload?.persisted_turn?.user_row_id !== userRowId) return;
+    if (payload.status !== 'complete' || !Number.isSafeInteger(payload.persisted_turn.final_assistant_row_id) || typeof payload.text !== 'string' || !payload.text.trim()) {
+      completeReject(new HermesTurnError('hermes_turn_failed', 'Hermes did not finish this message. Check the same conversation in Hermes for its error or approval request before retrying.'));
+    } else completeResolve({ text: payload.text.trim(), sessionId: request.runtimeSessionId });
+  };
+  try {
+    if (controller.signal.aborted) throw new Error();
+    const authTimer = setTimeout(abort, Math.min(timeoutMs, 5000));
+    let token;
+    try { token = await servedToken(owner.base, controller.signal); } finally { clearTimeout(authTimer); }
+    client = connect(owner, token, controller.signal, (event, err) => {
+      if (err) { completeReject(err); return; }
+      if (!dispatched || event?.type !== 'message.complete' || event.session_id !== owner.liveId) return;
+      if (userRowId) final(event.payload);
+      else { if (early.length >= 32) early.shift(); early.push(event.payload); }
+    });
+    await client.ready;
+    const list = await client.rpc('session.active_list');
+    const matches = list?.sessions?.filter(s => s.id === owner.liveId && s.session_key === request.runtimeSessionId);
+    if (matches?.length !== 1) throw hermesRefusal('SESSION_NOT_OWNED');
+    if (matches[0].status !== 'idle') throw refused('hermes_session_busy', 'Hermes is busy in this conversation. Let its current task finish, then retry here. Your message has not been sent.');
+    const attached = await client.rpc('session.activate', { session_id: owner.liveId, omit_messages: true });
+    if (attached?.session_id !== owner.liveId || attached.session_key !== request.runtimeSessionId) throw hermesRefusal('SESSION_NOT_OWNED');
+    if (attached.running || attached.queued || attached.status !== 'idle') throw refused('hermes_session_busy', 'Hermes is busy in this conversation. Let its current task finish, then retry here. Your message has not been sent.');
+    // No server_requests capability: existing Hermes clients retain their normal
+    // approval UI. Oomi never answers or auto-approves another client's requests.
+    heartbeat = setInterval(() => { client.rpc('gateway.ping').catch(completeReject); }, 15000);
+    dispatched = true;
+    const accepted = await client.rpc('prompt.submit', { session_id: owner.liveId, text: request.message, queued: true });
+    // A concurrent desktop send may win after the idle check. Hermes queues ours
+    // without interruption but currently returns no durable row ID for that path.
+    // Do not misattribute the desktop reply or replay a possibly accepted action.
+    if (accepted?.status === 'queued') throw new HermesTurnError('hermes_message_queued', 'Hermes queued your message behind another task. Check the same conversation in Hermes for the reply; do not send this message again.');
+    if (accepted?.status !== 'streaming' || !Number.isSafeInteger(accepted.user_row_id) || accepted.user_row_id <= 0) throw new HermesTurnError('hermes_receipt_unavailable', 'Hermes may have accepted your message, but could not confirm its reply address. Check the same conversation in Hermes before retrying. Update Hermes on that computer for shared chat support.');
+    userRowId = accepted.user_row_id;
+    for (const payload of early) final(payload);
+    const result = await completed;
+    // Compaction can rotate Hermes's durable session key while keeping the same
+    // live owner. Follow that exact owner, never a 'latest' conversation lookup.
+    try {
+      const current = await client.rpc('session.active_list');
+      const session = current?.sessions?.find(s => s.id === owner.liveId);
+      if (typeof session?.session_key === 'string' && /^[A-Za-z0-9_-]+$/.test(session.session_key)) result.sessionId = session.session_key;
+    } catch { /* The confirmed reply remains valid when a follow-up read fails. */ }
+    return result;
+  } catch (err) {
+    if (err instanceof HermesTurnError) throw err;
+    if (dispatched) throw new HermesTurnError('hermes_reply_uncertain', 'Oomi lost track of this reply. Hermes may still be working in the same conversation. Check it there before sending this message again.');
+    throw refused('hermes_attach_failed', 'Oomi could not attach to the open Hermes conversation. Check Hermes on that computer and its local connection, then retry. Your message has not been sent.');
+  } finally {
+    clearTimeout(timer); clearInterval(heartbeat); signal?.removeEventListener('abort', abort); controller.abort(); client?.close();
+  }
+}

package/lib/localAgent.js

@@ -4,6 +4,7 @@ import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { createHash, randomUUID } from 'node:crypto';
+import { runSharedHermesTurn, hermesRefusal } from './hermesGateway.js';
 
 const IMAGE_EXTENSIONS = { 'image/jpeg': '.jpg', 'image/png': '.png', 'image/webp': '.webp', 'image/gif': '.gif' };
 const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
@@ -98,7 +99,24 @@ export function localAgentConfig(flags) {
 }
 
 // No shell interpolation. Message bodies travel over stdin, never as executable code.
-export function runLocalAgent(config, request, { signal, timeoutMs = 180000 } = {}) {
+export async function runLocalAgent(config, request, options = {}) {
+  if (config.runtime === 'hermes') {
+    const shared = await runSharedHermesTurn(config, request, options);
+    if (shared) return shared;
+  }
+  try { return await runAgentProcess(config, request, options); }
+  catch (err) {
+    // Ownership may change between discovery and CLI lease acquisition. Only a
+    // machine-readable pre-start refusal permits trying the live owner once.
+    if (config.runtime === 'hermes' && err.code === 'hermes_session_owned') {
+      const shared = await runSharedHermesTurn(config, request, options);
+      if (shared) return shared;
+    }
+    throw err;
+  }
+}
+
+function runAgentProcess(config, request, { signal, timeoutMs = 180000 } = {}) {
   return new Promise((resolve, reject) => {
     const args = config.command.slice(1);
     if (config.runtime === 'hermes') {
@@ -112,6 +130,7 @@ export function runLocalAgent(config, request, { signal, timeoutMs = 180000 } =
     const child = spawn(config.command[0], args, { env, cwd: config.cwd, shell: false, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] });
     let output = '';
     let diagnostics = '';
+    let diagnosticsTruncated = false;
     child.stdout.setEncoding('utf8');
     child.stderr.setEncoding('utf8');
     let bytes = 0;
@@ -139,13 +158,16 @@ export function runLocalAgent(config, request, { signal, timeoutMs = 180000 } =
       output += data.toString();
     });
     // Diagnostics may contain credentials or tool output; never forward them to Oomi.
-    child.stderr.on('data', (data) => { diagnostics = (diagnostics + data).slice(-8192); });
+    child.stderr.on('data', (data) => { diagnosticsTruncated ||= diagnostics.length + data.length > 8192; diagnostics = (diagnostics + data).slice(-8192); });
     child.stdin.on('error', () => {});
     child.on('error', (err) => { error = new Error(`Could not start ${config.runtime} agent (${err.code || 'spawn failed'}). Check the executable and working directory.`); });
     child.on('close', (code) => {
       clearTimeout(timer); clearTimeout(killer); signal?.removeEventListener('abort', abort);
       if (error) return reject(error);
-      if (code !== 0) return reject(new Error(`Agent exited with code ${code}. Check local runtime credentials and logs.`));
+      if (code !== 0) {
+        const reason = config.runtime === 'hermes' && code === 1 && !diagnosticsTruncated && !output.trim() && diagnostics.match(/^hermes-refusal-reason:\s*([A-Z_]+)(?:\r?\n|$)/)?.[1];
+        return reject(hermesRefusal(reason) || new Error(`Agent exited with code ${code}. Check local runtime credentials and logs.`));
+      }
       try {
         const result = config.runtime === 'hermes'
           ? { text: output, sessionId: diagnostics.match(/(?:^|\n)session_id:\s*([A-Za-z0-9_-]+)\s*(?:\n|$)/)?.[1] }
@@ -189,7 +211,7 @@ export class LocalAgentRuntime {
       if (previous?.message !== undefined && previous.message !== message) throw new Error('Idempotency key was reused for a different message.');
       if (previous?.result) return previous.result;
       // A crash after a side effect cannot safely be retried by running the agent again.
-      if (previous && !retryInterrupted) throw new Error('The previous turn was interrupted. Check the agent before sending a new message.');
+      if (previous && previous.status !== 'not_started' && !retryInterrupted) throw new Error('The previous turn was interrupted. Check the agent before sending a new message.');
       if (controller.signal.aborted) throw new Error('Agent turn cancelled.');
       state.receipts[receiptKey] = { message, status: 'running' };
       writePrivateJson(this.file(sessionKey), state);
@@ -203,7 +225,14 @@ export class LocalAgentRuntime {
         writePrivateJson(this.file(sessionKey), state);
         this.onHealth({ runtimeReady: true, lastReplyAt: new Date().toISOString(), lastErrorMessage: '' });
         return result;
-      } catch (err) { this.onHealth({ runtimeReady: false, status: 'degraded', lastErrorMessage: err.message }); throw err; }
+      } catch (err) {
+        if (err.notStarted === true) {
+          state.receipts[receiptKey] = { message, status: 'not_started' };
+          writePrivateJson(this.file(sessionKey), state);
+        }
+        this.onHealth({ runtimeReady: err.runtimeReady === true, ...(err.runtimeReady === true ? {} : { status: 'degraded' }), lastErrorMessage: err.message });
+        throw err;
+      }
       finally { if (scratch) fs.rmSync(scratch.directory, { recursive: true, force: true }); }
     });
     this.queue = promise.catch(() => {});
@@ -252,7 +281,7 @@ class LocalAgentSocket extends EventEmitter {
     this.runtime.turn({ ...params, idempotencyKey: runId }).then((result) => {
       this.frame({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'final', message: { role: 'assistant', content: [{ type: 'text', text: result.text }], timestamp: Date.now() } } });
     }, (err) => {
-      this.frame({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'error', errorMessage: err.message } });
+      this.frame({ type: 'event', event: 'chat', payload: { runId, sessionKey: params.sessionKey, state: 'error', errorMessage: err.message, ...(typeof err.runtimeReady === 'boolean' ? { runtimeReady: err.runtimeReady } : {}) } });
     });
   }
   close(code = 1000, reason = '') { if (this.readyState === 3) return; this.readyState = 3; this.emit('close', code, reason); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Connect OpenClaw, Hermes, and other local agents to Oomi with verified runtime adapters",
   "bin": {
     "oomi": "bin/oomi-ai.js"
@@ -49,7 +49,7 @@
     "url": "https://github.com/crispcode-io/oomi/issues"
   },
   "scripts": {
-    "check": "node --check bin/oomi-ai.js && node --check lib/bridgeService.js && node --check lib/bridgeMaintenance.js",
+    "check": "node --check bin/oomi-ai.js && node --check lib/bridgeService.js && node --check lib/bridgeMaintenance.js && node --check lib/localAgent.js && node --check lib/hermesGateway.js",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
@@ -78,6 +78,7 @@
     "lib/spaces.js",
     "lib/objectives.js",
     "lib/bridgeService.js",
-    "lib/bridgeMaintenance.js"
+    "lib/bridgeMaintenance.js",
+    "lib/hermesGateway.js"
   ]
 }

package/skills/oomi/SKILL.md

@@ -161,7 +161,9 @@ oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, Hermes uses `chat --quiet --query-file -` and resumes the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
 
 The command verifies a real local reply, reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 

package/skills/oomi/agent_instructions.md

@@ -135,7 +135,9 @@ oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, Hermes uses `chat --quiet --query-file -` and resumes the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
 
 The first connection verifies a real local reply (reconnects reuse verification), reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.