onbuzz 5.0.2 → 5.3.0

package/src/services/__tests__/scheduleService.missedRuns.test.js

@@ -0,0 +1,186 @@
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+jest.unstable_mockModule('fs', () => ({
+  promises: {
+    readFile: jest.fn().mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' })),
+    writeFile: jest.fn().mockResolvedValue(undefined),
+    mkdir: jest.fn().mockResolvedValue(undefined),
+  },
+}));
+jest.unstable_mockModule('child_process', () => ({ execSync: jest.fn().mockReturnValue('') }));
+jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
+  getUserDataDir: jest.fn().mockReturnValue('/tmp/test-loxia-data'),
+}));
+
+const { default: ScheduleService, evaluateScheduleRun, resolveTriggerCommand, buildSchtasksCreateCommand, parseTriggerScheduleArg } = await import('../scheduleService.js');
+
+const MISS = 90 * 1000;
+const GRACE = 24 * 60 * 60 * 1000;
+const now = new Date('2026-06-01T12:00:00Z');
+const ago = (ms) => new Date(now.getTime() - ms).toISOString();
+const ahead = (ms) => new Date(now.getTime() + ms).toISOString();
+
+describe('evaluateScheduleRun', () => {
+  const opts = { now, missThresholdMs: MISS, catchUpGraceMs: GRACE };
+
+  test('null nextRun → nothing due', () => {
+    expect(evaluateScheduleRun({ nextRun: null, ...opts })).toMatchObject({ due: false, shouldFire: false });
+  });
+  test('future nextRun → not due', () => {
+    expect(evaluateScheduleRun({ nextRun: ahead(60000), ...opts }).due).toBe(false);
+  });
+  test('just due (within miss threshold) → fire, not missed', () => {
+    const r = evaluateScheduleRun({ nextRun: ago(10 * 1000), ...opts });
+    expect(r).toMatchObject({ due: true, missed: false, shouldFire: true });
+  });
+  test('missed but within grace → recorded AND fired (catch-up)', () => {
+    const r = evaluateScheduleRun({ nextRun: ago(10 * 60 * 1000), ...opts });
+    expect(r).toMatchObject({ due: true, missed: true, withinGrace: true, shouldFire: true });
+  });
+  test('missed beyond grace → recorded but NOT fired (too stale)', () => {
+    const r = evaluateScheduleRun({ nextRun: ago(48 * 60 * 60 * 1000), ...opts });
+    expect(r).toMatchObject({ due: true, missed: true, withinGrace: false, shouldFire: false });
+  });
+});
+
+describe('resolveTriggerCommand', () => {
+  test('Electron → registers the app executable with --trigger-schedule', () => {
+    expect(resolveTriggerCommand({ scheduleId: 's1', isElectron: true, execPath: '/Apps/OnBuzz.exe', loxiaBin: 'loxia' }))
+      .toBe('"/Apps/OnBuzz.exe" --trigger-schedule=s1');
+  });
+  test('non-Electron → uses the CLI bin', () => {
+    expect(resolveTriggerCommand({ scheduleId: 's1', isElectron: false, execPath: '/x', loxiaBin: 'node bin/cli.js' }))
+      .toBe('node bin/cli.js trigger-schedule s1');
+  });
+  test('Electron without execPath → falls back to the CLI form', () => {
+    expect(resolveTriggerCommand({ scheduleId: 's1', isElectron: true, execPath: '', loxiaBin: 'loxia' }))
+      .toBe('loxia trigger-schedule s1');
+  });
+});
+
+// ── tick-level missed-run behavior (uses real time; _tick reads new Date()) ──
+const rAgo = (ms) => new Date(Date.now() - ms).toISOString();
+const rAhead = (ms) => new Date(Date.now() + ms).toISOString();
+
+function svcWith(schedule) {
+  const svc = new ScheduleService(createMockLogger());
+  svc._executeSchedule = jest.fn().mockResolvedValue(undefined);
+  svc._saveSchedules = jest.fn().mockResolvedValue(undefined);
+  svc._broadcast = jest.fn();
+  svc.schedules.set(schedule.id, schedule);
+  return svc;
+}
+
+function baseSchedule(overrides = {}) {
+  return {
+    id: 'sch-1', name: 'Test', prompt: 'do', targetType: 'agent', targetId: 'a1',
+    cronExpression: '* * * * *', enabled: true, startDate: null, endDate: null,
+    maxRuns: null, runOnce: false, nextRun: null, lastRun: null, runCount: 0,
+    lastMissedRun: null, missedRunCount: 0, ...overrides,
+  };
+}
+
+describe('_tick missed-run handling', () => {
+  beforeEach(() => jest.restoreAllMocks());
+
+  test('on-time run fires without recording a miss', async () => {
+    const sched = baseSchedule({ nextRun: rAgo(10 * 1000) });
+    const svc = svcWith(sched);
+    await svc._tick();
+    expect(svc._executeSchedule).toHaveBeenCalledTimes(1);
+    expect(sched.runCount).toBe(1);
+    expect(sched.missedRunCount).toBe(0);
+    expect(sched.lastMissedRun).toBeNull();
+  });
+
+  test('recent missed run is recorded AND caught up', async () => {
+    const missedAt = rAgo(10 * 60 * 1000);
+    const sched = baseSchedule({ nextRun: missedAt });
+    const svc = svcWith(sched);
+    await svc._tick();
+    expect(svc._executeSchedule).toHaveBeenCalledTimes(1);   // caught up
+    expect(sched.runCount).toBe(1);
+    expect(sched.missedRunCount).toBe(1);                     // recorded
+    expect(sched.lastMissedRun).toBe(missedAt);
+    expect(svc._broadcast).toHaveBeenCalledWith('schedule_missed', expect.objectContaining({ caughtUp: true }));
+  });
+
+  test('stale missed run (beyond grace) is recorded but NOT executed, and advances', async () => {
+    const sched = baseSchedule({ nextRun: rAgo(48 * 60 * 60 * 1000) });
+    const svc = svcWith(sched);
+    await svc._tick();
+    expect(svc._executeSchedule).not.toHaveBeenCalled();      // too stale to run
+    expect(sched.runCount).toBe(0);
+    expect(sched.missedRunCount).toBe(1);                     // still recorded
+    expect(svc._broadcast).toHaveBeenCalledWith('schedule_missed', expect.objectContaining({ caughtUp: false }));
+    expect(new Date(sched.nextRun).getTime()).toBeGreaterThan(now.getTime()); // advanced to the future
+  });
+});
+
+describe('buildSchtasksCreateCommand (Windows quoting)', () => {
+  test('escapes inner quotes so the /TR action is not truncated', () => {
+    const cmd = resolveTriggerCommand({ scheduleId: 's1', isElectron: true, execPath: 'C:\\Apps\\OnBuzz.exe', loxiaBin: 'loxia' });
+    const full = buildSchtasksCreateCommand('LoxiaSchedule_s1', cmd, '/SC DAILY /ST 09:00');
+    // Inner quotes around the exe path must be backslash-escaped for schtasks.
+    expect(full).toContain('/TR "\\"C:\\Apps\\OnBuzz.exe\\" --trigger-schedule=s1"');
+    expect(full).toContain('/TN "LoxiaSchedule_s1"');
+    expect(full).toContain('/SC DAILY /ST 09:00');
+    // The action must NOT contain a bare unescaped inner quote.
+    const tr = full.slice(full.indexOf('/TR "') + 5, full.lastIndexOf('" /SC'));
+    expect(tr.includes('\\"')).toBe(true);
+  });
+  test('also escapes the node "bin/cli.js" CLI form', () => {
+    const cmd = resolveTriggerCommand({ scheduleId: 's2', isElectron: false, loxiaBin: 'node "C:\\app\\bin\\cli.js"' });
+    const full = buildSchtasksCreateCommand('T', cmd, '/SC DAILY');
+    expect(full).toContain('node \\"C:\\app\\bin\\cli.js\\" trigger-schedule s2');
+  });
+});
+
+describe('parseTriggerScheduleArg', () => {
+  test('extracts the id from an Electron launch argv', () => {
+    expect(parseTriggerScheduleArg(['app.exe', '--trigger-schedule=sch-123'])).toBe('sch-123');
+    expect(parseTriggerScheduleArg(['app.exe', '--other'])).toBeNull();
+    expect(parseTriggerScheduleArg(['app.exe', '--trigger-schedule='])).toBeNull(); // empty → null
+    expect(parseTriggerScheduleArg()).toBeNull();
+  });
+});
+
+describe('start() honours the boot-trigger env', () => {
+  const ORIG = process.env.LOXIA_TRIGGER_SCHEDULE;
+  test('fires the schedule named by LOXIA_TRIGGER_SCHEDULE on boot', async () => {
+    const svc = svcWith(baseSchedule({ id: 'boot-1' }));
+    svc.triggerSchedule = jest.fn().mockResolvedValue(undefined);
+    svc._tick = jest.fn().mockResolvedValue(undefined);
+    svc.syncAllToOS = jest.fn().mockResolvedValue(undefined);
+    process.env.LOXIA_TRIGGER_SCHEDULE = 'boot-1';
+    try {
+      svc.start();
+      // start() schedules the boot-trigger via a resolved promise; flush microtasks.
+      await Promise.resolve(); await Promise.resolve();
+      expect(svc.triggerSchedule).toHaveBeenCalledWith('boot-1');
+    } finally {
+      svc.stop();
+      if (ORIG === undefined) delete process.env.LOXIA_TRIGGER_SCHEDULE;
+      else process.env.LOXIA_TRIGGER_SCHEDULE = ORIG;
+    }
+  });
+});
+
+describe('triggerSchedule (force run / boot-trigger / run-now)', () => {
+  beforeEach(() => jest.restoreAllMocks());
+
+  test('runs the schedule immediately and counts it', async () => {
+    const sched = baseSchedule({ nextRun: rAhead(60000) });
+    const svc = svcWith(sched);
+    const result = await svc.triggerSchedule('sch-1');
+    expect(svc._executeSchedule).toHaveBeenCalledTimes(1);
+    expect(result.runCount).toBe(1);
+    expect(result.lastRun).toBeTruthy();
+  });
+
+  test('throws for an unknown id', async () => {
+    const svc = svcWith(baseSchedule());
+    await expect(svc.triggerSchedule('nope')).rejects.toThrow(/not found/i);
+  });
+});

