oomi-ai 0.3.8 → 0.4.0

package/lib/localAgent.js

@@ -0,0 +1,234 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { createHash, randomUUID } from 'node:crypto';
+
+export function writePrivateJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+
+export function readJson(file, fallback = {}) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (err) {
+    if (err.code === 'ENOENT') return fallback;
+    throw err;
+  }
+}
+
+export function localAgentConfig(flags) {
+  const runtime = String(flags.runtime || '');
+  if (!['hermes', 'command'].includes(runtime)) throw new Error('Choose --runtime hermes or --runtime command.');
+  let command = ['hermes'];
+  if (runtime === 'command') {
+    try { command = JSON.parse(flags.command); } catch { throw new Error('--command must be a JSON argv array, e.g. ["/path/to/adapter"].'); }
+    if (!Array.isArray(command) || !command.length || command.some((arg) => typeof arg !== 'string') || !command[0]) throw new Error('--command must contain an executable and optional arguments.');
+  }
+  if (flags.resume === 'latest') throw new Error('Use an exact Hermes session ID, never latest.');
+  let profile = flags.profile || '';
+  let hermesHome;
+  if (runtime === 'hermes') {
+    const nativeHome = process.platform === 'win32' && process.env.LOCALAPPDATA
+      ? path.join(process.env.LOCALAPPDATA, 'hermes') : path.join(os.homedir(), '.hermes');
+    const configuredHome = path.resolve(flags['hermes-home'] || process.env.HERMES_HOME || nativeHome);
+    const isProfile = path.basename(path.dirname(configuredHome)) === 'profiles';
+    hermesHome = isProfile ? path.dirname(path.dirname(configuredHome)) : configuredHome;
+    if (!profile && isProfile) profile = path.basename(configuredHome);
+    if (!profile) {
+      try { profile = fs.readFileSync(path.join(hermesHome, 'active_profile'), 'utf8').trim(); }
+      catch (err) { if (err.code !== 'ENOENT') throw err; }
+    }
+    profile ||= 'default';
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(profile)) throw new Error('Specify a valid Hermes --profile.');
+  }
+  return { runtime, command, profile, hermesHome, resume: flags.resume || '', cwd: path.resolve(flags.cwd || process.cwd()) };
+}
+
+// No shell interpolation. Message bodies travel over stdin, never as executable code.
+export function runLocalAgent(config, request, { signal, timeoutMs = 180000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const args = config.command.slice(1);
+    if (config.runtime === 'hermes') {
+      if (config.profile) args.push('--profile', config.profile);
+      args.push('chat', '--quiet', '--query-file', '-');
+      if (request.runtimeSessionId) args.push('--resume', request.runtimeSessionId);
+    }
+    const child = spawn(config.command[0], args, { env: config.hermesHome ? { ...process.env, HERMES_HOME: config.hermesHome } : process.env, cwd: config.cwd, shell: false, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] });
+    let output = '';
+    let diagnostics = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    let bytes = 0;
+    let error;
+    const terminate = (signal) => {
+      try {
+        if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal);
+        else child.kill(signal);
+      } catch { /* The child already exited. */ }
+    };
+    const kill = (reason) => {
+      if (error) return;
+      error = reason;
+      terminate('SIGTERM');
+      killer = setTimeout(() => terminate('SIGKILL'), 1000);
+      killer.unref();
+    };
+    let killer;
+    const abort = () => kill(new Error('Agent turn cancelled.'));
+    const timer = setTimeout(() => kill(new Error('Agent turn timed out.')), timeoutMs);
+    if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+    child.stdout.on('data', (data) => {
+      bytes += Buffer.byteLength(data);
+      if (bytes > 4 * 1024 * 1024) { if (!error) kill(new Error('Agent output exceeded 4 MiB.')); return; }
+      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.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.`));
+      try {
+        const result = config.runtime === 'hermes'
+          ? { text: output, sessionId: diagnostics.match(/(?:^|\n)session_id:\s*([A-Za-z0-9_-]+)\s*(?:\n|$)/)?.[1] }
+          : JSON.parse(output);
+        if (!result || (config.runtime === 'hermes' && !result.sessionId) || typeof result.text !== 'string' || !result.text.trim()) throw new Error();
+        resolve({ text: result.text.trim(), sessionId: result.session_id || result.sessionId || request.runtimeSessionId || '' });
+      } catch { reject(new Error('Agent did not return a successful final reply. Hermes must emit its quiet-mode session_id; command adapters must return {"text":"..."}.')); }
+    });
+    child.stdin.end(config.runtime === 'hermes' ? request.message : JSON.stringify(request) + '\n');
+  });
+}
+
+export class LocalAgentRuntime {
+  constructor(config, directory, onHealth = () => {}) {
+    this.config = config;
+    this.directory = directory;
+    this.onHealth = onHealth;
+    this.queue = Promise.resolve();
+    this.active = new Map();
+  }
+  file(sessionKey) { return path.join(this.directory, 'conversations', createHash('sha256').update(sessionKey).digest('hex') + '.json'); }
+  history(sessionKey) { return readJson(this.file(sessionKey), { messages: [], receipts: {} }); }
+  async turn({ sessionKey, message, idempotencyKey, attachments = [] }) {
+    if (typeof sessionKey !== 'string' || !sessionKey || typeof idempotencyKey !== 'string' || !idempotencyKey || typeof message !== 'string' || !message.trim()) throw new Error('A session, message, and idempotency key are required.');
+    if (attachments.length) throw new Error('This adapter supports text messages. Attachments require a runtime adapter that supports them.');
+    const key = `${sessionKey}\0${idempotencyKey}`;
+    if (this.active.has(key)) {
+      const active = this.active.get(key);
+      if (active.message !== message) throw new Error('Idempotency key was reused for a different message.');
+      return active.promise;
+    }
+    const receiptKey = createHash('sha256').update(idempotencyKey).digest('hex');
+    const controller = new AbortController();
+    const promise = this.queue.then(async () => {
+      const state = this.history(sessionKey);
+      const previous = state.receipts[receiptKey];
+      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) 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);
+      try {
+        const result = await runLocalAgent(this.config, { sessionKey, message, idempotencyKey, history: state.messages, runtimeSessionId: state.runtimeSessionId || this.config.resume }, { signal: controller.signal });
+        state.runtimeSessionId = result.sessionId;
+        state.messages.push({ role: 'user', content: message, timestamp: Date.now() }, { role: 'assistant', content: [{ type: 'text', text: result.text }], timestamp: Date.now() });
+        state.receipts[receiptKey] = { message, result };
+        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; }
+    });
+    this.queue = promise.catch(() => {});
+    this.active.set(key, { promise, controller, sessionKey, message, runId: idempotencyKey });
+    try { return await promise; } finally { this.active.delete(key); }
+  }
+  abort(sessionKey, runId) {
+    let aborted = false;
+    for (const entry of this.active.values()) if (entry.sessionKey === sessionKey && (!runId || entry.runId === runId)) { entry.controller.abort(); aborted = true; }
+    return aborted;
+  }
+  socket() { return new LocalAgentSocket(this); }
+}
+
+class LocalAgentSocket extends EventEmitter {
+  constructor(runtime) {
+    super(); this.runtime = runtime; this.readyState = 0; this.connected = false;
+    setImmediate(() => { if (this.readyState !== 0) return; this.readyState = 1; this.emit('open'); });
+  }
+  frame(frame) { if (this.readyState === 1) this.emit('message', JSON.stringify(frame)); }
+  send(raw) {
+    // Real WebSockets deliver replies asynchronously; preserve bridge bookkeeping order.
+    setImmediate(() => {
+      try { this.handle(raw); } catch {
+        let id;
+        try { id = JSON.parse(raw).id; } catch { return; }
+        this.frame({ type: 'res', id, ok: false, error: { code: 'local_agent_error', message: 'Could not read local conversation state. Inspect this connection before retrying.' } });
+      }
+    });
+  }
+  handle(raw) {
+    if (this.readyState !== 1) return;
+    let req;
+    try { req = JSON.parse(raw); } catch { return; }
+    if (req.type !== 'req') return;
+    const reply = (payload) => this.frame({ type: 'res', id: req.id, ok: true, payload });
+    const fail = (message) => this.frame({ type: 'res', id: req.id, ok: false, error: { code: 'local_agent_error', message } });
+    const params = req.params || {};
+    if (req.method === 'connect') { this.connected = true; return reply({ type: 'hello-ok', protocol: 3, features: { methods: ['chat.send', 'chat.history', 'chat.abort'], events: ['chat'] }, snapshot: {}, policy: { tickIntervalMs: 30000 } }); }
+    if (!this.connected) return fail('Connect before sending requests.');
+    if (req.method === 'chat.history') return reply({ sessionKey: params.sessionKey, messages: this.runtime.history(params.sessionKey || '').messages.slice(-Math.min(params.limit || 200, 500)) });
+    if (req.method === 'chat.abort') return reply({ aborted: this.runtime.abort(params.sessionKey, params.runId) });
+    if (req.method !== 'chat.send') return fail(`Method ${req.method} is not supported by this agent adapter.`);
+    const runId = params.idempotencyKey || req.id || randomUUID();
+    reply({ runId, status: 'started' });
+    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 } });
+    });
+  }
+  close(code = 1000, reason = '') { if (this.readyState === 3) return; this.readyState = 3; this.emit('close', code, reason); }
+}
+
+export function startChannelWorker(state, runtime) {
+  let stopped = false;
+  let timer;
+  const post = async (action, body) => {
+    const response = await fetch(`${state.brokerHttp.replace(/\/$/, '')}/v1/channel/plugin/${action}`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${state.deviceToken}` },
+      body: JSON.stringify(body), signal: AbortSignal.timeout(15000),
+    });
+    if (!response.ok) throw new Error(`Oomi message delivery failed (${response.status}).`);
+    return response.json();
+  };
+  const poll = async () => {
+    try {
+      const { messages = [] } = await post('poll', { limit: 1 });
+      for (const message of messages) {
+        let result;
+        try {
+          result = await runtime.turn({ sessionKey: message.sessionKey, message: message.content, idempotencyKey: message.messageId });
+        } catch {
+          await post('acks', { messageId: message.messageId, outcome: 'failed', failureCode: 'local_agent_failed' });
+          continue;
+        }
+        // Persist the reply before acknowledging delivery. Cached receipts allow a safe
+        // retry after a network failure without repeating agent actions.
+        await post('messages', { messageId: `reply_${message.messageId}`, conversationKey: message.conversationKey, userId: message.userId, sessionKey: message.sessionKey, content: result.text, correlationId: message.correlationId, source: state.runtime });
+        await post('acks', { messageId: message.messageId, outcome: 'delivered' });
+      }
+    } catch (err) {
+      runtime.onHealth({ status: 'degraded', lastErrorMessage: err.message });
+    } finally { if (!stopped) timer = setTimeout(poll, 3000); }
+  };
+  timer = setTimeout(poll, 0);
+  return () => { stopped = true; clearTimeout(timer); for (const entry of runtime.active.values()) entry.controller.abort(); };
+}

