total-recall-brain 3.18.2 → 3.19.0

package/src/core/config.mjs

@@ -48,6 +48,7 @@ const configSchema = z.object({
   cliModel: z.string().optional(),
   cliTimeout: z.preprocess((val) => val === undefined || val === '' ? 300 : parseInt(String(val), 10), z.number().int().default(300)),
   googleApiKey: z.string().optional(),
+  openRouterApiKey: z.string().optional(),
   embedModel: z.string().default('gemini-embedding-2'),
   searxngBaseUrl: z.string().optional(),
   braveApiKey: z.string().optional(),
@@ -151,10 +152,13 @@ try {
         const isConfigPath = p.includes(path.join('config', 'secrets.enc'));
         const brainDir = isConfigPath ? path.dirname(path.dirname(p)) : path.dirname(p);
         const parsed = loadSecretsSync(brainDir);
-        if (Object.keys(parsed).length > 0) {
-          secrets = parsed;
-          break; // Found valid secrets!
-        }
+        // Merge (don't stop at the first non-empty file): an earlier, sparser
+        // store (e.g. the global ~/.agent/secrets.enc root) was previously
+        // short-circuiting the search and silently hiding real secrets that
+        // only existed in a later, richer store (e.g. the total-recall
+        // skill's own config/secrets.enc). Earlier candidates still win on
+        // key collisions — this only fills in keys the earlier ones lack.
+        secrets = { ...parsed, ...secrets };
       } catch {}
     }
   }
