oomi-ai 0.10.0 → 0.10.2

package/agent_instructions.md

@@ -132,6 +132,8 @@ The legacy persona-app commands below remain compatibility tools; use Spaces for
 
 Use this when your owner asks you to let another agent (Claude, Codex, a Grok bot, or another Oomi agent) talk with you directly. For example: "make a link so Claude can ask you how to set up Obsidian".
 
+**Your only job is to create the link and then answer.** Your owner gives the link to the other agent, and that agent joins from wherever it already runs, usually another computer. Do not install, launch, sign in to, or message that agent yourself, even if a copy of it is installed on your computer. Never ask your owner for passwords, sign-in links or one-time codes for it. You don't need the other agent to be ready first: create the link right away.
+
 1. Create a channel with a specific purpose: `oomi channel create --purpose "Help Claude set up Obsidian on this computer"`. If useful, add `--expires-minutes N` (default 120, at most 1440) or `--greeting "..."`.
 2. Give your owner the returned `link`. Tell them it works for one agent only, until `joinBy`. Never post the link publicly or share your device token. The link is all the other agent needs.
 3. Each message from the other agent arrives as its own turn in a separate conversation (`agent:main:oomi:channel:ID`), headed "Oomi agent channel". Your final reply text is sent back automatically. Do not also send that reply with `oomi channel send`.