package/lib/personaApiClient.js

@@ -140,12 +140,16 @@ export function createPersonaApiClient({
       });
     },
 
-    getHealthContext() {
+    getHealthContext(options = {}) {
+      const query = new URLSearchParams();
+      for (const key of ['window', 'date', 'from', 'to', 'timezone', 'shape', 'groupBy', 'cursor']) {
+        if (typeof options[key] === 'string' && options[key].trim()) query.set(key, options[key].trim());
+      }
       return getJson({
         fetchImpl,
         backendUrl: resolvedBackendUrl,
         deviceToken: resolvedDeviceToken,
-        path: '/v1/context/health',
+        path: `/v1/context/health${query.size ? `?${query}` : ''}`,
       });
     },
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oomi-ai",
-  "version": "0.3.8",
-  "description": "Managed Oomi channel, bridge, voice, and persona app API tooling for OpenClaw",
+  "version": "0.4.0",
+  "description": "Connect OpenClaw, Hermes, and other local agents to Oomi with verified runtime adapters",
   "bin": {
     "oomi": "bin/oomi-ai.js"
   },
@@ -70,6 +70,8 @@
     "README.md",
     "persona-app",
     "skills/oomi/SKILL.md",
-    "skills/oomi/agent_instructions.md"
+    "skills/oomi/agent_instructions.md",
+    "lib/gatewayProbe.js",
+    "lib/localAgent.js"
   ]
 }

