onbuzz 5.1.0 → 5.3.0

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

@@ -0,0 +1,184 @@
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import path from 'path';
+import { AttachmentIngestionService, safeBaseName } from '../attachmentIngestionService.js';
+
+function makeFs() {
+  return {
+    mkdir: jest.fn().mockResolvedValue(undefined),
+    writeFile: jest.fn().mockResolvedValue(undefined),
+    unlink: jest.fn().mockResolvedValue(undefined),
+  };
+}
+
+let fs, fas, svc;
+beforeEach(() => {
+  fs = makeFs();
+  fas = { uploadFile: jest.fn().mockResolvedValue({ fileId: 'f1', fileName: 'x' }) };
+  let n = 0;
+  svc = new AttachmentIngestionService({ fileAttachmentService: fas, fs, tempDir: '/tmp/ingest', idgen: () => `id${++n}` });
+});
+
+describe('safeBaseName', () => {
+  test('strips directories and unsafe chars', () => {
+    expect(safeBaseName('../../etc/pa ss wd')).toBe('pa_ss_wd');
+    expect(safeBaseName('C:\\evil\\report.pdf')).toBe('report.pdf');
+    expect(safeBaseName('')).toBe('upload');
+    expect(safeBaseName('...')).toBe('upload');
+  });
+});
+
+describe('ingestUpload', () => {
+  test('decodes base64 and writes BINARY bytes (not utf8) to a temp file', async () => {
+    const bytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0xff]); // PNG-ish header w/ non-utf8 bytes
+    const b64 = bytes.toString('base64');
+
+    await svc.ingestUpload({ agentId: 'a1', fileName: 'pic.png', dataBase64: b64 });
+
+    expect(fs.mkdir).toHaveBeenCalledWith('/tmp/ingest', { recursive: true });
+    const [writtenPath, writtenData, ...rest] = fs.writeFile.mock.calls[0];
+    expect(writtenPath).toBe(path.join('/tmp/ingest', 'id1-pic.png'));
+    expect(Buffer.isBuffer(writtenData)).toBe(true);          // bytes, not a string
+    expect(writtenData.equals(bytes)).toBe(true);             // exact round-trip
+    expect(rest).toEqual([]);                                  // no 'utf8' encoding arg
+  });
+
+  test('hands the temp path to fileAttachmentService and returns its metadata', async () => {
+    const res = await svc.ingestUpload({ agentId: 'a1', fileName: 'pic.png', dataBase64: Buffer.from('x').toString('base64') });
+    expect(fas.uploadFile).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'a1', filePath: path.join('/tmp/ingest', 'id1-pic.png'), mode: 'content', fileName: 'pic.png', scope: 'agent', conversationId: null }));
+    expect(res).toEqual({ fileId: 'f1', fileName: 'x' });
+  });
+
+  test('accepts a data: URI and strips the prefix', async () => {
+    const bytes = Buffer.from('hello');
+    await svc.ingestUpload({ agentId: 'a1', fileName: 't.txt', dataBase64: `data:text/plain;base64,${bytes.toString('base64')}` });
+    expect(fs.writeFile.mock.calls[0][1].equals(bytes)).toBe(true);
+  });
+
+  test('a data: prefix with no comma falls back to the whole string as base64', async () => {
+    await svc.ingestUpload({ agentId: 'a1', fileName: 't.txt', dataBase64: 'data:AAAA' });
+    expect(fs.writeFile).toHaveBeenCalledTimes(1);
+  });
+
+  test('cleans up the temp file after success', async () => {
+    await svc.ingestUpload({ agentId: 'a1', fileName: 't.txt', dataBase64: Buffer.from('x').toString('base64') });
+    expect(fs.unlink).toHaveBeenCalledWith(path.join('/tmp/ingest', 'id1-t.txt'));
+  });
+
+  test('cleans up the temp file even when upload fails, and propagates the error', async () => {
+    fas.uploadFile.mockRejectedValueOnce(new Error('validation failed'));
+    await expect(svc.ingestUpload({ agentId: 'a1', fileName: 't.txt', dataBase64: Buffer.from('x').toString('base64') }))
+      .rejects.toThrow(/validation failed/);
+    expect(fs.unlink).toHaveBeenCalled();
+  });
+
+  test('cleanup failure is swallowed (does not mask the result)', async () => {
+    fs.unlink.mockRejectedValueOnce(new Error('ENOENT'));
+    const res = await svc.ingestUpload({ agentId: 'a1', fileName: 't.txt', dataBase64: Buffer.from('x').toString('base64') });
+    expect(res.fileId).toBe('f1');
+  });
+
+  test.each([
+    [{ fileName: 'x', dataBase64: 'AA' }, /agentId is required/],
+    [{ agentId: 'a', dataBase64: 'AA' }, /fileName is required/],
+    [{ agentId: 'a', fileName: 'x' }, /dataBase64 is required/],
+    [{ agentId: 'a', fileName: 'x', dataBase64: '' }, /dataBase64 is required/],
+  ])('rejects invalid input %#', async (input, re) => {
+    await expect(svc.ingestUpload(input)).rejects.toThrow(re);
+    expect(fs.writeFile).not.toHaveBeenCalled();
+  });
+
+  test('respects a custom mode', async () => {
+    await svc.ingestUpload({ agentId: 'a1', fileName: 't.txt', dataBase64: 'AA==', mode: 'reference' });
+    expect(fas.uploadFile.mock.calls[0][0].mode).toBe('reference');
+  });
+
+  test('forwards scope + conversationId to uploadFile', async () => {
+    await svc.ingestUpload({ agentId: 'a1', fileName: 't.txt', dataBase64: 'AA==', scope: 'conversation', conversationId: 'c1' });
+    expect(fas.uploadFile).toHaveBeenCalledWith(expect.objectContaining({ scope: 'conversation', conversationId: 'c1' }));
+  });
+});
+
+describe('ingestServerPath', () => {
+  test('delegates straight to fileAttachmentService', async () => {
+    await svc.ingestServerPath({ agentId: 'a1', filePath: '/srv/doc.pdf', fileName: 'doc.pdf' });
+    expect(fas.uploadFile).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'a1', filePath: '/srv/doc.pdf', mode: 'content', fileName: 'doc.pdf' }));
+    expect(fs.writeFile).not.toHaveBeenCalled(); // no staging for server files
+  });
+  test.each([
+    [{ filePath: '/x' }, /agentId is required/],
+    [{ agentId: 'a' }, /filePath is required/],
+  ])('validates input %#', async (input, re) => {
+    await expect(svc.ingestServerPath(input)).rejects.toThrow(re);
+  });
+});
+
+describe('large-text indexing into the DocumentStore', () => {
+  const bigText = { fileId: 'f1', fileName: 'big.txt', contentType: 'text', size: 999999, tokenEstimate: 99999 };
+  const smallText = { fileId: 'f2', fileName: 'note.txt', contentType: 'text', size: 100, tokenEstimate: 50 };
+  let dm, fasIdx, idxSvc;
+
+  beforeEach(() => {
+    dm = { remember: jest.fn().mockResolvedValue({ docId: 'doc-1' }) };
+    fasIdx = {
+      uploadFile: jest.fn().mockResolvedValue(bigText),
+      getAttachmentContent: jest.fn().mockResolvedValue('a very long document body'.repeat(100)),
+      updateAttachment: jest.fn().mockResolvedValue(undefined),
+    };
+    idxSvc = new AttachmentIngestionService({ fileAttachmentService: fasIdx, documentMemory: dm, fs, tempDir: '/tmp/ingest', idgen: () => 'id1' });
+  });
+
+  test('large text → remembered in the store and linked by docId', async () => {
+    const res = await idxSvc.ingestUpload({ agentId: 'a1', fileName: 'big.txt', dataBase64: 'AAAA' });
+    expect(dm.remember).toHaveBeenCalledWith('a1', expect.objectContaining({ source: 'big.txt', title: 'big.txt' }));
+    expect(fasIdx.updateAttachment).toHaveBeenCalledWith('f1', { docId: 'doc-1', indexed: true });
+    expect(res).toMatchObject({ docId: 'doc-1', indexed: true });
+  });
+
+  test('small text is NOT indexed', async () => {
+    fasIdx.uploadFile.mockResolvedValueOnce(smallText);
+    await idxSvc.ingestUpload({ agentId: 'a1', fileName: 'note.txt', dataBase64: 'AAAA' });
+    expect(dm.remember).not.toHaveBeenCalled();
+  });
+
+  test('no documentMemory → never indexes (default behavior)', async () => {
+    const res = await svc.ingestUpload({ agentId: 'a1', fileName: 'big.txt', dataBase64: 'AAAA' });
+    expect(res).toEqual({ fileId: 'f1', fileName: 'x' }); // svc has no documentMemory
+  });
+
+  test('empty extracted content → skip indexing', async () => {
+    fasIdx.getAttachmentContent.mockResolvedValueOnce('');
+    const res = await idxSvc.ingestUpload({ agentId: 'a1', fileName: 'big.txt', dataBase64: 'AAAA' });
+    expect(dm.remember).not.toHaveBeenCalled();
+    expect(res).toBe(bigText);
+  });
+
+  test('indexing failure is swallowed; the attachment is still returned', async () => {
+    dm.remember.mockRejectedValueOnce(new Error('embeddings down'));
+    const res = await idxSvc.ingestUpload({ agentId: 'a1', fileName: 'big.txt', dataBase64: 'AAAA' });
+    expect(res).toBe(bigText); // original metadata, no docId
+    expect(fasIdx.updateAttachment).not.toHaveBeenCalled();
+  });
+
+  test('ingestServerPath also indexes large text', async () => {
+    await idxSvc.ingestServerPath({ agentId: 'a1', filePath: '/srv/big.txt', fileName: 'big.txt' });
+    expect(dm.remember).toHaveBeenCalled();
+  });
+
+  test('null metadata from upload is tolerated', async () => {
+    fasIdx.uploadFile.mockResolvedValueOnce(null);
+    const res = await idxSvc.ingestUpload({ agentId: 'a1', fileName: 'x', dataBase64: 'AAAA' });
+    expect(res).toBeNull();
+    expect(dm.remember).not.toHaveBeenCalled();
+  });
+});
+
+describe('defaults', () => {
+  test('falls back to an OS temp dir when none injected', () => {
+    const s = new AttachmentIngestionService({ fileAttachmentService: fas });
+    expect(typeof s.tempDir).toBe('string');
+    expect(s.tempDir.length).toBeGreaterThan(0);
+  });
+  test('constructs with no arguments at all (default options)', () => {
+    expect(() => new AttachmentIngestionService()).not.toThrow();
+  });
+});

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

