oomi-ai 0.7.1 → 0.8.0

package/lib/bridgeService.js

@@ -0,0 +1,173 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const xml = (value) => String(value).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' }[c]));
+// systemd performs specifier expansion even inside quotes; ExecStart also expands $.
+const unitString = (value, exec = false) => '"' + String(value).replace(/%/g, '%%').replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t').replace(/\$/g, exec ? '$$$$' : '$$') + '"';
+
+// These path directives consume the full value, without removing shell-style quotes.
+function unitPath(value) {
+  if (/[\\\r\n\0]/.test(value)) throw new Error('Linux service paths cannot contain backslashes or control characters.');
+  return String(value).replace(/%/g, '%%');
+}
+
+export function bridgeServiceConfig({ name = '', stateDirectory, logPath, scriptPath, nodePath = process.execPath,
+  platform = process.platform, home = os.homedir(), env = process.env, uid = process.getuid?.() } = {}) {
+  if (name && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name)) throw new Error('Invalid connection name.');
+  const label = `ai.oomi.bridge${name ? '.' + name : ''}`;
+  const directory = path.resolve(stateDirectory);
+  const environment = { OOMI_SKIP_UPDATE_CHECK: '1', OOMI_CONNECTION: name, PATH: env.PATH || '/usr/local/bin:/usr/bin:/bin',
+    // Always pin the state root. A login service must not resolve another connection from its environment.
+    OPENCLAW_HOME: path.resolve(env.OPENCLAW_HOME || path.join(home, '.openclaw')) };
+  if (name) environment.OOMI_CONNECTIONS_DIR = path.dirname(directory);
+  if (env.OPENCLAW_WORKSPACE) environment.OPENCLAW_WORKSPACE = path.resolve(env.OPENCLAW_WORKSPACE);
+  const args = [nodePath, scriptPath, ...(name ? ['bridge', 'start', '--name', name] : ['openclaw', 'bridge', 'start']), '--service-managed'];
+  return { name, label, platform, uid, directory, logPath, environment, args,
+    file: platform === 'darwin' ? path.join(home, 'Library', 'LaunchAgents', `${label}.plist`)
+      : path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'systemd', 'user', `${label}.service`),
+    target: platform === 'darwin' ? `gui/${uid}/${label}` : `${label}.service` };
+}
+
+export function renderLaunchAgent(config) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${xml(config.label)}</string>
+<key>ProgramArguments</key><array>${config.args.map((arg) => `<string>${xml(arg)}</string>`).join('')}</array>
+<key>WorkingDirectory</key><string>${xml(config.directory)}</string>
+<key>RunAtLoad</key><true/>
+<key>KeepAlive</key><true/>
+<key>ThrottleInterval</key><integer>10</integer>
+<key>EnvironmentVariables</key><dict>${Object.entries(config.environment).map(([k, v]) => `<key>${xml(k)}</key><string>${xml(v)}</string>`).join('')}</dict>
+<key>StandardOutPath</key><string>${xml(config.logPath)}</string>
+<key>StandardErrorPath</key><string>${xml(config.logPath)}</string>
+</dict></plist>
+`;
+}
+
+export function renderSystemdUnit(config) {
+  return `[Unit]
+Description=Oomi bridge ${config.name || 'default'}
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+WorkingDirectory=${unitPath(config.directory)}
+ExecStart=${config.args.map((arg) => unitString(arg, true)).join(' ')}
+${Object.entries(config.environment).map(([key, value]) => `Environment=${unitString(`${key}=${value}`)}`).join('\n')}
+Restart=always
+RestartSec=10
+TimeoutStopSec=15
+UMask=0077
+StandardOutput=append:${unitPath(config.logPath)}
+StandardError=append:${unitPath(config.logPath)}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+// No credentials, runtime commands or arbitrary environment are copied into service files.
+// Use injectable process execution so lifecycle failures can be tested without real user services.
+export function createBridgeService(config, { run = spawnSync } = {}) {
+  const mac = config.platform === 'darwin';
+  const supported = mac || config.platform === 'linux';
+  const command = mac ? 'launchctl' : 'systemctl';
+  function invoke(args, allowFailure = false) {
+    const result = run(command, mac ? args : ['--user', ...args], { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'pipe'] });
+    const code = Number.isInteger(result.status) ? result.status : 1;
+    const stdout = String(result.stdout || '').trim();
+    if (code && !allowFailure) throw new Error(`${command} ${args[0]} failed: ${String(result.stderr || result.error?.message || stdout || 'service manager unavailable').trim()}`);
+    return { code, stdout };
+  }
+  function availability() {
+    if (!supported) return { available: false, reason: 'Automatic startup supports macOS launchd and Linux systemd (including WSL with systemd). Use --no-service only with your own supervisor.' };
+    const result = invoke(mac ? ['print', `gui/${config.uid}`] : ['show-environment'], true);
+    return { available: result.code === 0, reason: result.code ? (mac ? 'A macOS login session is required for the Oomi service.' : 'The systemd user manager is unavailable. Enable systemd/user services, or use --no-service with your own supervisor.') : null };
+  }
+  function assertAvailable() { const result = availability(); if (!result.available) throw new Error(result.reason); }
+  function status() {
+    const available = availability();
+    const base = { manager: mac ? 'launchd' : config.platform === 'linux' ? 'systemd' : null,
+      connection: config.name || null, target: config.target, file: config.file, installed: supported && fs.existsSync(config.file),
+      ...available, loaded: false, running: false, enabled: false, pid: null, startsAt: mac ? 'login' : 'user-session' };
+    if (!available.available) return base;
+    if (mac) {
+      const printed = invoke(['print', config.target], true);
+      const disabled = invoke(['print-disabled', `gui/${config.uid}`], true);
+      const escapedLabel = config.label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const explicitlyDisabled = new RegExp(`"${escapedLabel}"\\s*=>\\s*(?:true|disabled)\\b`).test(disabled.stdout);
+      const pid = Number(printed.stdout.match(/\bpid\s*=\s*(\d+)/)?.[1]) || null;
+      return { ...base, loaded: printed.code === 0, running: Boolean(pid), pid,
+        enabled: base.installed && disabled.code === 0 ? !explicitlyDisabled : null };
+    }
+    const printed = invoke(['show', config.target, '--property=LoadState,ActiveState,MainPID,UnitFileState'], true);
+    const properties = Object.fromEntries(printed.stdout.split('\n').filter((line) => line.includes('=')).map((line) => { const i = line.indexOf('='); return [line.slice(0, i), line.slice(i + 1)]; }));
+    const linger = run('loginctl', ['show-user', String(config.uid), '--property=Linger', '--value'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    const persistsWithoutLogin = linger.status === 0 && String(linger.stdout).trim() === 'yes';
+    return { ...base, loaded: properties.LoadState === 'loaded', running: properties.ActiveState === 'active',
+      pid: Number(properties.MainPID) || null, enabled: properties.UnitFileState === 'enabled',
+      startsAt: persistsWithoutLogin ? 'boot' : 'user-session', persistsWithoutLogin };
+  }
+  function assertOwnership() {
+    // Prevent a custom state root with the same name from taking over another connection's service.
+    if (fs.existsSync(config.file)) {
+      const existing = fs.readFileSync(config.file, 'utf8');
+      const matches = mac ? new RegExp(`<key>WorkingDirectory</key>\\s*<string>${xml(config.directory).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}</string>`).test(existing)
+        : existing.includes(`WorkingDirectory=${unitPath(config.directory)}\n`);
+      if (!matches) throw new Error(`Service ${config.target} belongs to a different state directory. Use a different connection name.`);
+    }
+  }
+  function preflight() {
+    assertAvailable();
+    assertOwnership();
+    if (config.args[1].split(path.sep).includes('_npx')) throw new Error('Install oomi-ai globally before installing automatic startup; an npx cache is temporary.');
+    // Validate paths before pairing or stopping an already working connection.
+    if (mac) renderLaunchAgent(config); else renderSystemdUnit(config);
+  }
+  function writeDefinition() {
+    preflight();
+    fs.mkdirSync(path.dirname(config.file), { recursive: true });
+    fs.mkdirSync(config.directory, { recursive: true });
+    fs.mkdirSync(path.dirname(config.logPath), { recursive: true });
+    const content = mac ? renderLaunchAgent(config) : renderSystemdUnit(config);
+    fs.writeFileSync(config.file, content, { mode: 0o600 });
+    fs.chmodSync(config.file, 0o600);
+    if (!mac) invoke(['daemon-reload']);
+  }
+  function stop() {
+    assertAvailable();
+    assertOwnership();
+    if (mac) {
+      invoke(['disable', config.target]);
+      const current = invoke(['print', config.target], true);
+      if (!current.code) invoke(['bootout', config.target]);
+    } else if (fs.existsSync(config.file)) invoke(['disable', '--now', config.target]);
+  }
+  function start({ rewrite = false } = {}) {
+    assertAvailable();
+    assertOwnership();
+    if (!fs.existsSync(config.file)) throw new Error('Bridge service is not installed. Run oomi bridge repair for this connection.');
+    const current = status();
+    if (rewrite) { writeDefinition(); stop(); }
+    if (mac) {
+      invoke(['enable', config.target]);
+      if (!current.loaded || rewrite) invoke(['bootstrap', `gui/${config.uid}`, config.file]);
+      else if (!current.running) invoke(['kickstart', config.target]);
+    } else invoke(['enable', '--now', config.target]);
+  }
+  function install({ noStart = false } = {}) {
+    assertAvailable();
+    writeDefinition();
+    stop();
+    if (!noStart) start();
+  }
+  function uninstall() {
+    stop();
+    if (fs.existsSync(config.file)) fs.unlinkSync(config.file);
+    if (!mac) invoke(['daemon-reload']);
+  }
+  return { config, availability, preflight, status, install, start, stop, uninstall };
+}

package/lib/localAgent.js

@@ -5,6 +5,56 @@ import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { createHash, randomUUID } from 'node:crypto';
 
+const IMAGE_EXTENSIONS = { 'image/jpeg': '.jpg', 'image/png': '.png', 'image/webp': '.webp', 'image/gif': '.gif' };
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Chat photos arrive inline as base64 (the shape OpenClaw's gateway also accepts), with an
+ * optional `storagePath` in the owner's Oomi storage so the conversation can show it again
+ * later. Hermes looks at one image per query.
+ */
+export function readImageAttachments(attachments) {
+  if (!Array.isArray(attachments) || attachments.length === 0) return [];
+  if (attachments.length > 1) throw new Error('Send one photo at a time.');
+  return attachments.map((attachment) => {
+    const mimeType = String(attachment?.mimeType || '').toLowerCase();
+    if (attachment?.type !== 'image' || !IMAGE_EXTENSIONS[mimeType]) throw new Error('Only JPEG, PNG, WebP, or GIF photos can be sent.');
+    const bytes = Buffer.from(typeof attachment.content === 'string' ? attachment.content : '', 'base64');
+    if (!bytes.length) throw new Error('The photo arrived empty. Try sending it again.');
+    if (bytes.length > MAX_IMAGE_BYTES) throw new Error('That photo is too large. Photos can be up to 10 MB.');
+    const dimension = (value) => (Number.isFinite(value) && value > 0 ? Math.round(value) : undefined);
+    return {
+      mimeType,
+      bytes,
+      storagePath: typeof attachment.storagePath === 'string' && attachment.storagePath.trim() ? attachment.storagePath.trim() : undefined,
+      width: dimension(attachment.width),
+      height: dimension(attachment.height),
+    };
+  });
+}
+
+// Private files for one turn; the caller removes the folder when the turn ends.
+function writeTurnImages(images) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'oomi-turn-'));
+  fs.chmodSync(directory, 0o700);
+  const paths = images.map((image, index) => {
+    const file = path.join(directory, `photo-${index + 1}${IMAGE_EXTENSIONS[image.mimeType]}`);
+    fs.writeFileSync(file, image.bytes, { mode: 0o600 });
+    return file;
+  });
+  return { directory, paths };
+}
+
+// What the conversation remembers: the words, plus where the owner's photo is stored (never the bytes).
+function userContent(text, images) {
+  const stored = images.filter((image) => image.storagePath);
+  if (!stored.length) return text;
+  return [
+    ...(text.trim() ? [{ type: 'text', text }] : []),
+    ...stored.map(({ mimeType, storagePath, width, height }) => ({ type: 'image', mimeType, storagePath, ...(width ? { width } : {}), ...(height ? { height } : {}) })),
+  ];
+}
+
 export function writePrivateJson(file, data) {
   fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
   const temporary = `${file}.${process.pid}.tmp`;
@@ -55,8 +105,11 @@ export function runLocalAgent(config, request, { signal, timeoutMs = 180000 } =
       if (config.profile) args.push('--profile', config.profile);
       args.push('chat', '--quiet', '--query-file', '-');
       if (request.runtimeSessionId) args.push('--resume', request.runtimeSessionId);
+      if (request.imagePaths?.[0]) args.push('--image', request.imagePaths[0]);
     }
-    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'] });
+    // The agent's own `oomi` commands (notify, routines, spaces) use this connection by default.
+    const env = { ...process.env, ...(config.hermesHome ? { HERMES_HOME: config.hermesHome } : {}), ...(config.connection ? { OOMI_CONNECTION: config.connection } : {}) };
+    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 = '';
     child.stdout.setEncoding('utf8');
@@ -116,8 +169,11 @@ export class LocalAgentRuntime {
   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 = [], retryInterrupted = false }) {
-    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 images = readImageAttachments(attachments);
+    const text = typeof message === 'string' ? message : '';
+    if (typeof sessionKey !== 'string' || !sessionKey || typeof idempotencyKey !== 'string' || !idempotencyKey || (!text.trim() && !images.length)) throw new Error('A session, message, and idempotency key are required.');
+    const prompt = text.trim() ? text : 'Here is a photo.';
+    message = text;
     const key = `${sessionKey}\0${idempotencyKey}`;
     if (this.active.has(key)) {
       const active = this.active.get(key);
@@ -136,15 +192,18 @@ export class LocalAgentRuntime {
       if (controller.signal.aborted) throw new Error('Agent turn cancelled.');
       state.receipts[receiptKey] = { message, status: 'running' };
       writePrivateJson(this.file(sessionKey), state);
+      let scratch;
       try {
-        const result = await runLocalAgent(this.config, { sessionKey, message, idempotencyKey, history: state.messages, runtimeSessionId: state.runtimeSessionId || this.config.resume }, { signal: controller.signal });
+        scratch = images.length ? writeTurnImages(images) : null;
+        const result = await runLocalAgent(this.config, { sessionKey, message: prompt, idempotencyKey, history: state.messages, runtimeSessionId: state.runtimeSessionId || this.config.resume, imagePaths: scratch?.paths || [] }, { 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.messages.push({ role: 'user', content: userContent(text, images), 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; }
+      finally { if (scratch) fs.rmSync(scratch.directory, { recursive: true, force: true }); }
     });
     this.queue = promise.catch(() => {});
     this.active.set(key, { promise, controller, sessionKey, message, runId: idempotencyKey });

package/lib/objectives.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import { routineRequest } from './routines.js';
+
+export async function handleObjectivesCommand(state, action = 'list', flags = {}, positionals = [], request = routineRequest) {
+  if (!['list', 'show', 'history', 'create', 'update', 'respond'].includes(action)) throw new Error('Use objectives list, show, history, create, update, or respond.');
+  let route = 'objectives', method = 'GET', body;
+  const id = positionals[0] || flags.id;
+  if (!['list', 'create'].includes(action)) {
+    if (!/^obj_[a-f0-9]{24}$/.test(id || '')) throw new Error('Use the objective ID returned by Oomi.');
+    route += `/${id}`;
+  }
+  if (action === 'history') {
+    if (flags.before && !/^\d{4}-\d{2}-\d{2}$/.test(flags.before)) throw new Error('Use --before YYYY-MM-DD.');
+    route += `/history${flags.before ? `?before=${flags.before}` : ''}`;
+  }
+  if (['create', 'update', 'respond'].includes(action)) {
+    if (typeof flags.file !== 'string' || fs.statSync(flags.file).size > 32768) throw new Error('Use a goal JSON file under 32 KiB.');
+    body = JSON.parse(fs.readFileSync(flags.file, 'utf8'));
+    if (!body || typeof body !== 'object' || Array.isArray(body)) throw new Error('Use a JSON object.');
+    if (flags['request-id']) body.idempotencyKey = flags['request-id'];
+    if (flags.revision !== undefined) body.expectedRevision = Number(flags.revision);
+    if (flags['source-message']) body.sourceMessageId = flags['source-message'];
+    if (typeof body.idempotencyKey !== 'string' || body.idempotencyKey.length < 8) throw new Error('Include a stable idempotencyKey; retry only the identical request.');
+    if (action !== 'create' && !Number.isInteger(body.expectedRevision)) throw new Error('Read the goal and provide expectedRevision.');
+    if (action === 'respond') {
+      if (!body.periodKey || !Number.isInteger(body.expectedPeriodRevision)) throw new Error('Read the goal and include periodKey and expectedPeriodRevision.');
+      route += '/responses';
+    }
+    method = action === 'update' ? 'PATCH' : 'POST';
+  }
+  const result = await request(state, route, { method, body });
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}

package/lib/personaApiClient.js

@@ -147,7 +147,7 @@ export function createPersonaApiClient({
 
     getHealthContext(options = {}) {
       const query = new URLSearchParams();
-      for (const key of ['window', 'date', 'from', 'to', 'timezone', 'shape', 'groupBy', 'cursor']) {
+      for (const key of ['window', 'date', 'from', 'to', 'timezone', 'shape', 'groupBy', 'cursor', 'provider']) {
         if (typeof options[key] === 'string' && options[key].trim()) query.set(key, options[key].trim());
       }
       return getJson({

package/lib/routines.js

@@ -5,7 +5,7 @@ import { readJson, writePrivateJson } from './localAgent.js';
 export async function routineRequest(state, route, { method = 'GET', body, fetchImpl = fetch } = {}) {
   if (!state.deviceToken || !state.brokerHttp) throw new Error('Connect this agent to Oomi first.');
   const response = await fetchImpl(`${state.brokerHttp.replace(/\/$/, '')}/v1/${route}`, {
-    method, headers: { Authorization: `Bearer ${state.deviceToken}`, 'Content-Type': 'application/json', 'X-Oomi-Event-Delivery': 'quiet-v1' },
+    method, headers: { Authorization: `Bearer ${state.deviceToken}`, 'Content-Type': 'application/json', 'X-Oomi-Event-Delivery': 'quiet-v1', 'X-Oomi-Space-Schema': 'space.v3' },
     ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(15000),
   });
   const result = await response.json().catch(() => ({}));

package/lib/spaces.js

@@ -9,17 +9,18 @@ export async function handleSpacesCommand(state, action = 'list', flags = {}, po
     body = JSON.parse(fs.readFileSync(flags.file, 'utf8'));
     if (!body || typeof body !== 'object' || Array.isArray(body)) throw new Error('Use a JSON object.');
   }
-  if (!['list', 'catalog', 'create', 'show', 'update', 'archive', 'unarchive', 'revisions', 'restore'].includes(action)) throw new Error('Use spaces list, catalog, create, show, update, archive, unarchive, revisions, or restore.');
+  if (!['list', 'catalog', 'create', 'show', 'update', 'archive', 'unarchive', 'revisions', 'restore', 'upgrade'].includes(action)) throw new Error('Use spaces list, catalog, create, show, update, archive, unarchive, revisions, restore, or upgrade.');
   if (action === 'catalog') route += '/catalog';
   if (action === 'list' && flags.archived) route += '?archived=true';
   if (!['list', 'catalog', 'create'].includes(action)) {
     if (!/^spc_[a-f0-9]{24}$/.test(id || '')) throw new Error('Provide the Space ID returned by Oomi.');
     route += `/${id}`;
   }
-  if (['revisions', 'restore'].includes(action)) route += `/${action}`;
-  if (['create', 'update', 'archive', 'unarchive', 'restore'].includes(action)) {
-    method = ['create', 'restore'].includes(action) ? 'POST' : 'PATCH';
+  if (['revisions', 'restore', 'upgrade'].includes(action)) route += `/${action}`;
+  if (['create', 'update', 'archive', 'unarchive', 'restore', 'upgrade'].includes(action)) {
+    method = ['create', 'restore', 'upgrade'].includes(action) ? 'POST' : 'PATCH';
     body ||= {};
+    if (flags['schema-version']) body.schemaVersion = flags['schema-version'];
     if (flags.revision !== undefined) body.expectedRevision = Number(flags.revision);
     if (flags['request-id']) body.idempotencyKey = flags['request-id'];
     if (action === 'archive' || action === 'unarchive') body.archived = action === 'archive';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "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",
+    "check": "node --check bin/oomi-ai.js && node --check lib/bridgeService.js",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
@@ -75,6 +75,8 @@
     "lib/localAgent.js",
     "lib/agentIdentity.js",
     "lib/routines.js",
-    "lib/spaces.js"
+    "lib/spaces.js",
+    "lib/objectives.js",
+    "lib/bridgeService.js"
   ]
 }

package/skills/oomi/SKILL.md

@@ -37,14 +37,82 @@ Supported types and binding fields:
 - profile: heightCm, birthDate (YYYY-MM-DD), sex, activityLevel, athleteMode. Ask incrementally only when necessary; do not invent profile facts.
 - routine/streak: routineId returned by the existing routines API. The source remains that routine's real schedule and check-ins. Rendering a component does not activate a routine.
 
-Live source example: `{"id":"steps","type":"chart","title":"Steps this week","dataKey":"steps","source":{"kind":"health","metric":"activity.steps","window":"week","unit":"count"}}`. Health sources use canonical metric names from the catalog and resolve permissioned observations when opened. Body-weight unit may be kg or lb. For the user's shared scale use `source:{kind:"scale",metric:"weight",unit:"lb"}`. The scale shows received capture values; packet stability and measurement time remain unverified. No body-composition values can be inferred from weight alone. Don't present estimates as measurements.
+For connected content, use reusable named `sources` and a component's `sourceRef`. Check the live catalog for supported versions and available providers. Send `schemaVersion:"space.v2"` on creation and every edit/restore/archive to a v2 Space; flag-only commands accept `--schema-version space.v2`. Retain existing definitions when replacing the sources object. References automatically manage subscriptions; they never grant permission.
+
+Example fragment (preserve the person's existing components and targets):
+```json
+{
+  "schemaVersion": "space.v2",
+  "sources": {
+    "weight": {"kind":"observation","metric":"body.mass_kg","providers":["smart_scale","apple_health"],"operation":"latest","window":"month","unit":"lb"},
+    "workouts": {"kind":"workouts","metric":"workout","operation":"count","window":"week","minDurationMinutes":10}
+  },
+  "components": [
+    {"id":"weight","type":"metric","title":"Latest weight","dataKey":"weight","sourceRef":"weight"},
+    {"id":"weightHistory","type":"chart","title":"Weight history","dataKey":"weightHistory","sourceRef":"weight"},
+    {"id":"workouts","type":"metric","title":"Recorded workouts","dataKey":"workouts","sourceRef":"workouts"}
+  ],
+  "bindings": {}
+}
+```
+
+Display windows are day (today), week (rolling seven days), month/year (current calendar periods), or all, with an optional IANA timezone. These are not goal recurrence. Latest weight uses a real reading even outside the chart window. Body weight accepts kg/lb. Apple Health daily averages remain in legacy history; individual readings require a sync from the updated phone, and historical averages cannot recover sample times. Scale time is phone receipt time, not a verified device timestamp. Never infer body composition from weight.
+
+Use observation operation sum for activity totals, average for averages, or count/presence for evidence. Sensor workouts (kind workouts, metric workout) and user-reported Fitness completions (kind fitness, metric completion, optionally filtered by explicit actionIds) remain separate. Never add those counts and claim duplicates were removed. Missing data is unknown, not zero. observedAt and syncedAt distinguish record time from receipt; dataRevision changes do not affect the edit revision. Quiet space.data_changed events need no model wake or acknowledgment.
+
+Legacy inline health and scale sources remain readable. Legacy scale history may contain explicitly shared diagnostic captures, separately labelled and not certified weigh-ins. Use the new observation source for automatic shared readings and selectable chart periods.
 
 Removing a component keeps its binding data and revision history. Use `oomi spaces revisions ID` and `oomi spaces restore ID --file restore.json` with `{expectedRevision,restoreRevision,idempotencyKey}` to restore layout without rolling back saved values. Archive/unarchive is reversible. Spaces never execute scripts, HTML, or agent-provided code; unsupported components require an Oomi renderer update.
 
 Creating a Space does not authorize health access, identity-file backup, push messages, or schedules. For a requested routine, use the existing routine proposal/commit commands and authenticated sourceMessageId or previously granted externalInstruction permission. When the user says to revise and set it, commit all changes together; the resolved review card disappears. Don't make them repeat the instruction in the UI. The primary agent normally coordinates; specialists keep their own assigned Spaces.
 
+### Recurring goals and optional streaks (space.v3)
+
+Use the live catalog to confirm support, then `oomi objectives list` and `oomi objectives show ID` before adding another goal. Goals belong to the account and may be reused across Spaces. Keep the existing `goal` card for numeric milestones; use an `objective` component for a recurring rule. A plain checklist does not reset or create completion history.
+
+Create with `oomi objectives create --file goal.json`. Example shape only; choose dates, calendar, target and source from the user's request rather than creating this example:
+```json
+{
+  "title": "Reading practice",
+  "idempotencyKey": "unique-goal-create-request",
+  "calendar": {"period":"daily","timezone":"America/Chicago","startsOn":"YYYY-MM-DD","weekdays":[1,2,3,4,5]},
+  "definition": {"source":{"kind":"manual","unit":"chapters"},"comparison":"gte","target":1}
+}
+```
+
+Calendars support daily (optionally selected weekdays, 1=Monday), weekly (weekStartsOn defaults to Monday), monthly, and once (endsOn required). Time zone and calendar stay fixed through travel. A different calendar requires a new goal. Targets/rules/pause changes take effect next period, leaving past and current progress intact. A future one-time goal may change before starting; once started, correct its progress or create another goal.
+
+Sources may be manual, an existing routine (`{kind:"routine",routineId:"returned ID",operation:"count"}`), or a supported observation/workouts/fitness configuration without window/timezone. The calendar supplies its evaluation window. Daily weigh-in uses observation/body.mass_kg/presence/target 1; weekly recorded workouts uses workouts/workout/count and the requested target. Fitness is user-reported and remains separate from sensor workouts. Daily activity totals imported in a different time zone are unknown for this goal, not rebinned or invented. Sources need existing permission; creating goals never grants it.
+
+For either/or completion use `{kind:"any",sources:[{kind:"workouts",metric:"workout",operation:"presence"},{kind:"fitness",metric:"completion",operation:"presence"}]}` with comparison `gte` and target `1`. Use 2–5 presence sources (observation, workouts, Fitness, or an existing routine). One period counts once even if several sources match; this does not add workout counts across providers. Nested combinations and manual sources inside this rule are unsupported.
+
+Add components using the returned goal ID, preserving all other components and bindings:
+```json
+{"schemaVersion":"space.v3","expectedRevision":1,"idempotencyKey":"unique-space-update-request","components":[{"id":"practice","type":"objective","title":"Reading practice","dataKey":"practice","objectiveId":"RETURNED_OBJECTIVE_ID"},{"id":"practiceStreak","type":"streak","title":"Practice streak","dataKey":"practiceStreak","objectiveIds":["RETURNED_OBJECTIVE_ID"],"match":"all"}]}
+```
+
+Send space.v3 on every write/restore/archive of a Space containing these references. The CLI supplies the space.v3 read header; older clients show an update message and cannot discard newer definitions. Removing a card preserves the objective and history. Never save resolvedBindings back into bindings.
+
+For requested changes use `oomi objectives update ID --file change.json` with expectedRevision, stable idempotencyKey, and only the changed title/definition/reminderRoutineId. A definition is replaced as a whole: preserve the source/comparison/target/status not being changed. Set definition.status to active/paused. An optional reminderRoutineId links an existing authorized routine, creates no schedule, and automatically suppresses its reminder once the goal is complete. One routine can follow one goal. A routine-backed goal may link that same routine as its reminder, but not a different routine. Automatic reminder completion is excluded from source evidence so it cannot complete its own goal indefinitely. Create/activate any new reminder through the established routine authority flow.
+
+For a person's progress correction use `oomi objectives respond ID --file response.json` with expectedRevision, expectedPeriodRevision, periodKey (all from the latest read), action record/incomplete/skip/reset, and a stable idempotencyKey. Record also requires numeric value; optional note is at most 500 characters. Agent-recorded progress requires sourceMessageId from the authenticated Oomi owner message. The external routine permission does not authorize generic goal responses. Existing routine and Fitness actions still use their own action APIs; goals consume that evidence. Never fabricate completed actions. Corrections persist until reset (return to source data, or clear a manual entry). On uncertain failure retry the identical key/body; after a definite revision conflict read current state and make a new request.
+
+`show` contains the last 31 periods; `oomi objectives history ID [--before YYYY-MM-DD]` pages 100 older periods using nextCursor. Full stored history drives current/best streaks, not the seven visible dots. A streak can use 1–10 goals with identical recurring calendars, matching all or any. Rest, skip and pause add no success and do not break an individual streak; an open period is not missed. Skipping one grouped goal does not hide another missed goal. Missing evidence is unknown; unavailable access hides progress. Late source changes/corrections reconcile earlier periods. Existing routine-only streak cards remain compatible and retain their older history limit; migrate explicitly when requested.
+
+### Upgrade an existing Space without losing its plan
+
+Read the Space and its existing routines first. If the catalog advertises `upgrade`, use `oomi spaces upgrade ID --file upgrade.json` to apply explicit source and goal mappings atomically. Supply `expectedRevision`, a stable `idempotencyKey`, optional named `sources`, optional `sourceBindings:{"EXISTING_COMPONENT_ID":"SOURCE_NAME"}`, and an `objectives` array. Each entry requires a distinct stable `key`, `title`, `calendar`, and `definition` in the usual goal format. Optional fields:
+- `checklistItem:{componentId,itemId}` removes exactly that legacy checklist item.
+- `componentId` chooses the new goal card ID; `replaceComponent:true` explicitly replaces an existing section.
+- `reminderRoutineId` links an existing authorized reminder.
+- `streakComponentIds:["EXISTING_STREAK_ID"]` converts selected streaks to the new goal.
+
+All mappings must succeed or nothing changes. Retry the identical body/key after an uncertain response. A conflict requires a fresh read and new request key. Preserve user targets, notes, profiles, unrelated bindings and source permissions. Existing undated checklist ticks are retained in revision history, never invented as dated completions. Use this only for a requested upgrade; do not infer recurrence or health targets from vague prose. Restore an earlier layout with the existing revision API; created account goals and their history remain available.
+
 ### Health questions without oversized output
 
+The iPhone synchronizes available Apple Health history in durable pages keyed by sample UUID, then tracks additions and explicit deletions. A cursor advances only after Oomi saves the page and its affected daily totals. Interrupted imports resume on foreground or a later health update. Apple does not reveal read denials: an empty query is unknown, not zero or proof of deletion. Provider permissions and Oomi's sharing switch still apply. Physical HealthKit/background-delivery acceptance is separate from simulator and synthetic checks.
+
 For a rolling seven days: `oomi context health --window week --metric steps --json`.
 For a previous calendar week: determine dates in the user's time zone, then `oomi context health --window range --from YYYY-MM-DD --to YYYY-MM-DD --metric steps --json`.
 Use `--metric weight`, `--metric sleep`, or a canonical metric as needed. Preserve coverage, dates, units, missing days, and today's partial count. Don't label a rolling window as a calendar week. For large/raw responses use `--output /absolute/path/new-health.json`; the CLI writes private, complete JSON to a new file and prints a small receipt. Never try to parse a terminal-truncated response as if it were the original JSON. Read existing permitted history before asking the user to sync. Request a phone sync only when current data is needed; don't repeatedly poll an offline phone.
@@ -134,11 +202,17 @@ Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
 ```bash
 oomi status --name hermes --json
 oomi verify --name hermes
-oomi bridge restart --name hermes --detach
+oomi bridge repair --name hermes
 oomi invite --name hermes --app-url https://www.oomi.ai
 ```
 
-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.
+Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. 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`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
+
+Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To upgrade an existing connection on **each computer**, install `oomi-ai@latest`, then run `oomi bridge repair --name <existing-name>` (omit the name for default OpenClaw). Repair installs/updates its supervisor, preserves pairing and conversations, and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
+
+Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.
+
+For containers or an existing external supervisor, use `connect --no-service` explicitly, then configure that supervisor to run `oomi bridge start --name <name> --service-managed` in the foreground. Detached mode alone does not provide crash/login recovery. Setup fails with an actionable error when the service manager is unavailable; never claim automatic startup in that case. The phone's Reconnect button reconnects the client; it cannot wake a computer or start a missing host process.
 
 `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.
 
@@ -205,11 +279,14 @@ To reach the user on their phone when they are not in the conversation:
 oomi notify "Your 7-day plan is ready. Want to look now?" --title "Fitness" --json
 ```
 
+Add `--connection NAME` when you run it outside an Oomi conversation (for example from a scheduled job); turns Oomi starts already set `OOMI_CONNECTION`. Omit it for the default OpenClaw connection.
+
 Rules:
 - notify only for things worth interrupting the user for (a reminder they asked for, a finished task, something time-sensitive); say everything else in chat
 - keep it short and specific; the title defaults to your agent name
 - tapping it opens the Oomi app to the conversation, where the message also appears
-- messages you send on the Oomi channel already notify the phone; do not also run `oomi notify` for the same message
+- replies to the user's own Oomi messages and OpenClaw sends on the Oomi channel already notify the phone; do not also run `oomi notify` for the same message
+- anything you start on your own (a reminder, finished background work) needs `oomi notify`; Hermes agents have no other way to reach the phone
 - if `notification.status` is `skipped`, tell the user `notification.guidance` instead of retrying
 - if rate limited, wait `retryAfterSeconds` before trying again