package/skills/oomi/SKILL.md

@@ -1,95 +1,77 @@
 ---
 name: oomi
-description: Support Oomi OpenClaw installs, bridge health, managed chat and voice setup, persona app tools, and avatar control.
+description: Connect the current OpenClaw, Hermes, or other local agent to Oomi; verify replies and repair the selected connection.
 ---
 
-# Oomi Skill
+# Oomi Local Agent Operator Guide
 
-Use this skill when you need to:
-- connect an OpenClaw machine to Oomi
-- repair the Oomi plugin or bridge on a machine
-- inspect managed chat or voice health
-- inspect or update component-composed Oomi persona app state
-- read approved Oomi backend context such as HealthKit summaries synced by the mobile app
-- read permissioned Finance balances (no tokens, routing, or transactions)
-- control the Oomi avatar with inline tags
+Connect the agent the user is speaking to. Identify your runtime and profile first. Never choose OpenClaw merely because it is installed on the same machine as Hermes.
 
-## Primary Operator Workflow
+## Standard Connect Flow
 
-If the user wants OpenClaw connected to Oomi:
+Install or update the local package:
 
-1. For a first-time install or missing local pairing state, run the bootstrap exactly once using the requested app URL:
 ```bash
-curl -fsSL https://www.oomi.ai/install.sh | bash
+npm install -g oomi-ai@latest
 ```