@@ -178,6 +182,7 @@ const rawConfig = {
   cliModel: process.env.TR_CLI_MODEL,
   cliTimeout: process.env.TR_CLI_TIMEOUT,
   googleApiKey: process.env.GOOGLE_API_KEY || secrets.google_api_key,
+  openRouterApiKey: process.env.OPENROUTER_API_KEY || secrets.openrouter_api_key || secrets.OPENROUTER_API_KEY,
   embedModel: process.env.TR_EMBED_MODEL,
   searxngBaseUrl: process.env.SEARXNG_BASE_URL,
   braveApiKey: process.env.BRAVE_SEARCH_API_KEY || process.env.BRAVE_API_KEY || secrets.brave_api_key,
@@ -225,6 +230,7 @@ export const {
   cliModel,
   cliTimeout,
   googleApiKey,
+  openRouterApiKey,
   embedModel,
   searxngBaseUrl,
   braveApiKey,

package/src/core/daemon-loop.mjs

@@ -31,7 +31,8 @@ const DERIVED_DIR = path.join(BRAIN_DIR, 'memory-derived');
 const CONFLICTS_DIR = path.join(BRAIN_DIR, 'memory-inbox', 'conflicts');
 const SESSIONS_DIR = path.join(BRAIN_DIR, 'sessions');
 const QUEUE_DIR = path.join(BRAIN_DIR, 'scheduler', 'queue');
-const INSTRUCTIONS_FILE = path.join(BRAIN_DIR, 'INSTRUCTIONS.md');
+// Surface shims resolve from the agent root (.agent/), not brainDir (…/skills/total-recall/)
+const INSTRUCTIONS_FILE = path.join(AGENT_DIR, 'INSTRUCTIONS.md');
 
 // How often to recompile surfaces (every N task ticks)
 const RECOMPILE_EVERY_N_TASKS = 20;
@@ -469,19 +470,28 @@ async function main() {
             status: result.success ? 'pending' : 'failed',
             notes: result.output ? `Phase output: ${result.output}` : (result.error || null),
           };
-          if (result.factSlug) {
+          if (result.factSlug && result.factSlug !== 'pending') {
             patch.node_slug = result.factSlug;
           }
+          const nodeSlug = patch.node_slug || task._node_slug;
           if (result.skippedLLM) {
             patch.status = 'pending';
           } else if (result.success) {
+            // Never advance past acquisition without a real memory/draft node
             if (task._research_phase === 'acquisition' && !result.factSlug) {
               patch.status = 'failed';
-              patch.notes = 'No insights found during acquisition.';
+              patch.notes =
+                result.error ||
+                'No insights found during acquisition (no web results / synthesis failed).';
             } else if (task._research_phase === 'acquisition') {
               patch.status = 'pending';
               patch.research_phase = 'deliberation';
-              patch.completed_at = new Date().toISOString();
+              patch.completed_at = null;
+            } else if (!nodeSlug || nodeSlug === 'pending') {
+              // Later phase without content → force back to acquisition
+              patch.status = 'pending';
+              patch.research_phase = 'acquisition';
+              patch.notes = `Phase ${task._research_phase} had no node_slug — re-running acquisition.`;
             } else if (task._research_phase === 'deliberation') {
               patch.status = 'pending';
               patch.research_phase = 'improvement';
@@ -492,8 +502,25 @@ async function main() {
               patch.status = 'pending';
               patch.research_phase = 'expansion';
             } else if (task._research_phase === 'expansion') {
-              patch.status = 'done';
-              patch.completed_at = new Date().toISOString();
+              // Only mark done when we still have a real node
+              if (nodeSlug && nodeSlug !== 'pending') {
+                patch.status = 'done';
+                patch.node_slug = nodeSlug;
+                patch.completed_at = new Date().toISOString();
+              } else {
+                patch.status = 'failed';
+                patch.notes = 'Expansion finished without a research memory node.';
+              }
+            }
+          } else {
+            // Failure on later phase: if no node, reset to acquisition for retry
+            if (
+              (!task._node_slug || task._node_slug === 'pending') &&
+              task._research_phase !== 'acquisition'
+            ) {
+              patch.status = 'pending';
+              patch.research_phase = 'acquisition';
+              patch.notes = `Reset to acquisition after ${task._research_phase} failure: ${result.error || 'unknown'}`;
             }
           }
           updateQueueItem(task._research_id, patch);

package/src/core/embeddings.mjs

@@ -20,7 +20,7 @@ import {
   getVssLoadablePath,
 } from 'sqlite-vss';
 
-import { googleApiKey, embedModel, brainDir as defaultBrainDir } from './config.mjs';
+import { googleApiKey, openRouterApiKey, embedModel, brainDir as defaultBrainDir } from './config.mjs';
 import { logger } from './logger.mjs';
 
 const DEFAULT_EMBED_MODEL = embedModel;
@@ -34,6 +34,10 @@ function resolveOpenAiApiKey() {
   return process.env.OPENAI_API_KEY || null;
 }
 
+function resolveOpenRouterApiKey() {
+  return openRouterApiKey || process.env.OPENROUTER_API_KEY || null;
+}
+
 let dbInstance = null;
 let currentDbPath = null;
 /** @type {WeakMap<object, boolean>} */
@@ -227,6 +231,37 @@ async function getGoogleEmbedding(text, model) {
   return data.embedding.values;
 }
 
+async function getOpenRouterEmbedding(text, model = 'openai/text-embedding-3-small') {
+  const openRouterKey = resolveOpenRouterApiKey();
+  if (!openRouterKey) {
+    throw new Error('OPENROUTER_API_KEY not set. Cannot generate embeddings.');
+  }
+
+  const res = await throttledFetch('https://openrouter.ai/api/v1/embeddings', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${openRouterKey}`,
+    },
+    // Request 768 dims to match the existing vault vss0(embedding(768)) schema
+    // and stay comparable against previously-stored Google embeddings.
+    body: JSON.stringify({ model, input: text, dimensions: 768 }),
+    signal: AbortSignal.timeout(30000),
+  }, 20000);
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`OpenRouter embedding API error ${res.status}: ${body || 'no response body'}`);
+  }
+
+  const data = await res.json();
+  if (!data.data?.[0]?.embedding) {
+    throw new Error('OpenRouter returned no embedding vector');
+  }
+
+  return data.data[0].embedding;
+}
+
 async function getOpenAIEmbedding(text, model = 'text-embedding-3-small') {
   const openaiKey = resolveOpenAiApiKey();
   if (!openaiKey) {
@@ -258,11 +293,24 @@ async function getOpenAIEmbedding(text, model = 'text-embedding-3-small') {
 
 export async function getEmbedding(text, _unused, model = DEFAULT_EMBED_MODEL) {
   const input = String(text).slice(0, 8000);
+  const openRouterKey = resolveOpenRouterApiKey();
   const googleKey = resolveGoogleApiKey();
   const openaiKey = resolveOpenAiApiKey();
 
   let embedding;
-  if (googleKey) {
+
+  // OpenRouter first: standing preference (Gemini's budget is exhausted, so
+  // Google is a near-guaranteed slow failure right now — trying it first just
+  // taxes every call with a ~15-20s timeout before falling through).
+  if (openRouterKey) {
+    try {
+      embedding = await getOpenRouterEmbedding(input);
+    } catch (err) {
+      logger.debug('embeddings: OpenRouter failed, trying Google fallback', { err: err.message });
+    }
+  }
+
+  if (!embedding && googleKey) {
     try {
       embedding = await getGoogleEmbedding(input, model);
     } catch (err) {
@@ -280,7 +328,7 @@ export async function getEmbedding(text, _unused, model = DEFAULT_EMBED_MODEL) {
   }
 
   if (!embedding) {
-    throw new Error('No embedding provider available. Set GOOGLE_API_KEY or OPENAI_API_KEY.');
+    throw new Error('No embedding provider available. Set OPENROUTER_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY.');
   }
 
   return embedding;

package/src/core/memory-title.mjs

@@ -0,0 +1,70 @@
+/**
+ * Memory title helpers — provenance belongs in source/tags, not a title prefix.
+ */
+
+const SELF_CAPTURED_PREFIX_RE = /^Self-captured memory:\s*/i;
+
+/**
+ * Strip legacy auto-title prefix if present.
+ * @param {string} title
+ * @returns {string}
+ */
+export function stripSelfCapturedTitlePrefix(title) {
+  return String(title || '').replace(SELF_CAPTURED_PREFIX_RE, '').trim();
+}
+
+/**
+ * True when title is the old auto-generated echo of the body.
+ * @param {string} title
+ * @param {string} [body]
+ */
+export function isSelfCapturedEchoTitle(title, body = '') {
+  const raw = String(title || '').trim();
+  if (SELF_CAPTURED_PREFIX_RE.test(raw)) return true;
+  const stripped = stripSelfCapturedTitlePrefix(raw);
+  const text = String(body || '').replace(/\s+/g, ' ').trim();
+  if (!stripped || !text) return false;
+  const head = stripped.replace(/\.\.\.$/, '').trim().toLowerCase();
+  if (head.length < 12) return false;
+  return text.toLowerCase().startsWith(head.slice(0, Math.min(40, head.length)));
+}
+
+/**
+ * Build a short human title from body content (no provenance prefix).
+ * Uses first sentence when reasonable, else first ~100 chars.
+ * @param {string} body
+ * @returns {string}
+ */
+export function defaultTitleFromBody(body) {
+  const oneLine = String(body || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!oneLine) return 'Untitled memory';
+
+  // Prefer first sentence
+  const m = oneLine.match(/^(.{12,}?[.!?])(\s|$)/);
+  let candidate = m ? m[1].trim() : oneLine;
+
+  // Avoid absurdly long single-sentence titles
+  if (candidate.length > 100) {
+    candidate = candidate.slice(0, 97).replace(/\s+\S*$/, '').trim() + '...';
+  }
+  return candidate || oneLine.slice(0, 100);
+}
+
+/**
+ * Normalize an existing title that may carry the legacy prefix.
+ * If after strip the title is empty or still an echo of body, rebuild from body.
+ * @param {string} title
+ * @param {string} body
+ * @returns {string}
+ */
+export function normalizeMemoryTitle(title, body) {
+  const stripped = stripSelfCapturedTitlePrefix(title);
+  if (!stripped) return defaultTitleFromBody(body);
+  if (isSelfCapturedEchoTitle(title, body) || isSelfCapturedEchoTitle(stripped, body)) {
+    // Prefer full first sentence from body over truncated echo
+    return defaultTitleFromBody(body);
+  }
+  return stripped;
+}

package/src/core/notifications.mjs

@@ -1,77 +1,247 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import crypto from 'node:crypto';
 import { logger } from './logger.mjs';
+import { findVfsDocumentByPath, listVfsDocumentsUnder } from './vfs-documents.mjs';
+import {
+  appendVfsEvent,
+  deleteVfsDocument,
+  listVfsEvents,
+  writeVfsDocument,
+} from './ssss-operation-service.mjs';
 
 const execFileAsync = promisify(execFile);
 
+/** Supported mesh / system alert events (Agent Rules / dashboard selector). */
+export const NOTIFICATION_EVENTS = new Set([
+  'node_offline',
+  'leader_change',
+  'webhook_failed',
+  'secret_sync_failed',
+  'daemon_error',
+  'research_complete',
+  'test',
+]);
+
+export const NOTIFICATION_CHANNELS = new Set(['desktop', 'webhook', 'email']);
+export const NOTIFICATION_PRIORITIES = new Set(['critical', 'high', 'low']);
+
+const RULES_PREFIX = 'system/notification-rules';
+const HISTORY_WORKSPACE = 'notifications';
+const MAX_HISTORY = 100;
+
+function rulePath(id) {
+  return `${RULES_PREFIX}/${id}.md`;
+}
+
+function eventOpts(intent) {
+  return {
+    actorRole: 'system',
+    intent,
+    workspaceId: HISTORY_WORKSPACE,
+  };
+}
+
 /**
  * Sends a macOS desktop notification using terminal-notifier if available,
  * falling back to osascript.
  *
- * @param {string} title - The notification title
- * @param {string} message - The notification message content
- * @param {object} [options] - Additional parameters
- * @param {string} [options.open] - Absolute path or URL to open on clicking "Open" or "Show"
- * @param {string} [options.sound] - macOS sound name (e.g., 'Glass', 'Hero', 'Sosumi', 'default')
- * @param {string} [options.subtitle] - Subtitle text to show
- * @param {string} [options.group] - Group ID to allow notification replacement rather than stacking
+ * @param {string} title
+ * @param {string} message
+ * @param {object} [options]
+ * @returns {Promise<{ delivered: boolean, channel: string, error?: string }>}
  */
 export async function sendSystemNotification(title, message, options = {}) {
-  // Bypassed in tests
   const isTest = process.env.VITEST || process.env._TR_TEST_AGENT_DIR || process.env.NODE_ENV === 'test';
   if (isTest) {
     logger.debug('notifications: bypassing system notification in test environment');
-    return;
+    return { delivered: true, channel: 'desktop', bypassed: true };
   }
 
   const {
     open,
     sound = 'default',
     subtitle = 'Total Recall',
-    group = 'total-recall-system'
+    group = 'total-recall-system',
   } = options;
 
-  // Sanitize inputs to prevent unexpected arguments/escaping issues
   const cleanMessage = String(message).replace(/[^ -~]/g, '').replace(/["'`$\\]/g, '').slice(0, 200);
   const cleanTitle = String(title).replace(/[^ -~]/g, '').replace(/["'`$\\]/g, '').slice(0, 100);
-  const cleanSubtitle = subtitle ? String(subtitle).replace(/[^ -~]/g, '').replace(/["'`$\\]/g, '').slice(0, 100) : '';
+  const cleanSubtitle = subtitle
+    ? String(subtitle).replace(/[^ -~]/g, '').replace(/["'`$\\]/g, '').slice(0, 100)
+    : '';
 
   try {
-    // 1. Try terminal-notifier first (supports click actions, custom sounds, subtitles, grouping)
-    const args = [
-      '-title', cleanTitle,
-      '-message', cleanMessage,
-      '-group', group,
-    ];
-    if (cleanSubtitle) {
-      args.push('-subtitle', cleanSubtitle);
-    }
+    const args = ['-title', cleanTitle, '-message', cleanMessage, '-group', group];
+    if (cleanSubtitle) args.push('-subtitle', cleanSubtitle);
     if (open) {
-      // Ensure file url is correct format or HTTP(S) URL
-      const openTarget = (open.startsWith('/') || open.startsWith('~')) ? `file://${open}` : open;
-      args.push('-open', openTarget);
-      args.push('-actions', 'Open');
-    }
-    if (sound && sound !== 'default') {
-      args.push('-sound', sound);
+      const openTarget = open.startsWith('/') || open.startsWith('~') ? `file://${open}` : open;
+      args.push('-open', openTarget, '-actions', 'Open');
     }
+    if (sound && sound !== 'default') args.push('-sound', sound);
 
     await execFileAsync('terminal-notifier', args, { timeout: 3000 });
-    logger.debug('notifications: successfully sent notification via terminal-notifier', { title, message });
-  } catch (err) {
-    // 2. Fall back to plain AppleScript display notification if terminal-notifier fails
+    logger.debug('notifications: sent via terminal-notifier', { title });
+    return { delivered: true, channel: 'desktop' };
+  } catch {
     try {
       const appleScriptParts = [
         `display notification "${cleanMessage.replace(/"/g, '\\"')}"`,
-        `with title "${cleanTitle.replace(/"/g, '\\"')}"`
+        `with title "${cleanTitle.replace(/"/g, '\\"')}"`,
       ];
       if (sound && sound !== 'default') {
         appleScriptParts.push(`sound name "${sound}"`);
       }
       await execFileAsync('osascript', ['-e', appleScriptParts.join(' ')], { timeout: 3000 });
-      logger.debug('notifications: successfully sent fallback osascript notification', { title, message });
+      logger.debug('notifications: sent via osascript', { title });
+      return { delivered: true, channel: 'desktop' };
     } catch (fallbackErr) {
-      logger.debug('notifications: both terminal-notifier and osascript failed', { err: fallbackErr.message });
+      logger.debug('notifications: desktop delivery failed', { err: fallbackErr.message });
+      return { delivered: false, channel: 'desktop', error: fallbackErr.message };
     }
   }
 }
+
+function publicRule(doc) {
+  const fm = doc.frontmatter || doc;
+  return {
+    id: String(fm.id || doc.vfs_path?.replace(/^.*\//, '').replace(/\.md$/, '') || ''),
+    event: String(fm.event || ''),
+    channel: String(fm.channel || 'desktop'),
+    priority: String(fm.priority || 'high'),
+    enabled: fm.enabled !== false && fm.enabled !== 'false',
+    quietHours: fm.quietHours === true || fm.quietHours === 'true',
+  };
+}
+
+export function listNotificationRules() {
+  return listVfsDocumentsUnder(RULES_PREFIX)
+    .filter((doc) => (doc.type || doc.frontmatter?.type) === 'notification_rule' || doc.event || doc.frontmatter?.event)
+    .map(publicRule)
+    .filter((r) => r.id && r.event);
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.event
+ * @param {string} input.channel
+ * @param {string} input.priority
+ * @param {boolean} [input.enabled]
+ * @param {boolean} [input.quietHours]
+ */
+export async function createNotificationRule(input = {}) {
+  const event = String(input.event || '').trim();
+  const channel = String(input.channel || 'desktop').trim();
+  const priority = String(input.priority || 'high').trim();
+  if (!NOTIFICATION_EVENTS.has(event) || event === 'test') {
+    throw Object.assign(new Error(`Unsupported event: ${event}`), { status: 400 });
+  }
+  if (!NOTIFICATION_CHANNELS.has(channel)) {
+    throw Object.assign(new Error(`Unsupported channel: ${channel}`), { status: 400 });
+  }
+  if (!NOTIFICATION_PRIORITIES.has(priority)) {
+    throw Object.assign(new Error(`Unsupported priority: ${priority}`), { status: 400 });
+  }
+
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+  const title = `Notify: ${event} → ${channel}`;
+  const description = `Alert on ${event} via ${channel} (${priority})`;
+  const frontmatter = {
+    type: 'notification_rule',
+    title,
+    description,
+    timestamp: now,
+    id,
+    event,
+    channel,
+    priority,
+    enabled: input.enabled !== false,
+    quietHours: !!input.quietHours,
+    created: now,
+    updated: now,
+  };
+
+  await writeVfsDocument(rulePath(id), frontmatter, description, {
+    actorRole: 'admin',
+    intent: 'Create notification rule',
+  });
+
+  return publicRule({ frontmatter });
+}
+
+export async function deleteNotificationRule(id) {
+  const ruleId = String(id || '').trim();
+  if (!ruleId) throw Object.assign(new Error('Rule id is required'), { status: 400 });
+  const path = rulePath(ruleId);
+  const existing = findVfsDocumentByPath(path);
+  if (!existing) throw Object.assign(new Error('Notification rule not found'), { status: 404 });
+  await deleteVfsDocument(path, {
+    actorRole: 'admin',
+    intent: 'Delete notification rule',
+  });
+  return { success: true, id: ruleId };
+}
+
+/**
+ * @param {object} entry
+ * @param {string} entry.title
+ * @param {string} entry.message
+ * @param {string} entry.channel
+ * @param {'delivered'|'failed'} entry.status
+ */
+export async function recordNotificationDelivery(entry) {
+  const id = crypto.randomUUID();
+  const timestamp = new Date().toISOString();
+  const payload = {
+    kind: 'notification_delivery',
+    id,
+    title: String(entry.title || 'Notification').slice(0, 200),
+    message: String(entry.message || '').slice(0, 1000),
+    channel: String(entry.channel || 'desktop'),
+    status: entry.status === 'failed' ? 'failed' : 'delivered',
+    timestamp,
+  };
+  await appendVfsEvent(`notifications/delivery/${id}`, payload, eventOpts('Record notification delivery'));
+  return payload;
+}
+
+export async function listNotificationHistory({ limit = MAX_HISTORY } = {}) {
+  const events = await listVfsEvents({ workspaceId: HISTORY_WORKSPACE });
+  const entries = events
+    .filter((event) => event.payload?.kind === 'notification_delivery')
+    .map((event) => {
+      const p = event.payload || {};
+      return {
+        id: p.id || event.event_id || crypto.randomUUID(),
+        title: p.title || 'Notification',
+        message: p.message || '',
+        channel: p.channel || 'desktop',
+        status: p.status === 'failed' ? 'failed' : 'delivered',
+        timestamp: p.timestamp || event.timestamp || new Date().toISOString(),
+      };
+    })
+    .sort((a, b) => String(b.timestamp).localeCompare(String(a.timestamp)));
+
+  const n = Number(limit);
+  return Number.isFinite(n) && n > 0 ? entries.slice(0, n) : entries.slice(0, MAX_HISTORY);
+}
+
+/**
+ * Deliver a test notification on the desktop channel and record history.
+ */
+export async function sendTestNotification() {
+  const title = 'Total Recall';
+  const message = 'Test notification from the dashboard';
+  const result = await sendSystemNotification(title, message, {
+    subtitle: 'Notifications',
+    group: 'total-recall-test',
+  });
+  const entry = await recordNotificationDelivery({
+    title,
+    message,
+    channel: 'desktop',
+    status: result.delivered ? 'delivered' : 'failed',
+  });
+  return { ...entry, delivery: result };
+}