package/src/services/aiService.js

@@ -17,6 +17,7 @@ import {
   COMPACTION_CONFIG
 } from '../utilities/constants.js';
 import { getOllamaService, OLLAMA_MODEL_PREFIX } from './ollamaService.js';
+import { SHARED_MEMORY_SCOPE } from './memoryService.js';
 
 /**
  * Pull the reasoning-token count out of a usage object, checking every
@@ -1206,19 +1207,53 @@ class AIService {
 
     const memoryIndexer = await this._buildMemoryIndexer();
     const reminisceIndexer = await this._buildReminisceIndexer();
+    const documentIndexer = await this._buildDocumentIndexer();
+
+    const cfg = this.embeddingService.config;
+    const indexers = { memory: memoryIndexer, reminisce: reminisceIndexer, documents: documentIndexer };
+    let recallOpts = opts;
+
+    // Shared user-memory tier: when enabled, EVERY agent also recalls a single
+    // shared memory store (facts about the user). Implemented as an extra
+    // 'shared-memory' surface that searches the memory indexer at the shared
+    // scope — no new store machinery needed. Off by default (agents isolated).
+    if (memoryIndexer && cfg?.autoRecall?.sharedUserMemory) {
+      indexers['shared-memory'] = {
+        isEnabled: memoryIndexer.isEnabled,
+        search: (_agentId, query, searchOpts) =>
+          memoryIndexer.search(SHARED_MEMORY_SCOPE, query, searchOpts),
+      };
+      const base = Array.isArray(cfg.autoRecall.surfaces) && cfg.autoRecall.surfaces.length
+        ? cfg.autoRecall.surfaces : ['memory', 'reminisce', 'documents'];
+      recallOpts = { ...opts, surfaces: [...new Set([...base, 'shared-memory'])] };
+    }
 
     const deps = {
-      getIndexers: () => ({ memory: memoryIndexer, reminisce: reminisceIndexer }),
-      getConfig:   () => this.embeddingService.config,
+      getIndexers: () => indexers,
+      getConfig:   () => cfg,
     };
 
     let result;
     try {
-      result = await recallForPrompt(deps, agentId, recentText, opts);
+      result = await recallForPrompt(deps, agentId, recentText, recallOpts);
     } catch (err) {
       this.logger?.warn?.('[aiService] auto-recall failed', { error: err?.message });
       return systemPrompt;
     }
+
+    // Publish the recall funnel for the live memory-path view (best-effort,
+    // fire-and-forget). Recorded even when nothing was injected — "ran, found
+    // 0" is itself the signal that recall is alive. Never blocks the turn.
+    try {
+      if (result?.enabled && result.stats && this.embeddingService?.recordRecallActivity) {
+        this.embeddingService.recordRecallActivity(
+          agentId,
+          result.stats,
+          (result.items || []).map(i => ({ id: i.id, title: i.title, source: i.source, score: i.score })),
+        );
+      }
+    } catch { /* telemetry must never break the turn */ }
+
     if (!result?.items?.length) return systemPrompt;
 
     const section = formatRecallSection(result.items);