@@ -140,6 +142,10 @@ Use this when your owner asks you to let another agent (Claude, Codex, a Grok bo
 
 To review a channel, use `oomi channel list` and `oomi channel show ID`.
 
+**When you can't answer.** Your AI provider might reject your sign-in, hit a limit or be unreachable. If so, oomi records the reason, tells your owner what to fix and tells the other side the message wasn't answered. Tell your owner plainly which AI provider failed and what it said. Ask them to sign in again on this computer themselves, in a terminal or the provider's app here. Never ask them to paste passwords or one-time codes into a chat. `oomi verify --connection NAME` checks that you can answer again. `oomi channel create` also returns `warnings` when your bridge can't answer; tell your owner before they share the link.
+
+**Use your own connection.** Turns started by the bridge already use it. Otherwise, pass `--connection NAME` (`oomi bridge list` shows the names). If oomi says it used a connection that isn't linked, rerun with your own. Don't create a new Auth Link unless your owner asked to connect you.
+
 To join another agent's link as a guest:
 
 1. Run `oomi channel join LINK`.

package/bin/oomi-ai.js

@@ -20,6 +20,7 @@ import { handleSpacesCommand, compactHealth } from '../lib/spaces.js';
 import { handleObjectivesCommand } from '../lib/objectives.js';
 import { handleRoutinesCommand, startRoutineEventWorker } from '../lib/routines.js';
 import { handleChannelCommand, startAgentChannelWorker } from '../lib/agentChannels.js';
+import { classifyRuntimeFailure } from '../lib/runtimeFailure.js';
 import { createPersonaApiClient } from '../lib/personaApiClient.js';
 import { inferSpokenMetadataFromContent, normalizeSpokenMetadata } from '../lib/spokenMetadata.js';
 import {
@@ -2650,7 +2651,9 @@ async function startOpenclawBridge(flags) {
     state: { ...bridgeState, brokerHttp, deviceToken },
     connection: bridgeConnectionName,
     deliver: deliverAgentEvent,
-    onError: (error) => updateBridgeStatus({ agentChannelError: `Agent channel delivery: ${error.message}` }),
+    onError: (error) => updateBridgeStatus({ agentChannelError: error.failure
+      ? `Couldn't answer a chat-link message: ${error.failure.summary}. ${error.failure.hint}`
+      : `Agent channel delivery: ${error.message}` }),
     onDelivered: () => updateBridgeStatus({ agentChannelError: '' }),
   });
   console.log(`Local gateway: ${gateway.gatewayUrl}`);
@@ -4450,6 +4453,14 @@ function connectionDirectory() {
   return path.join(process.env.OOMI_CONNECTIONS_DIR || path.join(os.homedir(), '.oomi', 'connections'), bridgeConnectionName);
 }
 
+// A failed connection check usually means the agent's own AI access is broken.
+// Say that plainly, with the fix, instead of a bare runtime error.
+function explainVerificationFailure(err) {
+  const failure = classifyRuntimeFailure(err);
+  if (failure.code === 'runtime_failed') return err;
+  return Object.assign(new Error(`This agent couldn't answer the connection check: ${failure.summary}. ${failure.hint} Oomi itself is fine; nothing else needs reconnecting. (Details: ${failure.detail})`), { failure });
+}
+
 async function verifyLocalAgent(state) {
   if (state.openclawHome) process.env.OPENCLAW_HOME = state.openclawHome;
   let result;
@@ -4519,8 +4530,9 @@ async function connectLocalAgent(flags) {
     const verified = await verifyLocalAgent(state);
     state.verifiedAt = verified.verifiedAt;
   } catch (err) {
-    updateBridgeStatus({ runtime, runtimeReady: false, status: 'degraded', lastErrorMessage: err.message });
-    throw err;
+    const explained = explainVerificationFailure(err);
+    updateBridgeStatus({ runtime, runtimeReady: false, status: 'degraded', lastErrorMessage: explained.message });
+    throw explained;
   }
   } else {
     console.log(`Reusing the verified ${runtime} runtime. No model test message sent. Use oomi verify for an explicit paid-model probe.`);
@@ -4676,8 +4688,9 @@ async function main() {
       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;
+      const explained = explainVerificationFailure(err);
+      updateBridgeStatus({ runtimeReady: false, status: 'degraded', lastErrorMessage: explained.message });
+      throw explained;
     }
     return;
   }

package/lib/agentChannels.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { readJson, writePrivateJson } from './localAgent.js';
+import { classifyRuntimeFailure } from './runtimeFailure.js';
 
 // Owner-visible conversations between this agent and one other agent.
 // Host side uses the device token against the Oomi API. Guest side (after
@@ -42,6 +44,46 @@ export function parseChannelLink(link) {
   return { origin: url.origin, token: match[1] };
 }
 
+function connectionsRoot() {
+  return process.env.OOMI_CONNECTIONS_DIR || path.join(os.homedir(), '.oomi', 'connections');
+}
+
+function localConnections() {
+  try {
+    return fs.readdirSync(connectionsRoot(), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(connectionsRoot(), entry.name, 'oomi-bridge.json')))
+      .map((entry) => entry.name);
+  } catch { return []; }
+}
+
+// Agents that ran a command without --connection were sent to a stale default
+// connection and then created Auth Links for it. Say which connection was used
+// and which others exist, and steer away from reconnecting.
+export function explainConnectionError(error, directory) {
+  const notLinked = error?.status === 403 && /not linked/i.test(error.message || '');
+  const missing = /Connect this agent to Oomi first/.test(error?.message || '');
+  if (!notLinked && !missing) return error;
+  const named = directory && path.resolve(path.dirname(directory)) === path.resolve(connectionsRoot());
+  const label = named ? `the connection "${path.basename(directory)}"` : 'the default OpenClaw connection';
+  const others = localConnections().filter((name) => !named || name !== path.basename(directory));
+  const problem = missing ? `found no saved login for ${label}` : `used ${label}, but that connection isn't linked to an oomi account`;
+  const next = others.length
+    ? `Connections on this computer: ${others.join(', ')}. If one of them is you, rerun with --connection NAME.`
+    : 'No other oomi connections were found on this computer.';
+  return Object.assign(new Error(`oomi ${problem}. ${next} Don't create a new Auth Link or reconnect unless your owner asked to connect this agent.`), { status: error.status, reasonCode: error.reasonCode });
+}
+
+// A link only helps if this agent can answer; warn before handing one out.
+export function bridgeWarnings(directory) {
+  if (!directory) return [];
+  const status = readJson(path.join(directory, 'oomi-bridge-status.json'), null);
+  if (!status) return ['No oomi bridge status was found for this connection. Run oomi bridge repair for it, or guest messages will wait unanswered.'];
+  const warnings = [];
+  if (['error', 'degraded', 'failed', 'stopped'].includes(status.status)) warnings.push(`Your oomi bridge reports "${status.status}"${status.lastErrorMessage ? `: ${String(status.lastErrorMessage).replace(/\.\s*$/, '')}` : ''}.`);
+  if (status.agentChannelError) warnings.push(status.agentChannelError);
+  return warnings;
+}
+
 function guestRecordPath(directory, channelId) {
   return path.join(directory, 'agent-channels', `${channelId}.json`);
 }
@@ -90,7 +132,10 @@ function optionalInteger(value, name) {
   return number;
 }
 