@@ -0,0 +1,26 @@
+import { describe, test, expect } from '@jest/globals';
+import { inAttachmentScope } from '../attachmentScope.js';
+
+describe('inAttachmentScope', () => {
+  test('no scope (legacy) → always in scope', () => {
+    expect(inAttachmentScope({})).toBe(true);
+    expect(inAttachmentScope({}, { conversationId: 'c1' })).toBe(true);
+  });
+  test("'agent' scope → always in scope", () => {
+    expect(inAttachmentScope({ scope: 'agent' }, { conversationId: 'c1' })).toBe(true);
+  });
+  test("'conversation' scope → only when conversationId matches", () => {
+    expect(inAttachmentScope({ scope: 'conversation', conversationId: 'c1' }, { conversationId: 'c1' })).toBe(true);
+    expect(inAttachmentScope({ scope: 'conversation', conversationId: 'c1' }, { conversationId: 'c2' })).toBe(false);
+  });
+  test("'conversation' scope with no current conversationId → out of scope", () => {
+    expect(inAttachmentScope({ scope: 'conversation', conversationId: 'c1' })).toBe(false);
+  });
+  test('unknown scope → fail-open (included)', () => {
+    expect(inAttachmentScope({ scope: 'weird' }, { conversationId: 'c1' })).toBe(true);
+  });
+  test('null/undefined attachment → in scope (no throw)', () => {
+    expect(inAttachmentScope(null)).toBe(true);
+    expect(inAttachmentScope(undefined)).toBe(true);
+  });
+});

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