-The bootstrap installs or updates `oomi-ai`, performs the one initial pair, installs the plugin, and starts the saved bridge detached. Do not pair again after it finishes.
 
-2. Print config guidance and apply the `channels.oomi.accounts.default` config:
-```bash
-oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai
-```
+Run ONE command for your runtime:
 
-3. Restart OpenClaw, then ensure the saved bridge is running:
-```bash
-oomi openclaw bridge ensure --detach
-```
-If stale:
-```bash
-oomi openclaw bridge restart --detach
-```
-On macOS, prefer supervised mode:
 ```bash
-oomi openclaw bridge service install
-```
+# OpenClaw (reuses existing default OpenClaw pairing)
+oomi connect --runtime openclaw --app-url https://www.oomi.ai
 
-4. If the Auth Link printed by bootstrap is missing or expired, create a replacement without re-pairing:
-```bash
-oomi openclaw invite --app-url https://www.oomi.ai
+# Hermes (separate connection, no OpenClaw required)
+oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
+
+# Another local agent, through its own adapter
+oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-5. If the machine is already paired, do not rerun bootstrap. Refresh the installed package and plugin without changing pairing state, then use `invite`, `bridge ensure`, or `bridge restart` as needed:
+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.
+
+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.
+
+The installer is an alternative to npm plus connect, and requires an explicit runtime:
+
 ```bash
-pnpm add -g oomi-ai@latest
-openclaw plugins install oomi-ai@latest
-oomi openclaw refresh --skip-version-check
+curl -fsSL https://www.oomi.ai/install.sh | bash -s -- --runtime hermes --name hermes
 ```
 
-If the user provides a specific app URL, substitute it in both the bootstrap URL and the `invite --app-url` command.
+## Required User-Facing Result
+
+Return the verified runtime/profile and the printed Auth Link. The human opens the link, signs in, and approves ownership. Only after a message receives a reply in Oomi can you claim end-to-end delivery works. Never expose raw tokens, pairing codes, or gateway credentials.
 
-## Health Checks
+## Repair and Reconnect
 
-Use these when chat or voice is failing:
+Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
 
 ```bash
