onbuzz 5.0.2 → 5.1.0

package/src/interfaces/__tests__/monitorRoutes.test.js

@@ -0,0 +1,227 @@
+/**
+ * Tests for monitorRoutes — the Settings → Monitor App backend.
+ *
+ * Pure DI: route handlers are captured off a fake `app` and invoked with
+ * mock req/res; the broadcast wiring uses a real EventEmitter.
+ */
+import { describe, test, expect, jest } from '@jest/globals';
+import { EventEmitter } from 'events';
+import { registerMonitorRoutes, wireMonitorBroadcast } from '../monitorRoutes.js';
+
+function makeApp() {
+  const routes = {};
+  const app = {
+    get: (p, h) => { routes[`GET ${p}`] = h; },
+    post: (p, h) => { routes[`POST ${p}`] = h; },
+  };
+  return { app, routes };
+}
+function makeRes() {
+  return {
+    statusCode: 200, body: null,
+    status(c) { this.statusCode = c; return this; },
+    json(b) { this.body = b; return this; },
+  };
+}
+
+describe('registerMonitorRoutes — GET /api/monitor/logs', () => {
+  test('returns logs from getLogger().getRecentLogs with parsed filters', () => {
+    const getRecentLogs = jest.fn(() => [{ level: 'ERROR', message: 'x' }]);
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: (p, h) => { routes[p] = h; }, post: () => {} }, { getLogger: () => ({ getRecentLogs }) });
+    const res = makeRes();
+    routes['/api/monitor/logs']({ query: { level: 'error', agentId: 'a1', limit: '50' } }, res);
+    expect(getRecentLogs).toHaveBeenCalledWith({ level: 'error', agentId: 'a1', category: undefined, limit: 50 });
+    expect(res.body).toEqual({ logs: [{ level: 'ERROR', message: 'x' }] });
+  });
+
+  test('defaults limit to 200 when missing/invalid; caps at 1000', () => {
+    const getRecentLogs = jest.fn(() => []);
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: (p, h) => { routes[p] = h; }, post: () => {} }, { getLogger: () => ({ getRecentLogs }) });
+    routes['/api/monitor/logs']({ query: {} }, makeRes());
+    expect(getRecentLogs.mock.calls[0][0].limit).toBe(200);
+    routes['/api/monitor/logs']({ query: { limit: '999999' } }, makeRes());
+    expect(getRecentLogs.mock.calls[1][0].limit).toBe(1000);
+    routes['/api/monitor/logs']({ query: { limit: 'abc' } }, makeRes());
+    expect(getRecentLogs.mock.calls[2][0].limit).toBe(200);
+  });
+
+  test('no logger → empty logs', () => {
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: (p, h) => { routes[p] = h; }, post: () => {} }, { getLogger: () => null });
+    const res = makeRes();
+    routes['/api/monitor/logs']({ query: {} }, res);
+    expect(res.body).toEqual({ logs: [] });
+  });
+
+  test('500 when getRecentLogs throws', () => {
+    const logger = { error: jest.fn() };
+    const { routes } = makeApp();
+    registerMonitorRoutes(
+      { get: (p, h) => { routes[p] = h; }, post: () => {} },
+      { getLogger: () => ({ getRecentLogs: () => { throw new Error('boom'); } }), logger },
+    );
+    const res = makeRes();
+    routes['/api/monitor/logs']({ query: {} }, res);
+    expect(res.statusCode).toBe(500);
+    expect(res.body).toEqual({ error: 'boom' });
+    expect(logger.error).toHaveBeenCalled();
+  });
+
+  test('no-deps registrar does not throw (empty logs)', () => {
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: (p, h) => { routes[p] = h; }, post: () => {} });
+    const res = makeRes();
+    routes['/api/monitor/logs']({ query: {} }, res);
+    expect(res.body).toEqual({ logs: [] });
+  });
+
+  test('tolerates a request with no query object', () => {
+    const getRecentLogs = jest.fn(() => []);
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: (p, h) => { routes[p] = h; }, post: () => {} }, { getLogger: () => ({ getRecentLogs }) });
+    const res = makeRes();
+    routes['/api/monitor/logs']({}, res); // no .query
+    expect(res.body).toEqual({ logs: [] });
+    expect(getRecentLogs.mock.calls[0][0].limit).toBe(200);
+  });
+});
+
+describe('registerMonitorRoutes — POST /api/monitor/logs/clear', () => {
+  test('clears and returns the count', () => {
+    const clearRecentLogs = jest.fn(() => 7);
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: () => {}, post: (p, h) => { routes[p] = h; } }, { getLogger: () => ({ clearRecentLogs }) });
+    const res = makeRes();
+    routes['/api/monitor/logs/clear']({}, res);
+    expect(res.body).toEqual({ success: true, cleared: 7 });
+  });
+
+  test('no logger → cleared 0', () => {
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: () => {}, post: (p, h) => { routes[p] = h; } }, { getLogger: () => null });
+    const res = makeRes();
+    routes['/api/monitor/logs/clear']({}, res);
+    expect(res.body).toEqual({ success: true, cleared: 0 });
+  });
+
+  test('logger without clearRecentLogs → cleared 0', () => {
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: () => {}, post: (p, h) => { routes[p] = h; } }, { getLogger: () => ({}) });
+    const res = makeRes();
+    routes['/api/monitor/logs/clear']({}, res);
+    expect(res.body).toEqual({ success: true, cleared: 0 });
+  });
+
+  test('no-deps registrar clear route → cleared 0', () => {
+    const { routes } = makeApp();
+    registerMonitorRoutes({ get: () => {}, post: (p, h) => { routes[p] = h; } }); // no deps
+    const res = makeRes();
+    routes['/api/monitor/logs/clear']({}, res);
+    expect(res.body).toEqual({ success: true, cleared: 0 });
+  });
+
+  test('500 when clear throws', () => {
+    const logger = { error: jest.fn() };
+    const { routes } = makeApp();
+    registerMonitorRoutes(
+      { get: () => {}, post: (p, h) => { routes[p] = h; } },
+      { getLogger: () => ({ clearRecentLogs: () => { throw new Error('nope'); } }), logger },
+    );
+    const res = makeRes();
+    routes['/api/monitor/logs/clear']({}, res);
+    expect(res.statusCode).toBe(500);
+    expect(logger.error).toHaveBeenCalled();
+  });
+});
+
+describe('wireMonitorBroadcast', () => {
+  const flush = () => new Promise((r) => setImmediate(r));
+
+  test('does NOT broadcast synchronously (non-blocking — deferred off the log stack)', () => {
+    const logger = { logEvents: new EventEmitter() };
+    const sent = [];
+    wireMonitorBroadcast({ logger, broadcast: (m) => sent.push(m) });
+    logger.logEvents.emit('entry', { level: 'ERROR', message: 'e' });
+    expect(sent).toHaveLength(0); // nothing yet — emit returned immediately
+  });
+
+  test('pushes ERROR and WARN (deferred); ignores info/debug', async () => {
+    const logger = { logEvents: new EventEmitter() };
+    const sent = [];
+    const off = wireMonitorBroadcast({ logger, broadcast: (m) => sent.push(m) });
+
+    logger.logEvents.emit('entry', { level: 'INFO', message: 'i' }); // ignored
+    logger.logEvents.emit('entry', { level: 'ERROR', message: 'e' });
+    await flush();
+    logger.logEvents.emit('entry', { level: 'WARN', message: 'w' });
+    await flush();
+    expect(sent).toEqual([
+      { type: 'monitor:log', data: { level: 'ERROR', message: 'e' } },
+      { type: 'monitor:log', data: { level: 'WARN', message: 'w' } },
+    ]);
+
+    off();
+    logger.logEvents.emit('entry', { level: 'ERROR', message: 'after-off' });
+    await flush();
+    expect(sent).toHaveLength(2);
+  });
+
+  test('re-entrancy guard: a broadcast that re-logs a WARN does not loop', async () => {
+    const logger = { logEvents: new EventEmitter() };
+    let calls = 0;
+    // Simulate broadcastToSession logging a WARN during the broadcast (the real
+    // "🔄 no connections" path) — must NOT trigger another push.
+    wireMonitorBroadcast({
+      logger,
+      broadcast: () => { calls++; logger.logEvents.emit('entry', { level: 'WARN', message: 'no connections' }); },
+    });
+    logger.logEvents.emit('entry', { level: 'ERROR', message: 'e' });
+    await flush();
+    await flush();
+    expect(calls).toBe(1); // exactly one broadcast, no feedback loop
+  });
+
+  test('a throwing broadcast is swallowed and resets the in-flight guard', async () => {
+    const logger = { logEvents: new EventEmitter(), warn: jest.fn(), error: jest.fn() };
+    let calls = 0;
+    wireMonitorBroadcast({ logger, broadcast: () => { calls++; throw new Error('ws down'); } });
+    logger.logEvents.emit('entry', { level: 'ERROR', message: 'e1' });
+    await flush();
+    // Must NOT log through the logger (that would loop via the emitter).
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+    // Guard reset → a later entry still broadcasts.
+    logger.logEvents.emit('entry', { level: 'ERROR', message: 'e2' });
+    await flush();
+    expect(calls).toBe(2);
+  });
+
+  test('no emitter or non-function broadcast → safe no-op', () => {
+    expect(typeof wireMonitorBroadcast({ logger: {}, broadcast: () => {} })).toBe('function');
+    const logger = { logEvents: new EventEmitter() };
+    const off = wireMonitorBroadcast({ logger, broadcast: null });
+    logger.logEvents.emit('entry', { level: 'ERROR' }); // must not throw
+    expect(typeof off).toBe('function');
+  });
+
+  test('no args → safe no-op', () => {
+    expect(() => wireMonitorBroadcast()()).not.toThrow();
+  });
+
+  test('falls back to setTimeout when setImmediate is unavailable', async () => {
+    const orig = global.setImmediate;
+    global.setImmediate = undefined;
+    try {
+      const logger = { logEvents: new EventEmitter() };
+      const sent = [];
+      wireMonitorBroadcast({ logger, broadcast: (m) => sent.push(m) });
+      logger.logEvents.emit('entry', { level: 'ERROR', message: 'e' });
+      await new Promise((r) => setTimeout(r, 0));
+      expect(sent).toHaveLength(1);
+    } finally {
+      global.setImmediate = orig;
+    }
+  });
+});