-export async function handleChannelCommand(state, action, flags = {}, positionals = [], { directory, request = channelRequest, guest = guestRequest, print = (value) => console.log(JSON.stringify(value, null, 2)) } = {}) {
+export async function handleChannelCommand(state, action, flags = {}, positionals = [], { directory, request: rawRequest = channelRequest, guest = guestRequest, print = (value) => console.log(JSON.stringify(value, null, 2)) } = {}) {
+  const request = async (...args) => {
+    try { return await rawRequest(...args); } catch (error) { throw explainConnectionError(error, directory); }
+  };
   const id = positionals[0] || flags.id;
   const requireId = () => { if (typeof id !== 'string' || !CHANNEL_ID.test(id)) throw new Error('Provide a channel ID (ach_...) from oomi channel list.'); };
   let result;
@@ -110,7 +155,9 @@ export async function handleChannelCommand(state, action, flags = {}, positional
       } });
       result = { ...result, next: audience === 'person'
         ? 'Give your owner both links: the chat link to send to the person, and the watchUrl where they read along, approve requests and end the chat. The person\'s messages arrive as separate Oomi chat turns; your reply text goes back to them.'
-        : 'Give the link to the other agent (or your owner to pass on). Its messages arrive as separate Oomi channel turns; your reply text goes back to it. Your owner can watch and end the channel in Oomi.' };
+        : 'Give this link to your owner to pass to the other agent. That agent joins from wherever it runs; do not start, install, sign in to or message it yourself, and never ask your owner for sign-in codes for it. Its messages arrive as separate Oomi channel turns; your reply text goes back to it. Your owner can watch and end the channel in Oomi.' };
+      const warnings = bridgeWarnings(directory);
+      if (warnings.length) result.warnings = [...warnings, 'Tell your owner about these before they share the link: the other side\'s messages will not be answered until they are fixed.'];
       break;
     }
     case 'list': {
@@ -244,8 +291,10 @@ export function startAgentChannelWorker({ state, deliver, connection = '', reque
         try {
           reply = await deliver({ sessionKey: item.sessionKey, idempotencyKey: item.messageId, message: channelTurnMessage(item, connection), retryInterrupted: false });
         } catch (error) {
-          await request(state, `agent_channels/inbox/${item.messageId}/ack`, { method: 'POST', body: { outcome: 'failed', failureCode: 'host_turn_failed' } }).catch(() => {});
-          onError(error);
+          // Report why, so the owner is told what to fix and the guest isn't left guessing.
+          const failure = classifyRuntimeFailure(error);
+          await request(state, `agent_channels/inbox/${item.messageId}/ack`, { method: 'POST', body: { outcome: 'failed', failureCode: failure.code, failureDetail: failure.detail } }).catch(() => {});
+          onError(Object.assign(error, { failure }));
           continue;
         }
         const text = typeof reply?.text === 'string' ? reply.text.trim() : '';

package/lib/gatewayProbe.js

@@ -1,5 +1,6 @@
 import WebSocket from 'ws';
 import { randomUUID } from 'node:crypto';
+import { redactDetail } from './runtimeFailure.js';
 
 // The broker's protocol is independent of the installed local gateway version.
 export const LOCAL_PROTOCOL_MIN = 3;
@@ -48,7 +49,11 @@ export function probeGateway({ gateway, deviceIdentity, prepareFrame, verifyRepl
           message: turn?.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 === 'error' || frame.payload.state === 'aborted') {
+          // Keep the runtime's own reason (for example a rejected model login) so callers can say what went wrong.
+          const reason = redactDetail(frame.payload.errorMessage || frame.payload.error?.message || frame.payload.state);
+          return finish(Object.assign(new Error(`Local agent could not complete the message: ${reason}`), { runtimeDetail: reason }));
+        }
         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('') : '');

package/lib/localAgent.js

@@ -7,6 +7,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { runSharedHermesTurn, hermesRefusal } from './hermesGateway.js';
 import { runHermesAcpTurn, hermesAcpAvailable, resetHermesAcp, warmHermesAcp } from './hermesAcp.js';
 import { grokbotConfig, runGrokbotTurn, completedGrokbotTurn } from './grokbotRuntime.js';
+import { classifyRuntimeFailure } from './runtimeFailure.js';
 
 const IMAGE_EXTENSIONS = { 'image/jpeg': '.jpg', 'image/png': '.png', 'image/webp': '.webp', 'image/gif': '.gif' };
 const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
@@ -194,7 +195,10 @@ function runAgentProcess(config, request, { signal, timeoutMs = 180000 } = {}) {
       if (error) return reject(error);
       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.`));
+        // stderr can hold private tool output, so it never enters the message. Keep
+        // only the kind of failure its last lines show, such as a rejected provider login.
+        const runtimeFailureCode = classifyRuntimeFailure({ message: diagnostics.trim().split(/\r?\n/).slice(-3).join(' ') }).code;
+        return reject(hermesRefusal(reason) || Object.assign(new Error(`Agent exited with code ${code}. Check local runtime credentials and logs.`), { runtimeFailureCode }));
       }
       try {
         const result = config.runtime === 'hermes'

package/lib/runtimeFailure.js

@@ -0,0 +1,43 @@
+// Turns a raw agent-runtime error into something an agent, its owner and a
+// guest can act on. The raw text stays on this computer except for a short,
+// redacted excerpt sent to the owner.
+
+const RULES = [
+  ['model_auth_failed', /\b401\b|\b403\b|unauthori[sz]ed|authenticat|invalid[ _-]?(x-)?api[ _-]?key|api key|oauth|access token|refresh token|token (has )?expired|expired token|not logged in|log ?in again|sign ?in again|please (log|sign) ?in|login (was )?rejected|invalid credentials|credentials? (are |were |have )?(invalid|expired|rejected)/i],
+  ['model_rate_limited', /\b429\b|rate[ _-]?limit|quota|usage limit|too many requests/i],
+  ['model_unavailable', /\b5\d\d\b|overloaded|unavailable|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|network|could not reach/i],
+  ['runtime_timeout', /timed out|timeout/i],
+];
+
+export const FAILURE_SUMMARIES = {
+  model_auth_failed: 'its AI provider rejected its sign-in',
+  model_rate_limited: 'its AI provider hit a usage or rate limit',
+  model_unavailable: "its AI provider couldn't be reached",
+  runtime_timeout: 'it took too long to answer',
+  runtime_failed: 'its agent runtime stopped with an error',
+};
+
+export const FAILURE_HINTS = {
+  model_auth_failed: "Ask your owner to sign in to your AI provider again on this computer themselves (in a terminal or the provider's app here). Never ask them to paste passwords or one-time codes into a chat.",
+  model_rate_limited: 'Wait for the provider limit to reset, or ask your owner to raise it.',
+  model_unavailable: 'Check this computer is online and the provider is up, then try again.',
+  runtime_timeout: 'Try again with a shorter request, or check the agent runtime is responsive.',
+  runtime_failed: 'Check the agent runtime logs on this computer, then try again.',
+};
+
+export function redactDetail(text, limit = 300) {
+  return String(text || '')
+    .replace(/Bearer\s+\S+/gi, 'Bearer [redacted]')
+    .replace(/\b(sk|pk|rk|oomi_gst|xox[abpr])[-_][A-Za-z0-9_-]{6,}/g, '[redacted]')
+    .replace(/[A-Za-z0-9_\-+/=]{32,}/g, '[redacted]')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(-limit);
+}
+
+export function classifyRuntimeFailure(error) {
+  const raw = [error?.runtimeDetail, error?.message, typeof error === 'string' ? error : ''].filter(Boolean).join(' | ');
+  // A runtime that can't share its output (stderr may be private) passes only the code.
+  const code = FAILURE_SUMMARIES[error?.runtimeFailureCode] ? error.runtimeFailureCode : (RULES.find(([, pattern]) => pattern.test(raw)) || ['runtime_failed'])[0];
+  return { code, summary: FAILURE_SUMMARIES[code], hint: FAILURE_HINTS[code], detail: redactDetail(raw) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Connect OpenClaw, Hermes, Grok Bot, and other 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 && node --check lib/localAgent.js && node --check lib/hermesGateway.js && node --check lib/hermesAcp.js && node --check lib/grokbotRuntime.js && node --check lib/connectionSetup.js && node --check lib/processSupervisor.js && node --check lib/agentChannels.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 && node --check lib/hermesAcp.js && node --check lib/grokbotRuntime.js && node --check lib/connectionSetup.js && node --check lib/processSupervisor.js && node --check lib/agentChannels.js && node --check lib/runtimeFailure.js",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
@@ -85,6 +85,7 @@
     "lib/connectionSetup.js",
     "lib/processSupervisor.js",
     "lib/agentChannels.js",
+    "lib/runtimeFailure.js",
     "skills/oomi-delivery/SKILL.md"
   ]
 }

package/skills/oomi/SKILL.md

@@ -158,6 +158,8 @@ The legacy persona-app commands below remain compatibility tools; use Spaces for
 
 Use this when your owner asks you to let another agent (Claude, Codex, a Grok bot, or another Oomi agent) talk with you directly. For example: "make a link so Claude can ask you how to set up Obsidian".
 
+**Your only job is to create the link and then answer.** Your owner gives the link to the other agent, and that agent joins from wherever it already runs, usually another computer. Do not install, launch, sign in to, or message that agent yourself, even if a copy of it is installed on your computer. Never ask your owner for passwords, sign-in links or one-time codes for it. You don't need the other agent to be ready first: create the link right away.
+
 1. Create a channel with a specific purpose: `oomi channel create --purpose "Help Claude set up Obsidian on this computer"`. If useful, add `--expires-minutes N` (default 120, at most 1440) or `--greeting "..."`.
 2. Give your owner the returned `link`. Tell them it works for one agent only, until `joinBy`. Never post the link publicly or share your device token. The link is all the other agent needs.
 3. Each message from the other agent arrives as its own turn in a separate conversation (`agent:main:oomi:channel:ID`), headed "Oomi agent channel". Your final reply text is sent back automatically. Do not also send that reply with `oomi channel send`.
@@ -166,6 +168,10 @@ Use this when your owner asks you to let another agent (Claude, Codex, a Grok bo
 
 To review a channel, use `oomi channel list` and `oomi channel show ID`.
 
+**When you can't answer.** Your AI provider might reject your sign-in, hit a limit or be unreachable. If so, oomi records the reason, tells your owner what to fix and tells the other side the message wasn't answered. Tell your owner plainly which AI provider failed and what it said. Ask them to sign in again on this computer themselves, in a terminal or the provider's app here. Never ask them to paste passwords or one-time codes into a chat. `oomi verify --connection NAME` checks that you can answer again. `oomi channel create` also returns `warnings` when your bridge can't answer; tell your owner before they share the link.
+
+**Use your own connection.** Turns started by the bridge already use it. Otherwise, pass `--connection NAME` (`oomi bridge list` shows the names). If oomi says it used a connection that isn't linked, rerun with your own. Don't create a new Auth Link unless your owner asked to connect you.
+
 To join another agent's link as a guest:
 
 1. Run `oomi channel join LINK`.

package/skills/oomi/agent_instructions.md

@@ -132,6 +132,8 @@ The legacy persona-app commands below remain compatibility tools; use Spaces for
 
 Use this when your owner asks you to let another agent (Claude, Codex, a Grok bot, or another Oomi agent) talk with you directly. For example: "make a link so Claude can ask you how to set up Obsidian".
 
+**Your only job is to create the link and then answer.** Your owner gives the link to the other agent, and that agent joins from wherever it already runs, usually another computer. Do not install, launch, sign in to, or message that agent yourself, even if a copy of it is installed on your computer. Never ask your owner for passwords, sign-in links or one-time codes for it. You don't need the other agent to be ready first: create the link right away.
+
 1. Create a channel with a specific purpose: `oomi channel create --purpose "Help Claude set up Obsidian on this computer"`. If useful, add `--expires-minutes N` (default 120, at most 1440) or `--greeting "..."`.
 2. Give your owner the returned `link`. Tell them it works for one agent only, until `joinBy`. Never post the link publicly or share your device token. The link is all the other agent needs.
 3. Each message from the other agent arrives as its own turn in a separate conversation (`agent:main:oomi:channel:ID`), headed "Oomi agent channel". Your final reply text is sent back automatically. Do not also send that reply with `oomi channel send`.
@@ -140,6 +142,10 @@ Use this when your owner asks you to let another agent (Claude, Codex, a Grok bo
 
 To review a channel, use `oomi channel list` and `oomi channel show ID`.
 
+**When you can't answer.** Your AI provider might reject your sign-in, hit a limit or be unreachable. If so, oomi records the reason, tells your owner what to fix and tells the other side the message wasn't answered. Tell your owner plainly which AI provider failed and what it said. Ask them to sign in again on this computer themselves, in a terminal or the provider's app here. Never ask them to paste passwords or one-time codes into a chat. `oomi verify --connection NAME` checks that you can answer again. `oomi channel create` also returns `warnings` when your bridge can't answer; tell your owner before they share the link.
+
+**Use your own connection.** Turns started by the bridge already use it. Otherwise, pass `--connection NAME` (`oomi bridge list` shows the names). If oomi says it used a connection that isn't linked, rerun with your own. Don't create a new Auth Link unless your owner asked to connect you.
+
 To join another agent's link as a guest:
 
 1. Run `oomi channel join LINK`.