@@ -0,0 +1,85 @@
+import { describe, test, expect } from '@jest/globals';
+import { classifyAttachment, DEFAULT_THRESHOLDS } from '../attachmentStrategy.js';
+
+const strat = (input, cfg) => classifyAttachment(input, cfg).strategy;
+
+describe('classifyAttachment — text', () => {
+  test('small text (under token threshold) → inline-text', () => {
+    expect(strat({ contentType: 'text', tokenEstimate: 500 })).toBe('inline-text');
+  });
+  test('large text (over token threshold) → document-recall', () => {
+    expect(strat({ contentType: 'text', tokenEstimate: 5000 })).toBe('document-recall');
+  });
+  test('token threshold boundary is inclusive (== stays inline)', () => {
+    expect(strat({ contentType: 'text', tokenEstimate: DEFAULT_THRESHOLDS.inlineTextMaxTokens })).toBe('inline-text');
+    expect(strat({ contentType: 'text', tokenEstimate: DEFAULT_THRESHOLDS.inlineTextMaxTokens + 1 })).toBe('document-recall');
+  });
+  test('no token estimate → falls back to byte ceiling', () => {
+    expect(strat({ contentType: 'text', byteSize: 1000 })).toBe('inline-text');
+    expect(strat({ contentType: 'text', byteSize: DEFAULT_THRESHOLDS.inlineTextMaxBytes + 1 })).toBe('document-recall');
+  });
+  test('token estimate present overrides bytes (big bytes, tiny tokens → inline)', () => {
+    expect(strat({ contentType: 'text', tokenEstimate: 100, byteSize: 10 * 1024 * 1024 })).toBe('inline-text');
+  });
+});
+
+describe('classifyAttachment — image', () => {
+  test('vision-capable chat model → vision-native', () => {
+    expect(strat({ contentType: 'image', byteSize: 1000, modelVisionCapable: true, hasVisionModel: true })).toBe('vision-native');
+  });
+  test('non-vision chat model but a vision model exists → vision-analyze', () => {
+    expect(strat({ contentType: 'image', byteSize: 1000, modelVisionCapable: false, hasVisionModel: true })).toBe('vision-analyze');
+  });
+  test('no vision model at all → reference', () => {
+    expect(strat({ contentType: 'image', byteSize: 1000, modelVisionCapable: false, hasVisionModel: false })).toBe('reference');
+  });
+  test('oversize image → reference even when vision-capable', () => {
+    expect(strat({ contentType: 'image', byteSize: DEFAULT_THRESHOLDS.visionMaxBytes + 1, modelVisionCapable: true, hasVisionModel: true })).toBe('reference');
+  });
+  test('image at the size boundary is still allowed', () => {
+    expect(strat({ contentType: 'image', byteSize: DEFAULT_THRESHOLDS.visionMaxBytes, modelVisionCapable: true })).toBe('vision-native');
+  });
+});
+
+describe('classifyAttachment — pdf', () => {
+  test('small PDF + vision model → vision-native', () => {
+    expect(strat({ contentType: 'pdf', byteSize: 1000, modelVisionCapable: true })).toBe('vision-native');
+  });
+  test('PDF without a vision-capable chat model → document-recall', () => {
+    expect(strat({ contentType: 'pdf', byteSize: 1000, modelVisionCapable: false })).toBe('document-recall');
+  });
+  test('oversize PDF even with vision model → document-recall (not native)', () => {
+    expect(strat({ contentType: 'pdf', byteSize: DEFAULT_THRESHOLDS.visionMaxBytes + 1, modelVisionCapable: true })).toBe('document-recall');
+  });
+});
+
+describe('classifyAttachment — binary/unknown + config', () => {
+  test('binary → reference', () => {
+    expect(strat({ contentType: 'binary', byteSize: 1000 })).toBe('reference');
+  });
+  test('unknown contentType → reference', () => {
+    expect(strat({ contentType: undefined })).toBe('reference');
+  });
+  test('empty input → reference (no throw)', () => {
+    expect(classifyAttachment()).toMatchObject({ strategy: 'reference' });
+  });
+  test('threshold override is honored', () => {
+    expect(strat({ contentType: 'text', tokenEstimate: 800 }, { inlineTextMaxTokens: 500 })).toBe('document-recall');
+  });
+  test('every result carries a human-readable reason', () => {
+    for (const input of [
+      { contentType: 'text', tokenEstimate: 1 },
+      { contentType: 'text', tokenEstimate: 99999 },
+      { contentType: 'image', modelVisionCapable: true },
+      { contentType: 'image', hasVisionModel: true },
+      { contentType: 'image' },
+      { contentType: 'pdf', modelVisionCapable: true },
+      { contentType: 'pdf' },
+      { contentType: 'binary' },
+    ]) {
+      const r = classifyAttachment(input);
+      expect(typeof r.reason).toBe('string');
+      expect(r.reason.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/services/attachments/attachmentContextBuilder.js

@@ -0,0 +1,185 @@
+/**
+ * Attachment context builder — turn-time materialization of a chat agent's
+ * active attachments, applying the per-attachment strategy.
+ *
+ *   - inline-text     → the full text in an <attached-files> <file> block
+ *   - document-recall → only the chunks relevant to the current query, pulled
+ *                       from the DocumentStore by the attachment's docId
+ *   - vision-*        → a text analysis from a (separate) vision model, when a
+ *                       visionAnalysisService is wired; otherwise a reference
+ *   - reference       → a lightweight pointer in <file-references>
+ *
+ * Output is { systemAdditions, contentBlocks }. systemAdditions is appended to
+ * the system prompt each turn (so it survives compaction by construction);
+ * contentBlocks is reserved for future native multimodal turns. Everything is
+ * best-effort: a failure on any single attachment degrades it to a reference
+ * and never breaks the turn.
+ */
+import { classifyAttachment } from './attachmentStrategy.js';
+import { inAttachmentScope } from './attachmentScope.js';
+
+/**
+ * Extract the most recent user message text from a conversation array, to use
+ * as the recall/vision focus query. Handles both string content and multimodal
+ * content arrays. Returns '' when there's no usable user text.
+ * @param {Array} messages
+ * @returns {string}
+ */
+export function latestUserQuery(messages) {
+  if (!Array.isArray(messages)) return '';
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (!m || m.role !== 'user') continue;
+    if (typeof m.content === 'string') return m.content;
+    if (Array.isArray(m.content)) {
+      const t = m.content.find((c) => c && c.type === 'text' && typeof c.text === 'string');
+      return t ? t.text : '';
+    }
+    return '';
+  }
+  return '';
+}
+
+const escapeXml = (t) => String(t ?? '')
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;');
+
+export class AttachmentContextBuilder {
+  constructor({ attachmentService, documentMemory = null, visionAnalysisService = null, classify = classifyAttachment, logger = null } = {}) {
+    this.attachmentService = attachmentService;
+    this.documentMemory = documentMemory;
+    this.visionAnalysisService = visionAnalysisService;
+    this.classify = classify;
+    this.logger = logger;
+  }
+
+  /**
+   * @param {string} agentId
+   * @param {Object} [opts]
+   * @param {string} [opts.query] - recent user text, used for recall + vision focus
+   * @param {Object} [opts.model] - { visionCapable } of the active chat model
+   * @param {number} [opts.recallTopK]
+   * @param {Object} [opts.thresholds] - strategy threshold overrides
+   * @returns {Promise<{systemAdditions: string, contentBlocks: Array}>}
+   */
+  async build(agentId, { query = '', model = {}, recallTopK = 5, thresholds, conversationId = null } = {}) {
+    const out = { systemAdditions: '', contentBlocks: [] };
+    if (!this.attachmentService || !agentId) return out;
+
+    let active;
+    try {
+      active = await this.attachmentService.getActiveAttachments(agentId);
+    } catch (err) {
+      this.logger?.warn?.('[attachmentContext] getActiveAttachments failed', { agentId, error: err?.message });
+      return out;
+    }
+    // Scope filter: agent-wide attachments always apply; conversation-scoped
+    // ones only on their own conversation.
+    active = (active || []).filter((a) => inAttachmentScope(a, { conversationId }));
+    if (active.length === 0) return out;
+
+    const hasVisionModel = model.hasVisionModel ?? (this.visionAnalysisService?.hasVisionModel?.() ?? false);
+    const files = [];
+    const refs = [];
+
+    for (const a of active) {
+      const { strategy } = this.classify({
+        contentType: a.contentType,
+        byteSize: a.size,
+        tokenEstimate: a.tokenEstimate,
+        modelVisionCapable: !!model.visionCapable,
+        hasVisionModel,
+      }, thresholds);
+
+      if (strategy === 'inline-text') {
+        const content = await this._content(a.fileId);
+        if (content) files.push(this._fileBlock(a, escapeXml(content), 'content'));
+        else refs.push(this._refBlock(a, 'content unavailable'));
+      } else if (strategy === 'document-recall') {
+        const excerpts = await this._recall(agentId, a, query, recallTopK);
+        if (excerpts) {
+          files.push(this._fileBlock(a, excerpts, 'recall'));
+        } else {
+          // Not indexed yet / no query / embeddings off → inline the full
+          // content so the model still sees it (no regression vs. the previous
+          // always-inline behavior). Recall is the optimization, not a gate.
+          const content = await this._content(a.fileId);
+          if (content) files.push(this._fileBlock(a, escapeXml(content), 'content'));
+          else refs.push(this._refBlock(a, 'content unavailable'));
+        }
+      } else if (strategy === 'vision-native' || strategy === 'vision-analyze') {
+        const analysis = await this._analyze(a, query);
+        if (analysis) files.push(this._fileBlock(a, analysis, 'vision'));
+        else refs.push(this._refBlock(a, 'image attached — vision analysis unavailable'));
+      } else {
+        refs.push(this._refBlock(a));
+      }
+    }
+
+    const parts = [];
+    if (files.length) parts.push(`<attached-files>\n${files.join('\n')}\n</attached-files>`);
+    if (refs.length) {
+      parts.push(`<file-references>\n${refs.join('\n')}\n</file-references>`);
+      parts.push('Note: referenced files can be read with the filesystem/recall tools if needed.');
+    }
+    /* istanbul ignore next: active is non-empty here, so a strategy always pushed to files or refs */
+    if (parts.length) out.systemAdditions = `\n${parts.join('\n')}\n`;
+    return out;
+  }
+
+  async _content(fileId) {
+    try {
+      return await this.attachmentService.getAttachmentContent(fileId);
+    } catch {
+      return null;
+    }
+  }
+
+  async _recall(agentId, a, query, topK) {
+    if (!this.documentMemory || !a.docId || !query || !query.trim()) return null;
+    try {
+      const { hits } = await this.documentMemory.recall(agentId, query, { docId: a.docId, topK });
+      const texts = (hits || []).map((h) => h && h.text).filter(Boolean);
+      if (texts.length === 0) return null;
+      return `[relevant excerpts]\n${texts.map(escapeXml).join('\n---\n')}`;
+    } catch (err) {
+      this.logger?.warn?.('[attachmentContext] recall failed', { docId: a.docId, error: err?.message });
+      return null;
+    }
+  }
+
+  async _analyze(a, query) {
+    if (!this.visionAnalysisService) return null;
+    const dataUri = await this._content(a.fileId);
+    if (!dataUri) return null;
+    const m = /^data:([^;]+);base64,(.*)$/s.exec(dataUri);
+    const mimeType = m ? m[1] : (a.fileType || 'image/png');
+    const imageBase64 = m ? m[2] : dataUri;
+    const focus = query && query.trim() ? `In the context of "${query.trim()}", ` : '';
+    const prompt = `${focus}describe this image, transcribe any text, and list the key objects.`;
+    try {
+      const res = await this.visionAnalysisService.analyze({ imageBase64, mimeType, prompt });
+      return res && res.text ? `[vision analysis]\n${escapeXml(res.text)}` : null;
+    } catch (err) {
+      this.logger?.warn?.('[attachmentContext] vision analysis failed', { fileId: a.fileId, error: err?.message });
+      return null;
+    }
+  }
+
+  _typeOf(a) {
+    return escapeXml(a.fileType || a.contentType || '');
+  }
+
+  _fileBlock(a, body, mode) {
+    const sizeKB = ((a.size || 0) / 1024).toFixed(1);
+    return `  <file name="${escapeXml(a.fileName)}" type="${this._typeOf(a)}" size="${sizeKB}KB" mode="${mode}">\n${body}\n  </file>`;
+  }
+
+  _refBlock(a, note) {
+    const pathAttr = a.originalPath ? ` path="${escapeXml(a.originalPath)}"` : '';
+    const noteAttr = note ? ` note="${escapeXml(note)}"` : '';
+    return `  <file name="${escapeXml(a.fileName)}"${pathAttr} type="${this._typeOf(a)}" mode="reference"${noteAttr} />`;
+  }
+}
+
+export default AttachmentContextBuilder;

package/src/services/attachments/attachmentIngestionService.js

@@ -0,0 +1,131 @@
+/**
+ * Attachment ingestion — the single, binary-safe entry point for chat
+ * attachments.
+ *
+ * The legacy browser path read files with FileReader.readAsText and shipped a
+ * UTF-8 string, which corrupted every non-text file (images, PDFs, …). This
+ * service accepts the actual bytes as base64, decodes them to a Buffer, and
+ * writes a temporary file in BINARY mode before handing off to the existing
+ * FileAttachmentService (which validates, hashes, extracts/encodes, and stores
+ * under the persistent attachments dir). Server-side files (from the file
+ * picker) are passed straight through by path.
+ *
+ * Dependency-injected (fileAttachmentService / fs / tempDir / id generator) so
+ * it is fully unit-testable without touching disk.
+ */
+
+import path from 'path';
+import os from 'os';
+import { promises as realFs } from 'fs';
+import { randomUUID } from 'crypto';
+import { classifyAttachment } from './attachmentStrategy.js';
+
+/** Strip path separators so a client-supplied name can't escape the temp dir. */
+export function safeBaseName(fileName) {
+  const base = path.basename(String(fileName || '').trim());
+  // Drop anything that isn't a sane filename char; keep dots/dashes/underscores.
+  const cleaned = base.replace(/[^\w.\-]+/g, '_').replace(/^\.+/, '');
+  return cleaned || 'upload';
+}
+
+export class AttachmentIngestionService {
+  constructor({ fileAttachmentService, documentMemory = null, classify = classifyAttachment, fs = realFs, tempDir = null, idgen = randomUUID, logger = null } = {}) {
+    this.fileAttachmentService = fileAttachmentService;
+    this.documentMemory = documentMemory;
+    this.classify = classify;
+    this.fs = fs;
+    this.tempDir = tempDir || path.join(os.tmpdir(), 'loxia-attachment-ingest');
+    this.idgen = idgen;
+    this.logger = logger;
+  }
+
+  /**
+   * After a file is stored, index large text/PDF into the DocumentStore so the
+   * context builder can recall only the relevant chunks instead of injecting
+   * the whole file every turn. Best-effort: indexing failure leaves the
+   * attachment usable (just not semantically searchable). Returns metadata,
+   * augmented with { docId, indexed } when indexed.
+   * @private
+   */
+  async _afterUpload(agentId, metadata) {
+    if (!this.documentMemory || !metadata) return metadata;
+    const { strategy } = this.classify({
+      contentType: metadata.contentType,
+      byteSize: metadata.size,
+      tokenEstimate: metadata.tokenEstimate,
+    });
+    if (strategy !== 'document-recall') return metadata;
+
+    try {
+      const content = await this.fileAttachmentService.getAttachmentContent(metadata.fileId);
+      if (!content) return metadata;
+      const { docId } = await this.documentMemory.remember(agentId, {
+        content,
+        source: metadata.fileName,
+        title: metadata.fileName,
+      });
+      await this.fileAttachmentService.updateAttachment(metadata.fileId, { docId, indexed: true });
+      return { ...metadata, docId, indexed: true };
+    } catch (err) {
+      this.logger?.warn?.('[attachmentIngestion] large-text indexing failed', {
+        fileId: metadata.fileId, error: err?.message,
+      });
+      return metadata;
+    }
+  }
+
+  /**
+   * Ingest raw uploaded bytes (base64). Binary-safe.
+   * @param {Object} opts
+   * @param {string} opts.agentId
+   * @param {string} opts.fileName
+   * @param {string} opts.dataBase64 - base64 of the file's actual bytes
+   * @param {string} [opts.mode] - 'content' | 'reference' (default 'content')
+   * @returns {Promise<Object>} attachment metadata (from FileAttachmentService)
+   */
+  async ingestUpload({ agentId, fileName, dataBase64, mode = 'content', scope = 'agent', conversationId = null }) {
+    if (!agentId) throw new Error('agentId is required');
+    if (!fileName) throw new Error('fileName is required');
+    if (typeof dataBase64 !== 'string' || dataBase64.length === 0) {
+      throw new Error('dataBase64 is required');
+    }
+
+    // Accept either a bare base64 string or a data: URI.
+    const comma = dataBase64.indexOf(',');
+    const b64 = dataBase64.startsWith('data:') && comma !== -1 ? dataBase64.slice(comma + 1) : dataBase64;
+    const buffer = Buffer.from(b64, 'base64');
+
+    await this.fs.mkdir(this.tempDir, { recursive: true });
+    const tmpPath = path.join(this.tempDir, `${this.idgen()}-${safeBaseName(fileName)}`);
+
+    // BINARY write — no 'utf8'. This is the corruption fix.
+    await this.fs.writeFile(tmpPath, buffer);
+
+    let metadata;
+    try {
+      metadata = await this.fileAttachmentService.uploadFile({ agentId, filePath: tmpPath, mode, fileName, scope, conversationId });
+    } finally {
+      // Best-effort cleanup of the staging file (the store keeps its own copy).
+      try { await this.fs.unlink(tmpPath); } catch { /* already gone — fine */ }
+    }
+    return this._afterUpload(agentId, metadata);
+  }
+
+  /**
+   * Ingest a file that already lives on the server (file-picker path).
+   * @param {Object} opts
+   * @param {string} opts.agentId
+   * @param {string} opts.filePath
+   * @param {string} [opts.mode]
+   * @param {string} [opts.fileName]
+   * @returns {Promise<Object>} attachment metadata
+   */
+  async ingestServerPath({ agentId, filePath, mode = 'content', fileName = null, scope = 'agent', conversationId = null }) {
+    if (!agentId) throw new Error('agentId is required');
+    if (!filePath) throw new Error('filePath is required');
+    const metadata = await this.fileAttachmentService.uploadFile({ agentId, filePath, mode, fileName, scope, conversationId });
+    return this._afterUpload(agentId, metadata);
+  }
+}
+
+export default AttachmentIngestionService;

package/src/services/attachments/attachmentScope.js

@@ -0,0 +1,22 @@
+/**
+ * Attachment scope — pure predicate deciding whether an attachment applies to
+ * the current turn.
+ *
+ *   - 'agent' (default / legacy): always in scope — persistent for the agent.
+ *   - 'conversation': in scope only when its conversationId matches the current
+ *     conversation (sessionId), so a file attached in one chat doesn't pollute
+ *     unrelated later turns.
+ *
+ * Backward compatible: attachments with no `scope` are treated as 'agent'.
+ * Fail-open: an unrecognized scope is included rather than silently dropped.
+ */
+export function inAttachmentScope(attachment, { conversationId = null } = {}) {
+  const scope = attachment?.scope;
+  if (!scope || scope === 'agent') return true;
+  if (scope === 'conversation') {
+    return !!conversationId && attachment.conversationId === conversationId;
+  }
+  return true;
+}
+
+export default inAttachmentScope;