package/src/interfaces/memoryStatusRoutes.js

@@ -0,0 +1,78 @@
+/**
+ * memoryStatusRoutes — the live per-agent "memory path" view.
+ *
+ * Two pure-DI pieces (so they're unit-testable without standing up the full
+ * WebServer, mirroring agentContextRoutes / marketplaceRoutes):
+ *
+ *   1. registerMemoryStatusRoute(app, deps)
+ *        GET /api/agents/:agentId/memory-status → embeddingService.getMemoryStatus
+ *        The PULL path: embeddings status + per-surface index sizes + the last
+ *        auto-recall funnel. Read only when the panel is open — no hot-path cost.
+ *
+ *   2. wireMemoryActivityBroadcast({ embeddingService, broadcast, logger })
+ *        The PUSH path: subscribe to the embedding service's per-turn recall
+ *        funnel and rebroadcast it to web-ui clients over the existing
+ *        websocket as `{ type: 'memory:recall', ... }`. Returns an unsubscribe
+ *        fn. Emits only data already computed by auto-recall — no extra work.
+ */
+
+/**
+ * @param {object} app  Express-like app with `.get(path, handler)`.
+ * @param {object} deps
+ * @param {() => (object|null)} deps.getEmbeddingService  Lazy accessor (the
+ *        service handle may be attached after route registration).
+ * @param {object} [deps.logger]
+ */
+export function registerMemoryStatusRoute(app, { getEmbeddingService, logger } = {}) {
+  app.get('/api/agents/:agentId/memory-status', async (req, res) => {
+    try {
+      const svc = typeof getEmbeddingService === 'function' ? getEmbeddingService() : null;
+      if (!svc || typeof svc.getMemoryStatus !== 'function') {
+        res.json({ embeddings: { enabled: false }, surfaces: {}, lastRecall: null });
+        return;
+      }
+      res.json(await svc.getMemoryStatus(req.params.agentId));
+    } catch (err) {
+      logger?.error?.('Failed to read memory status', { error: err?.message });
+      res.status(500).json({ error: err?.message });
+    }
+  });
+}
+
+/**
+ * Subscribe to live recall telemetry and rebroadcast to web-ui clients.
+ *
+ * @param {object} opts
+ * @param {object} opts.embeddingService  Must expose `memoryActivity` (an
+ *        EventEmitter that emits 'recall' entries).
+ * @param {(message: object) => void} opts.broadcast  Sends to connected clients.
+ * @param {object} [opts.logger]
+ * @returns {() => void} unsubscribe — no-op if wiring couldn't be established.
+ */
+/** Defer work off the current call stack (Node setImmediate; setTimeout fallback). */
+const _defer = (fn) => (typeof setImmediate === 'function' ? setImmediate(fn) : setTimeout(fn, 0));
+
+export function wireMemoryActivityBroadcast({ embeddingService, broadcast, logger } = {}) {
+  const emitter = embeddingService?.memoryActivity;
+  if (!emitter || typeof emitter.on !== 'function' || typeof broadcast !== 'function') {
+    return () => {};
+  }
+  const handler = (entry) => {
+    // DEFER off the emit stack: recordRecallActivity is called during the
+    // agent's per-turn prompt build, and broadcastToSession does synchronous
+    // websocket fan-out (plus its own logging). We never want that on the
+    // turn's critical path.
+    _defer(() => {
+      try {
+        // `{ type, data }` matches the web-ui store's websocket dispatch convention.
+        broadcast({ type: 'memory:recall', data: entry });
+      } catch (err) {
+        logger?.warn?.('Failed to broadcast memory:recall', { error: err?.message });
+      }
+    });
+  };
+  emitter.on('recall', handler);
+  return () => {
+    try { emitter.off('recall', handler); } catch { /* best-effort */ }
+  };
+}