@@ -1238,6 +1273,49 @@ class AIService {
     }
   }
 
+  /**
+   * Auto-index the agent's conversation into the `reminisce` surface so the
+   * agent can semantically recall its own past messages (auto-recall's
+   * conversation tier). Without this the reminisce index stays empty and
+   * recall can only see saved memories + offloaded documents.
+   *
+   * Incremental: only messages past the persisted high-water mark
+   * (`agent.reminisceIndexedCount`) are embedded, so the steady-state cost is a
+   * 1-message embed per turn; the first call after deploy/load catches the
+   * backlog. Idempotent (indexMany dedups chunks by messageId) and best-effort
+   * — never throws, never blocks the turn. Embeddings are local, so this is
+   * CPU only (no API spend).
+   *
+   * @param {object} agent  Live agent (mutated: `reminisceIndexedCount`).
+   * @returns {Promise<void>}
+   */
+  async autoIndexReminisce(agent) {
+    try {
+      if (!this.embeddingService || !this.embeddingService.isEnabled) return;
+      const msgs = agent?.conversations?.full?.messages;
+      if (!Array.isArray(msgs) || msgs.length === 0) return;
+
+      // High-water mark. Reset to 0 if it somehow exceeds the current length
+      // (history was cleared/truncated) so we re-index from the start.
+      let from = Number.isInteger(agent.reminisceIndexedCount) ? agent.reminisceIndexedCount : 0;
+      if (from > msgs.length) from = 0;
+      if (msgs.length <= from) return; // nothing new since last index
+
+      const indexer = await this._buildReminisceIndexer();
+      if (!indexer || !indexer.isEnabled) return;
+
+      const result = await indexer.indexMany(agent.id, msgs.slice(from));
+      // Advance the mark only when the batch didn't hard-fail — a transient
+      // embed error leaves the mark so the next turn retries. (Per-message
+      // skips, e.g. empty text, are fine to move past.)
+      if (result && !result.error) {
+        agent.reminisceIndexedCount = msgs.length;
+      }
+    } catch (err) {
+      this.logger?.warn?.('[aiService] reminisce auto-index failed', { agentId: agent?.id, error: err?.message });
+    }
+  }
+
   /** @private — lazy ReminisceIndexer construction (async dynamic import). */
   async _buildReminisceIndexer() {
     if (this._reminisceIndexerForRecall) return this._reminisceIndexerForRecall;
@@ -1251,6 +1329,19 @@ class AIService {
     }
   }
 