-oomi openclaw bridge ps
-oomi openclaw bridge service status
-oomi openclaw status
-tail -f ~/.openclaw/logs/oomi-bridge-live.log
-tail -f ~/.openclaw/logs/gateway.log
-tail -f ~/.openclaw/logs/gateway.err.log
+oomi status --name hermes --json
+oomi verify --name hermes
+oomi bridge restart --name hermes --detach
+oomi invite --name hermes --app-url https://www.oomi.ai
 ```
 
-Interpret bridge states like this:
-- `starting`: booting or waiting for managed subscription
-- `connected`: ready for managed traffic
-- `reconnecting`: retry scheduled after transport failure
-- `degraded`: bridge caught a runtime fault but is still alive
-- `error`: startup or auth failure blocked operation
-- `stopped`: not running or intentionally shut down
+Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses the saved pairing and verifies the runtime again. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. A detached worker requires the computer to remain awake and does not start automatically after reboot. Configure the host's process supervisor when persistence across reboot is needed.
+
+`connected` describes the broker transport. Inspect `runtimeReady`, `verifiedAt`, and `lastReplyAt` separately. A process ID, Auth Link, or broker connection alone does not prove the agent is answering.
+
+## Other Runtime Adapter Contract
+
+`--command` is a JSON argv array, not a shell command. Write an adapter against the selected agent's documented API or noninteractive CLI. The executable reads one JSON object from stdin:
+
+```json
+{"sessionKey":"...","message":"...","idempotencyKey":"...","history":[],"runtimeSessionId":"..."}
+```
 
-## Common Failures
+It writes `{"text":"final reply","sessionId":"optional-runtime-session"}` to stdout and exits zero on success. Errors must exit nonzero; diagnostics go to stderr. Resume `runtimeSessionId`, or use `history` for stateless runtimes. Never bypass the agent's existing approval rules. The adapter supports text (including voice transcripts); attachments are rejected explicitly. A failed or interrupted action is not silently repeated. Check the agent before sending a new message after a failure.
 
-### Duplicate plugin id
-- Cause: multiple discoverable `oomi-ai` installs
-- Action: remove stale plugin copies and reinstall once
+## OpenClaw Channel Extension
 
-### `invalid handshake: first request must be connect`
-- Cause: gateway request ordering broke
-- Action: update `oomi-ai`, restart the bridge, confirm only one bridge worker exists
+Managed web text and voice connect through the local gateway. The optional OpenClaw `oomi-ai` channel plugin handles agent-initiated channel output. If you need that path, install the plugin, enable its entry in OpenClaw, apply `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai` locally, and restart OpenClaw. Never share that secret config with the user. Disabling the plugin does not explain a gateway protocol rejection.
 
-### STT works but the assistant does not reply
-- Cause: the voice turn reached Oomi, but the managed gateway or OpenClaw run failed later
-- Action: inspect `gateway.log`, `gateway.err.log`, and the session JSONL for that run
+OpenClaw gateway protocols 3 and 4 are negotiated independently of the broker. For an existing install affected by a protocol mismatch, update `oomi-ai`, then run `oomi connect --runtime openclaw --app-url https://www.oomi.ai`.
 
 ## Persona App State Tools
 
@@ -119,10 +101,13 @@ oomi context health --json
 ```
 
 Rules:
-- answer only from `healthContext.summary` and `healthContext.derived`
-- respect `healthContext.agentGuidance.canAnswerFromContext`
+- For historical questions use `oomi context health --window day|week|month|year|all|range --json`. Add `--date YYYY-MM-DD`, or `--from YYYY-MM-DD --to YYYY-MM-DD` for a range. Week is the seven days ending on the date; month/year are calendar periods.
+- Use `--shape summary|series|both` and `--group-by day|week|month|year` to fit the request. Follow `healthHistory.nextCursor` with `--cursor` and the same query. `all` covers imported history only. Missing days are unknown, never zero.
+- Answer historical questions from `healthHistory.summary` and `.series` when `.agentGuidance.canAnswerFromContext` is true. Stored history remains usable when the phone is offline or the current snapshot is stale.
+- For current questions answer from `healthContext.summary`, `.recentDays`, and `.derived`.
+- For current questions respect `healthContext.agentGuidance.canAnswerFromContext`.
 - if `healthContext.agentGuidance.recommendedCommand` is present, run it before answering current/latest health questions
-- if context is stale or needs sync, run `oomi context health sync --wait --json`; answer only after fresh context is uploaded, or tell the user the phone sync is still pending if it times out
+- For current/latest questions, if context is stale or needs sync, run `oomi context health sync --wait --json`; answer only after fresh context is uploaded, or tell the user the phone sync is still pending if it times out
 - if context is missing, denied, disabled, or unavailable, follow `healthContext.repair`
 - never present stale HealthKit values as current values
 - do not ask HealthKit directly; the Oomi mobile app syncs approved HealthKit data to the backend