package/src/interfaces/monitorRoutes.js

@@ -0,0 +1,93 @@
+/**
+ * monitorRoutes — the Settings → Monitor App backend.
+ *
+ * Surfaces the logger's in-memory ring buffer (logs + errors, each with
+ * timestamp, level, agent, message) to the web-ui, plus a live push of new
+ * warn/error entries. Pure-DI so it's unit-testable without the full
+ * WebServer (mirrors memoryStatusRoutes / agentContextRoutes).
+ *
+ *   registerMonitorRoutes(app, { getLogger, logger })
+ *     GET  /api/monitor/logs?level=&agentId=&category=&limit=  (PULL)
+ *     POST /api/monitor/logs/clear
+ *
+ *   wireMonitorBroadcast({ logger, broadcast })
+ *     Live PUSH of new warn/error entries over the websocket as
+ *     `{ type: 'monitor:log', data: record }`. Info/debug stay pull-only so
+ *     the socket isn't flooded with routine chatter. Returns an unsubscribe.
+ */
+
+/** Default cap so a careless `?limit=` can't ask for an unbounded payload. */
+const MAX_LIMIT = 1000;
+
+export function registerMonitorRoutes(app, { getLogger, logger } = {}) {
+  app.get('/api/monitor/logs', (req, res) => {
+    try {
+      const lg = typeof getLogger === 'function' ? getLogger() : null;
+      if (!lg || typeof lg.getRecentLogs !== 'function') {
+        res.json({ logs: [] });
+        return;
+      }
+      const { level, agentId, category } = req.query || {};
+      let limit = parseInt(req.query?.limit, 10);
+      if (!Number.isInteger(limit) || limit <= 0) limit = 200;
+      limit = Math.min(limit, MAX_LIMIT);
+      res.json({ logs: lg.getRecentLogs({ level, agentId, category, limit }) });
+    } catch (err) {
+      logger?.error?.('Failed to read monitor logs', { error: err?.message });
+      res.status(500).json({ error: err?.message });
+    }
+  });
+
+  app.post('/api/monitor/logs/clear', (req, res) => {
+    try {
+      const lg = typeof getLogger === 'function' ? getLogger() : null;
+      const cleared = lg && typeof lg.clearRecentLogs === 'function' ? lg.clearRecentLogs() : 0;
+      res.json({ success: true, cleared });
+    } catch (err) {
+      logger?.error?.('Failed to clear monitor logs', { error: err?.message });
+      res.status(500).json({ error: err?.message });
+    }
+  });
+}
+
+/** Defer work off the current call stack (Node setImmediate; setTimeout fallback). */
+const _defer = (fn) => (typeof setImmediate === 'function' ? setImmediate(fn) : setTimeout(fn, 0));
+
+export function wireMonitorBroadcast({ logger, broadcast } = {}) {
+  const emitter = logger?.logEvents;
+  if (!emitter || typeof emitter.on !== 'function' || typeof broadcast !== 'function') {
+    return () => {};
+  }
+
+  // Why this is careful: the logger emits SYNCHRONOUSLY, and the websocket
+  // broadcast itself logs (e.g. broadcastToSession warns "no connections" and
+  // info "message sent"). So a naive `broadcast()` here would (a) BLOCK the
+  // caller of logger.warn/error on websocket fan-out, and (b) INFINITELY
+  // RECURSE — the broadcast's own WARN/INFO logs re-enter this handler.
+  //
+  // Fix: DEFER the broadcast off the logging stack (non-blocking), and GUARD
+  // against re-entry while a push is in flight (breaks the feedback loop —
+  // the broadcast's own log lines are skipped; they remain in the ring buffer
+  // and are still served by the pull endpoint).
+  let inFlight = false;
+  const handler = (record) => {
+    if (record?.level !== 'ERROR' && record?.level !== 'WARN') return;
+    if (inFlight) return;
+    inFlight = true;
+    _defer(() => {
+      try {
+        broadcast({ type: 'monitor:log', data: record });
+      } catch (err) {
+        // console only — logging here would re-enter the emitter.
+        // eslint-disable-next-line no-console
+        console.error('Failed to broadcast monitor:log:', err?.message);
+      } finally {
+        inFlight = false;
+      }
+    });
+  };
+  emitter.on('entry', handler);
+  return () => {
+    try { emitter.off('entry', handler); } catch { /* best-effort */ }
+  };
+}