+  /** @private — lazy DocumentIndexer construction (offloaded web/file content surface). */
+  async _buildDocumentIndexer() {
+    if (this._documentIndexerForRecall) return this._documentIndexerForRecall;
+    if (!this.embeddingService) return null;
+    try {
+      const { DocumentIndexer } = await import('./embeddings/indexers/documentIndexer.js');
+      this._documentIndexerForRecall = new DocumentIndexer({ embeddingService: this.embeddingService, logger: this.logger });
+      return this._documentIndexerForRecall;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Abort an active request for a specific agent
    * Used when user clicks "Stop" to immediately cancel streaming
@@ -1440,6 +1531,10 @@ class AIService {
         prompt,
         model,
         imageBase64,
+        // Multi-reference edit: forward the full array when provided. Older
+        // backends ignore this and use imageBase64 (the first image), so this
+        // is backward compatible in both directions.
+        ...(Array.isArray(options.imagesBase64) && options.imagesBase64.length > 1 && { imagesBase64: options.imagesBase64 }),
         ...(options.maskBase64 && { maskBase64: options.maskBase64 }),
         requestId
       };

package/src/services/attachments/__tests__/attachmentContextBuilder.test.js

@@ -0,0 +1,288 @@
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { AttachmentContextBuilder, latestUserQuery } from '../attachmentContextBuilder.js';
+
+describe('latestUserQuery', () => {
+  test('returns the last user string message', () => {
+    expect(latestUserQuery([{ role: 'user', content: 'first' }, { role: 'assistant', content: 'a' }, { role: 'user', content: 'last' }])).toBe('last');
+  });
+  test('extracts text from a multimodal content array', () => {
+    expect(latestUserQuery([{ role: 'user', content: [{ type: 'image' }, { type: 'text', text: 'caption' }] }])).toBe('caption');
+  });
+  test('multimodal with no text block → empty', () => {
+    expect(latestUserQuery([{ role: 'user', content: [{ type: 'image' }] }])).toBe('');
+  });
+  test('non-string non-array content → empty', () => {
+    expect(latestUserQuery([{ role: 'user', content: { weird: true } }])).toBe('');
+  });
+  test('skips assistant/non-user messages', () => {
+    expect(latestUserQuery([{ role: 'user', content: 'q' }, { role: 'assistant', content: 'a' }, { role: 'tool', content: 't' }])).toBe('q');
+  });
+  test('no user message → empty', () => {
+    expect(latestUserQuery([{ role: 'assistant', content: 'a' }])).toBe('');
+  });
+  test('non-array / null input → empty', () => {
+    expect(latestUserQuery(null)).toBe('');
+    expect(latestUserQuery(undefined)).toBe('');
+  });
+  test('null entries are skipped', () => {
+    expect(latestUserQuery([null, { role: 'user', content: 'q' }])).toBe('q');
+  });
+});
+
+function makeBuilder({ active = [], content = {}, recallHits = [], analysis = null, documentMemory, visionAnalysisService } = {}) {
+  const attachmentService = {
+    getActiveAttachments: jest.fn().mockResolvedValue(active),
+    getAttachmentContent: jest.fn(async (id) => content[id] ?? null),
+  };
+  const dm = documentMemory ?? { recall: jest.fn().mockResolvedValue({ hits: recallHits }) };
+  const vas = visionAnalysisService ?? (analysis !== null
+    ? { analyze: jest.fn().mockResolvedValue({ text: analysis }), hasVisionModel: () => true }
+    : null);
+  const builder = new AttachmentContextBuilder({ attachmentService, documentMemory: dm, visionAnalysisService: vas });
+  return { builder, attachmentService, dm, vas };
+}
+
+describe('constructor', () => {
+  test('accepts all explicit dependencies', () => {
+    const b = new AttachmentContextBuilder({
+      attachmentService: {}, documentMemory: {}, visionAnalysisService: {},
+      classify: () => ({ strategy: 'reference' }), logger: { warn() {} },
+    });
+    expect(b).toBeTruthy();
+  });
+  test('constructs with no arguments at all', () => {
+    expect(() => new AttachmentContextBuilder()).not.toThrow();
+  });
+});
+
+describe('build — guards', () => {
+  test('no attachmentService → empty', async () => {
+    const b = new AttachmentContextBuilder({});
+    expect(await b.build('a1')).toEqual({ systemAdditions: '', contentBlocks: [] });
+  });
+  test('no agentId → empty', async () => {
+    const { builder } = makeBuilder();
+    expect((await builder.build('')).systemAdditions).toBe('');
+  });
+  test('no active attachments → empty', async () => {
+    const { builder } = makeBuilder({ active: [] });
+    expect((await builder.build('a1')).systemAdditions).toBe('');
+  });
+  test('getActiveAttachments returning null → empty (|| [] guard)', async () => {
+    const attachmentService = { getActiveAttachments: jest.fn().mockResolvedValue(null) };
+    const b = new AttachmentContextBuilder({ attachmentService });
+    expect((await b.build('a1')).systemAdditions).toBe('');
+  });
+
+  test('getActiveAttachments throwing → empty (no throw)', async () => {
+    const attachmentService = { getActiveAttachments: jest.fn().mockRejectedValue(new Error('boom')) };
+    const b = new AttachmentContextBuilder({ attachmentService });
+    expect((await b.build('a1')).systemAdditions).toBe('');
+  });
+});
+
+describe('build — inline text', () => {
+  test('small text → full content inline, XML-escaped', async () => {
+    const { builder } = makeBuilder({
+      active: [{ fileId: 'f1', fileName: 'note.txt', contentType: 'text', size: 100, tokenEstimate: 20 }],
+      content: { f1: 'hello <b> & "you"' },
+    });
+    const { systemAdditions } = await builder.build('a1');
+    expect(systemAdditions).toContain('<attached-files>');
+    expect(systemAdditions).toContain('mode="content"');
+    expect(systemAdditions).toContain('hello &lt;b&gt; &amp; &quot;you&quot;');
+  });
+  test('getAttachmentContent throwing → degrades to a reference', async () => {
+    const attachmentService = {
+      getActiveAttachments: jest.fn().mockResolvedValue([{ fileId: 'f1', fileName: 'n.txt', contentType: 'text', size: 50, tokenEstimate: 10 }]),
+      getAttachmentContent: jest.fn().mockRejectedValue(new Error('read fail')),
+    };
+    const b = new AttachmentContextBuilder({ attachmentService });
+    expect((await b.build('a1')).systemAdditions).toContain('content unavailable');
+  });
+
+  test('inline file with no size renders (size || 0 guard)', async () => {
+    const { builder } = makeBuilder({
+      active: [{ fileId: 'f1', fileName: 'n.txt', contentType: 'text', tokenEstimate: 5 }], // no size
+      content: { f1: 'hi' },
+    });
+    const { systemAdditions } = await builder.build('a1');
+    expect(systemAdditions).toContain('size="0.0KB"');
+  });
+
+  test('missing content → degrades to a reference', async () => {
+    const { builder } = makeBuilder({
+      active: [{ fileId: 'f1', fileName: 'note.txt', contentType: 'text', size: 100, tokenEstimate: 20 }],
+      content: {},
+    });
+    const { systemAdditions } = await builder.build('a1');
+    expect(systemAdditions).toContain('<file-references>');
+    expect(systemAdditions).toContain('content unavailable');
+  });
+});
+
+describe('build — document recall', () => {
+  const bigText = { fileId: 'f1', fileName: 'big.txt', contentType: 'text', size: 999999, tokenEstimate: 99999, docId: 'doc-1' };
+
+  test('recalls only relevant chunks for the query, scoped by docId', async () => {
+    const { builder, dm } = makeBuilder({ active: [bigText], recallHits: [{ text: 'chunk A' }, { text: 'chunk B' }] });
+    const { systemAdditions } = await builder.build('a1', { query: 'what is X?' });
+    expect(dm.recall).toHaveBeenCalledWith('a1', 'what is X?', expect.objectContaining({ docId: 'doc-1' }));
+    expect(systemAdditions).toContain('[relevant excerpts]');
+    expect(systemAdditions).toContain('chunk A');
+    expect(systemAdditions).toContain('chunk B');
+    expect(systemAdditions).toContain('mode="recall"');
+  });
+  test('no query → no recall, falls back to reference', async () => {
+    const { builder, dm } = makeBuilder({ active: [bigText], recallHits: [{ text: 'x' }] });
+    const { systemAdditions } = await builder.build('a1', { query: '' });
+    expect(dm.recall).not.toHaveBeenCalled();
+    expect(systemAdditions).toContain('mode="reference"');
+  });
+  test('no docId → reference (not yet indexed)', async () => {
+    const { builder } = makeBuilder({ active: [{ ...bigText, docId: undefined }], recallHits: [{ text: 'x' }] });
+    const { systemAdditions } = await builder.build('a1', { query: 'q' });
+    expect(systemAdditions).toContain('mode="reference"');
+  });
+  test('recall returns no hits → reference', async () => {
+    const { builder } = makeBuilder({ active: [bigText], recallHits: [] });
+    expect((await builder.build('a1', { query: 'q' })).systemAdditions).toContain('mode="reference"');
+  });
+  test('recall result without a hits array (|| [] guard) → reference', async () => {
+    const dm = { recall: jest.fn().mockResolvedValue({}) };
+    const { builder } = makeBuilder({ active: [bigText], documentMemory: dm });
+    expect((await builder.build('a1', { query: 'q' })).systemAdditions).toContain('mode="reference"');
+  });
+  test('null/empty hits are filtered before formatting', async () => {
+    const { builder } = makeBuilder({ active: [bigText], recallHits: [null, { text: '' }, { text: 'real chunk' }] });
+    const { systemAdditions } = await builder.build('a1', { query: 'q' });
+    expect(systemAdditions).toContain('real chunk');
+    expect(systemAdditions).toContain('mode="recall"');
+  });
+  test('recall throwing → reference (no throw)', async () => {
+    const dm = { recall: jest.fn().mockRejectedValue(new Error('vec down')) };
+    const { builder } = makeBuilder({ active: [bigText], documentMemory: dm });
+    expect((await builder.build('a1', { query: 'q' })).systemAdditions).toContain('mode="reference"');
+  });
+  test('recall unavailable but content present → inline full content (no regression)', async () => {
+    const { builder } = makeBuilder({ active: [bigText], recallHits: [], content: { f1: 'the whole big document' } });
+    const { systemAdditions } = await builder.build('a1', { query: 'q' });
+    expect(systemAdditions).toContain('mode="content"');
+    expect(systemAdditions).toContain('the whole big document');
+  });
+});
+
+describe('build — vision', () => {
+  const img = { fileId: 'f1', fileName: 'pic.png', contentType: 'image', fileType: 'image/png', size: 5000 };
+
+  test('image + vision service → injects the text analysis', async () => {
+    const { builder, vas } = makeBuilder({
+      active: [img], content: { f1: 'data:image/png;base64,QUJD' }, analysis: 'A red cube on white.',
+    });
+    const { systemAdditions } = await builder.build('a1', { query: 'what colour?' });
+    expect(vas.analyze).toHaveBeenCalledWith(expect.objectContaining({ imageBase64: 'QUJD', mimeType: 'image/png' }));
+    expect(vas.analyze.mock.calls[0][0].prompt).toContain('what colour?');
+    expect(systemAdditions).toContain('[vision analysis]');
+    expect(systemAdditions).toContain('A red cube on white.');
+    expect(systemAdditions).toContain('mode="vision"');
+  });
+  test('image content that is not a data URI still analyzes (raw base64 + fileType mime)', async () => {
+    const { builder, vas } = makeBuilder({ active: [img], content: { f1: 'RAWB64' }, analysis: 'ok' });
+    await builder.build('a1', { query: '' });
+    expect(vas.analyze).toHaveBeenCalledWith(expect.objectContaining({ imageBase64: 'RAWB64', mimeType: 'image/png' }));
+  });
+  test('no vision model at all → image becomes a plain reference (no analysis attempted)', async () => {
+    const { builder } = makeBuilder({ active: [img], content: { f1: 'data:image/png;base64,QQ==' }, visionAnalysisService: null });
+    const { systemAdditions } = await builder.build('a1', { query: 'q' });
+    expect(systemAdditions).toContain('mode="reference"');
+  });
+  test('a vision model exists but analysis yields nothing → reference with note', async () => {
+    const vas = { analyze: jest.fn().mockResolvedValue({ text: '' }), hasVisionModel: () => true };
+    const { builder } = makeBuilder({ active: [img], content: { f1: 'data:image/png;base64,QQ==' }, visionAnalysisService: vas });
+    expect((await builder.build('a1', { query: 'q' })).systemAdditions).toContain('vision analysis unavailable');
+  });
+  test('vision analysis returning empty → reference', async () => {
+    const vas = { analyze: jest.fn().mockResolvedValue({ text: '' }), hasVisionModel: () => true };
+    const { builder } = makeBuilder({ active: [img], content: { f1: 'data:image/png;base64,QQ==' }, visionAnalysisService: vas });
+    expect((await builder.build('a1', { query: 'q' })).systemAdditions).toContain('mode="reference"');
+  });
+  test('vision analysis throwing → reference (no throw)', async () => {
+    const vas = { analyze: jest.fn().mockRejectedValue(new Error('vision 500')), hasVisionModel: () => true };
+    const { builder } = makeBuilder({ active: [img], content: { f1: 'data:image/png;base64,QQ==' }, visionAnalysisService: vas });
+    expect((await builder.build('a1', { query: 'q' })).systemAdditions).toContain('mode="reference"');
+  });
+  test('image with no stored content → reference', async () => {
+    const vas = { analyze: jest.fn(), hasVisionModel: () => true };
+    const { builder } = makeBuilder({ active: [img], content: {}, visionAnalysisService: vas });
+    expect((await builder.build('a1', { query: 'q' })).systemAdditions).toContain('mode="reference"');
+    expect(vas.analyze).not.toHaveBeenCalled();
+  });
+});
+
+describe('build — scope filtering', () => {
+  const convFile = { fileId: 'f1', fileName: 'n.txt', contentType: 'text', size: 50, tokenEstimate: 10, scope: 'conversation', conversationId: 'c1' };
+  test('conversation-scoped attachment is excluded on a different conversation', async () => {
+    const { builder } = makeBuilder({ active: [convFile], content: { f1: 'hi' } });
+    expect((await builder.build('a1', { conversationId: 'c2' })).systemAdditions).toBe('');
+  });
+  test('conversation-scoped attachment is included on its own conversation', async () => {
+    const { builder } = makeBuilder({ active: [convFile], content: { f1: 'hi' } });
+    expect((await builder.build('a1', { conversationId: 'c1' })).systemAdditions).toContain('hi');
+  });
+  test('agent-scoped attachment is included regardless of conversation', async () => {
+    const { builder } = makeBuilder({ active: [{ fileId: 'f1', fileName: 'n.txt', contentType: 'text', size: 50, tokenEstimate: 10 }], content: { f1: 'hi' } });
+    expect((await builder.build('a1', { conversationId: 'cX' })).systemAdditions).toContain('hi');
+  });
+});
+
+describe('build — reference + mixed', () => {
+  test('binary → reference with path', async () => {
+    const { builder } = makeBuilder({ active: [{ fileId: 'f1', fileName: 'a.zip', contentType: 'binary', size: 10, originalPath: '/srv/a.zip' }] });
+    const { systemAdditions } = await builder.build('a1');
+    expect(systemAdditions).toContain('mode="reference"');
+    expect(systemAdditions).toContain('path="/srv/a.zip"');
+    expect(systemAdditions).toContain('referenced files can be read');
+  });
+  test('explicit model.hasVisionModel=true but no vision service → image reference', async () => {
+    const attachmentService = {
+      getActiveAttachments: jest.fn().mockResolvedValue([{ fileId: 'f1', fileName: 'p.png', contentType: 'image', size: 100 }]),
+      getAttachmentContent: jest.fn().mockResolvedValue('data:image/png;base64,QQ=='),
+    };
+    const b = new AttachmentContextBuilder({ attachmentService }); // no vision service
+    const { systemAdditions } = await b.build('a1', { model: { hasVisionModel: true }, query: 'q' });
+    expect(systemAdditions).toContain('mode="reference"');
+  });
+
+  test('attachment missing fileName/type/contentType is handled without throwing', async () => {
+    const attachmentService = {
+      getActiveAttachments: jest.fn().mockResolvedValue([{ fileId: 'f1', size: 5 }]),
+      getAttachmentContent: jest.fn(),
+    };
+    const b = new AttachmentContextBuilder({ attachmentService });
+    expect((await b.build('a1')).systemAdditions).toContain('mode="reference"');
+  });
+
+  test('non-data-URI image without fileType defaults the mime to image/png', async () => {
+    const vas = { analyze: jest.fn().mockResolvedValue({ text: 'x' }), hasVisionModel: () => true };
+    const attachmentService = {
+      getActiveAttachments: jest.fn().mockResolvedValue([{ fileId: 'f1', fileName: 'p', contentType: 'image', size: 100 }]),
+      getAttachmentContent: jest.fn().mockResolvedValue('RAWB64'),
+    };
+    const b = new AttachmentContextBuilder({ attachmentService, visionAnalysisService: vas });
+    await b.build('a1', { query: '' });
+    expect(vas.analyze).toHaveBeenCalledWith(expect.objectContaining({ mimeType: 'image/png' }));
+  });
+
+  test('mixed set produces both sections', async () => {
+    const { builder } = makeBuilder({
+      active: [
+        { fileId: 'f1', fileName: 'n.txt', contentType: 'text', size: 50, tokenEstimate: 10 },
+        { fileId: 'f2', fileName: 'a.zip', contentType: 'binary', size: 10 },
+      ],
+      content: { f1: 'hi' },
+    });
+    const { systemAdditions } = await builder.build('a1');
+    expect(systemAdditions).toContain('<attached-files>');
+    expect(systemAdditions).toContain('<file-references>');
+  });
+});