onbuzz 5.1.0 → 5.4.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/agentActivityService.js

@@ -250,8 +250,21 @@ export function shouldAgentBeActive(agent) {
   }
 
   if (agent.mode === AGENT_MODES.CHAT) {
-    // CHAT mode: active ONLY if has user messages or inter-agent messages
-    // Tool results alone should NOT keep CHAT agents active
+    // CHAT mode: active if it has user messages, inter-agent messages, OR
+    // queued tool results.
+    //
+    // Activating on tool results is what makes guided chat "agentic": after a
+    // chat agent fires a tool, the result wakes it so it can read the output
+    // and produce its follow-up answer (tool -> observe -> answer within one
+    // user turn). Keying off QUEUE STATE — rather than granting a TTL at each
+    // place a result is enqueued — covers every delivery path by construction:
+    //   - sync tools push directly in agentScheduler._executeToolsAsync,
+    //   - async tools (image/video/async ops) land later via addToolResult,
+    //   - system-error injections and reminders,
+    //   - any future enqueue path,
+    // all become visible here the same way. It self-terminates: once
+    // processAgentQueues drains the results into the conversation, the queue is
+    // empty and the agent goes idle unless it issued another tool call.
     const queueStatus = getMessageQueueStatus(agent);
 
     if (queueStatus.hasUserMessages) {
@@ -270,13 +283,19 @@ export function shouldAgentBeActive(agent) {
       };
     }
 
-    // CHAT mode with no user/inter-agent messages
+    if (queueStatus.hasToolResults) {
+      return {
+        active: true,
+        reason: AGENT_ACTIVITY_STATUS.HAS_TOOL_RESULTS,
+        details: `Agent has ${queueStatus.counts.toolResults} tool result(s) to react to`
+      };
+    }
+
+    // CHAT mode with nothing queued
     return {
       active: false,
       reason: AGENT_ACTIVITY_STATUS.CHAT_MODE_NO_MESSAGES,
-      details: queueStatus.hasToolResults
-        ? `CHAT mode - has ${queueStatus.counts.toolResults} tool results but no new messages`
-        : 'CHAT mode - no messages to process'
+      details: 'CHAT mode - no messages to process'
     };
   }
 

package/src/services/aiService.js

@@ -1531,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>');
+  });
+});