package/src/interfaces/webServer.js

@@ -63,6 +63,8 @@ import { FlowVersionStore } from '../core/flowVersionStore.js';
 import { registerSchedulerRoutes } from './schedulerRoutes.js';
 // Agent memory + context-snapshot routes — power the Memory tab in AgentEditModal.
 import { registerAgentContextRoutes } from './agentContextRoutes.js';
+import { registerMemoryStatusRoute } from './memoryStatusRoutes.js';
+import { registerMonitorRoutes } from './monitorRoutes.js';
 import { getMemoryService } from '../services/memoryService.js';
 
 const __filename = resolveModuleFilename(import.meta.url);
@@ -3855,6 +3857,19 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       logger: this.logger,
     });
 
+    // Live per-agent memory-path snapshot (embeddings status + index sizes +
+    // last auto-recall funnel). Thunk: embeddingService attaches post-startup.
+    registerMemoryStatusRoute(this.app, {
+      getEmbeddingService: () => this.embeddingService,
+      logger: this.logger,
+    });
+
+    // Settings → Monitor App: recent logs/errors (time + agent + level).
+    registerMonitorRoutes(this.app, {
+      getLogger: () => this.logger,
+      logger: this.logger,
+    });
+
     // ============================================
     // Artifacts API Endpoint
     // ============================================
@@ -5148,9 +5163,11 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           );
           duplicatedAgent.conversations.full.lastUpdated = new Date().toISOString();
 
-          // Save the updated state
+          // Save the updated state. (The StateManager method is
+          // persistAgentState(agent, projectDir) — `saveAgentState` never
+          // existed, which crashed duplication when keepConversation=true.)
           const projectDir = this.orchestrator.config.project?.directory || process.cwd();
-          await this.orchestrator.stateManager.saveAgentState(duplicatedAgent, projectDir);
+          await this.orchestrator.stateManager.persistAgentState(duplicatedAgent, projectDir);
         }
 
         // Broadcast agent created event via WebSocket

package/src/services/__tests__/aiService.embed.test.js

@@ -16,6 +16,7 @@
 
 import { describe, test, expect, jest, beforeEach } from '@jest/globals';
 import { default as AIService } from '../aiService.js';
+import { SHARED_MEMORY_SCOPE } from '../memoryService.js';
 
 function makeService() {
   // Bare-minimum config; aiService falls back to defaults for anything missing.
@@ -28,6 +29,7 @@ function makeStubEmbeddingService() {
     embedQuery: jest.fn(async () => new Float32Array([1, 0, 0, 0])),
     embedDocuments: jest.fn(async (texts) =>
       texts.map(() => new Float32Array([0.5, 0.5, 0, 0]))),
+    recordRecallActivity: jest.fn(),
   };
 }
 
@@ -169,4 +171,157 @@ describe('aiService — augmentSystemPrompt (auto-recall integration)', () => {
     const out = await aiService.augmentSystemPrompt('SYSTEM', 'agent-1', 'query', { threshold: 0.8 });
     expect(out).toBe('SYSTEM');
   });
+
+  test('publishes the recall funnel to embeddingService.recordRecallActivity', async () => {
+    aiService.setEmbeddingService(stub);
+    aiService._memoryIndexerForRecall = {
+      isEnabled: true,
+      search: jest.fn(async () => ({
+        enabled: true,
+        hits: [{ id: 'm1', score: 0.9, similarity: 0.9, metadata: { text: 'remembered', title: 'Note' } }],
+      })),
+    };
+    aiService._reminisceIndexerForRecall = { isEnabled: true, search: jest.fn(async () => ({ enabled: true, hits: [] })) };
+
+    await aiService.augmentSystemPrompt('SYSTEM', 'agent-1', 'tell me');
+    expect(stub.recordRecallActivity).toHaveBeenCalledTimes(1);
+    const [agentId, stats, injected] = stub.recordRecallActivity.mock.calls[0];
+    expect(agentId).toBe('agent-1');
+    expect(stats).toMatchObject({ considered: 1, passed: 1, injected: 1 });
+    expect(injected[0]).toMatchObject({ id: 'm1', title: 'Note' });
+  });
+
+  test('publishes even when nothing is injected (ran, found 0)', async () => {
+    aiService.setEmbeddingService(stub);
+    aiService._memoryIndexerForRecall = {
+      isEnabled: true,
+      search: jest.fn(async () => ({ enabled: true, hits: [{ id: 'm1', score: 0.1, similarity: 0.1, metadata: { text: 'irrelevant' } }] })),
+    };
+    aiService._reminisceIndexerForRecall = { isEnabled: true, search: jest.fn(async () => ({ enabled: true, hits: [] })) };
+
+    const out = await aiService.augmentSystemPrompt('SYSTEM', 'agent-1', 'query');
+    expect(out).toBe('SYSTEM'); // nothing appended
+    expect(stub.recordRecallActivity).toHaveBeenCalledTimes(1);
+    expect(stub.recordRecallActivity.mock.calls[0][1]).toMatchObject({ passed: 0, injected: 0 });
+  });
+
+  test('a throwing recordRecallActivity never breaks augmentation', async () => {
+    stub.recordRecallActivity = jest.fn(() => { throw new Error('telemetry boom'); });
+    aiService.setEmbeddingService(stub);
+    aiService._memoryIndexerForRecall = {
+      isEnabled: true,
+      search: jest.fn(async () => ({ enabled: true, hits: [{ id: 'm1', score: 0.9, similarity: 0.9, metadata: { text: 'remembered', title: 'N' } }] })),
+    };
+    aiService._reminisceIndexerForRecall = { isEnabled: true, search: jest.fn(async () => ({ enabled: true, hits: [] })) };
+    const out = await aiService.augmentSystemPrompt('SYSTEM', 'agent-1', 'tell me');
+    expect(out).toContain('remembered'); // augmentation still succeeded
+  });
+});
+
+describe('aiService — autoIndexReminisce (conversation auto-indexing)', () => {
+  let aiService, indexer;
+  const mkAgent = (count, n) => ({
+    id: 'a1',
+    reminisceIndexedCount: count,
+    conversations: { full: { messages: Array.from({ length: n }, (_, i) => ({ id: `m${i}` })) } },
+  });
+
+  beforeEach(() => {
+    aiService = makeService();
+    aiService.setEmbeddingService({ isEnabled: true });
+    indexer = { isEnabled: true, indexMany: jest.fn(async () => ({ indexedMessages: 1, error: undefined })) };
+    aiService._reminisceIndexerForRecall = indexer; // _buildReminisceIndexer returns the cached one
+  });
+
+  test('indexes only messages past the high-water mark and advances it', async () => {
+    const agent = mkAgent(1, 3); // m0 already indexed; m1,m2 new
+    await aiService.autoIndexReminisce(agent);
+    expect(indexer.indexMany).toHaveBeenCalledTimes(1);
+    const [agentId, msgs] = indexer.indexMany.mock.calls[0];
+    expect(agentId).toBe('a1');
+    expect(msgs.map(m => m.id)).toEqual(['m1', 'm2']);
+    expect(agent.reminisceIndexedCount).toBe(3);
+  });
+
+  test('backlog: no prior count → indexes everything once, sets the mark', async () => {
+    const agent = mkAgent(undefined, 5);
+    await aiService.autoIndexReminisce(agent);
+    expect(indexer.indexMany.mock.calls[0][1]).toHaveLength(5);
+    expect(agent.reminisceIndexedCount).toBe(5);
+  });
+
+  test('nothing new → does not call the indexer', async () => {
+    const agent = mkAgent(4, 4);
+    await aiService.autoIndexReminisce(agent);
+    expect(indexer.indexMany).not.toHaveBeenCalled();
+  });
+
+  test('history shrank (cleared) → mark resets and re-indexes from start', async () => {
+    const agent = mkAgent(10, 2); // mark beyond current length
+    await aiService.autoIndexReminisce(agent);
+    expect(indexer.indexMany.mock.calls[0][1]).toHaveLength(2);
+    expect(agent.reminisceIndexedCount).toBe(2);
+  });
+
+  test('disabled embeddings → no-op', async () => {
+    aiService.setEmbeddingService({ isEnabled: false });
+    await aiService.autoIndexReminisce(mkAgent(0, 3));
+    expect(indexer.indexMany).not.toHaveBeenCalled();
+  });
+
+  test('batch embed error → mark is NOT advanced (retries next turn)', async () => {
+    indexer.indexMany = jest.fn(async () => ({ indexedMessages: 0, failed: 3, error: 'embed down' }));
+    const agent = mkAgent(0, 3);
+    await aiService.autoIndexReminisce(agent);
+    expect(agent.reminisceIndexedCount).toBe(0); // unchanged → retries next turn
+  });
+
+  test('indexer throwing never propagates', async () => {
+    indexer.indexMany = jest.fn(async () => { throw new Error('boom'); });
+    const agent = mkAgent(0, 2);
+    await expect(aiService.autoIndexReminisce(agent)).resolves.toBeUndefined();
+    expect(agent.reminisceIndexedCount).toBe(0); // unchanged
+  });
+
+  test('empty conversation → no-op', async () => {
+    const agent = mkAgent(0, 0);
+    await aiService.autoIndexReminisce(agent);
+    expect(indexer.indexMany).not.toHaveBeenCalled();
+  });
+
+  test('reminisce indexer disabled → no-op', async () => {
+    indexer.isEnabled = false;
+    const agent = mkAgent(0, 3);
+    await aiService.autoIndexReminisce(agent);
+    expect(indexer.indexMany).not.toHaveBeenCalled();
+    expect(agent.reminisceIndexedCount).toBe(0);
+  });
+});
+
+describe('aiService — shared user-memory recall surface', () => {
+  let aiService, stub, memSearch;
+  beforeEach(() => {
+    aiService = makeService();
+    stub = makeStubEmbeddingService();
+    stub.config = { autoRecall: { enabled: true, threshold: 0.5, topK: 3, maxTokens: 400, surfaces: ['memory', 'reminisce'], sharedUserMemory: true } };
+    aiService.setEmbeddingService(stub);
+    memSearch = jest.fn(async () => ({ enabled: true, hits: [] }));
+    aiService._memoryIndexerForRecall = { isEnabled: true, search: memSearch };
+    aiService._reminisceIndexerForRecall = { isEnabled: true, search: jest.fn(async () => ({ enabled: true, hits: [] })) };
+    aiService._documentIndexerForRecall = { isEnabled: true, search: jest.fn(async () => ({ enabled: true, hits: [] })) };
+  });
+
+  test('sharedUserMemory ON → memory indexer is also searched at the shared scope', async () => {
+    await aiService.augmentSystemPrompt('SYSTEM', 'agent-1', 'whats my name?');
+    const scopes = memSearch.mock.calls.map(c => c[0]);
+    expect(scopes).toContain(SHARED_MEMORY_SCOPE); // shared-memory surface
+    expect(scopes).toContain('agent-1');           // the agent's own memory surface
+  });
+
+  test('sharedUserMemory OFF → the shared scope is NOT searched', async () => {
+    stub.config.autoRecall.sharedUserMemory = false;
+    await aiService.augmentSystemPrompt('SYSTEM', 'agent-1', 'whats my name?');
+    const scopes = memSearch.mock.calls.map(c => c[0]);
+    expect(scopes).not.toContain(SHARED_MEMORY_SCOPE);
+  });
 });