npm - onbuzz - Versions diffs - 5.1.0 → 5.3.0 - Mend

onbuzz 5.1.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1934) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

package/scripts/gen-brand-icons.mjs ADDED Viewed

@@ -0,0 +1,21 @@
+/**
+ * Generate per-brand Electron app icons from the brand logo.
+ * Run: node scripts/gen-brand-icons.mjs
+ * Produces electron/icon-onbuzz.png (512x512, used by electron:build:onbuzz:*).
+ * The default electron/icon.png remains the Autopilot icon.
+ */
+import sharp from 'sharp';
+const SIZE = 512;
+const jobs = [
+  { src: 'web-ui/public/brands/onbuzz/logo.webp', out: 'electron/icon-onbuzz.png' },
+];
+for (const { src, out } of jobs) {
+  await sharp(src)
+    .resize(SIZE, SIZE, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+    .png()
+    .toFile(out);
+  const meta = await sharp(out).metadata();
+  console.log(`wrote ${out} (${meta.width}x${meta.height})`);
+}

package/scripts/web-automation-experiment.mjs ADDED Viewed

@@ -0,0 +1,112 @@
+/**
+ * Controlled experiment: does the tab-reuse fix make browser automation
+ * effective for a multi-turn chatbot conversation?
+ *
+ * It drives the REAL WebTool action dispatch (interactive → open-tab /
+ * switch-tab / top-level → _runActionsOnTab / executeTabAction) against a mock
+ * page that faithfully models browser semantics: page.goto() RELOADS and wipes
+ * in-page state (a chatbot's conversation lives in memory), while acting on the
+ * open page preserves it. Only the call PATTERN differs between arms.
+ *
+ * Run:  node scripts/web-automation-experiment.mjs
+ */
+import WebTool from '../src/tools/webTool.js';
+const TURNS = 6;
+const logger = { info() {}, warn() {}, error() {}, debug() {} };
+function makeChatPage() {
+  const state = { messages: [] };
+  let gotoCount = 0;
+  return {
+    state,
+    gotoCalls: () => gotoCount,
+    url: () => 'http://fixture.local/chat',
+    goto: async () => { gotoCount += 1; state.messages = []; return { status: () => 200 }; }, // reload wipes chat
+    content: async () => '<html><body>chat</body></html>',
+    close: async () => {},
+    $: async () => ({}),
+    evaluate: async (_cb, script) => {
+      if (typeof script === 'string' && script.includes('send')) {
+        state.messages.push('turn-' + (state.messages.length + 1));
+        return state.messages.length;
+      }
+      return null;
+    },
+    accessibility: { snapshot: async () => ({ role: 'WebArea', name: '', children: [
+      { role: 'textbox', name: 'Message' }, { role: 'button', name: 'Send' },
+    ] }) },
+  };
+}
+function newTool(agentId) {
+  const wt = new WebTool({}, logger);
+  wt.ensureBrowser = async () => {};
+  wt.browser = { isConnected: () => true, _stealthConfig: { stealthLevel: 'standard' } };
+  const page = makeChatPage();
+  wt.agentTabs.set(agentId, new Map([['chat', {
+    page, url: page.url(), name: 'chat', humanMode: false,
+    pageErrors: [], networkFailures: [], httpErrors: [], consoleMessages: [], lastActivity: 0,
+  }]]));
+  return { wt, page };
+}
+const run = (wt, actions, agentId) => wt.interactive(actions, { agentId, stealthLevel: 'standard', humanMode: false });
+const countErr = (r, re) => (r.results || []).filter(a => re.test(a.error || '') ||
+  (a.results || []).some(n => re.test(n.error || ''))).length;
+const CTX_ERR = /must be executed within a tab context/;
+async function arm(label, agentId, driveTurn) {
+  const { wt, page } = newTool(agentId);
+  let toolCalls = 0, ctxErrors = 0;
+  for (let i = 0; i < TURNS; i++) {
+    const r = await driveTurn(wt, agentId, i);
+    toolCalls += 1;
+    ctxErrors += countErr(r, CTX_ERR);
+  }
+  return { label, toolCalls, reloads: page.gotoCalls(), conversation: page.state.messages.length, ctxErrors };
+}
+const OLD = (wt, agentId) => run(wt, [{
+  type: 'open-tab', name: 'chat', url: 'http://fixture.local/chat',
+  nestedActions: [{ type: 'evaluate', script: 'send' }],
+}], agentId);
+const NEW = (wt, agentId, i) => (i === 0
+  ? run(wt, [{ type: 'open-tab', name: 'chat', url: 'http://fixture.local/chat', nestedActions: [{ type: 'evaluate', script: 'send' }] }], agentId)
+  // Subsequent turns: reuse the open tab (no url) — and use a TOP-LEVEL action
+  // (no wrapper) which previously errored with "must be executed within a tab context".
+  : run(wt, [{ type: 'evaluate', script: 'send' }], agentId));
+console.log(`\nControlled experiment — ${TURNS}-turn chatbot conversation\n${'='.repeat(58)}`);
+const oldArm = await arm('OLD (open-tab + url each turn)', 'old', OLD);
+const newArm = await arm('NEW (open once, then reuse tab)', 'new', NEW);
+const fmt = (a) => `${a.label.padEnd(34)} reloads=${String(a.reloads).padStart(2)}  conversation=${String(a.conversation).padStart(2)}/${TURNS}  ctxErrors=${a.ctxErrors}`;
+console.log(fmt(oldArm));
+console.log(fmt(newArm));
+const failures = [];
+if (!(oldArm.reloads === TURNS)) failures.push('expected OLD to reload every turn');
+if (!(oldArm.conversation === 1)) failures.push('expected OLD to lose conversation state (len 1)');
+if (!(newArm.reloads === 1)) failures.push('expected NEW to load exactly once');
+if (!(newArm.conversation === TURNS)) failures.push(`expected NEW to preserve all ${TURNS} turns`);
+if (!(newArm.ctxErrors === 0)) failures.push('expected NEW to have zero tab-context errors');
+console.log('\nVerdict:');
+console.log(`  • Page reloads: ${oldArm.reloads} → ${newArm.reloads}  (${Math.round((1 - newArm.reloads / oldArm.reloads) * 100)}% fewer)`);
+console.log(`  • Conversation preserved: ${oldArm.conversation}/${TURNS} → ${newArm.conversation}/${TURNS}`);
+console.log(`  • "must be executed within a tab context" errors eliminated (top-level actions now run on the active tab)`);
+console.log('\nUnder MAXIMUM stealth (headful browser + human-like delays) the win compounds:');
+console.log(`  • Each reload also incurs a human NAVIGATION delay (the most expensive step):`);
+console.log(`      navigation delays ≈ reloads: OLD ${oldArm.reloads} → NEW ${newArm.reloads}`);
+console.log(`  • Human pacing now applies ONLY to genuine input actions (click/type/…);`);
+console.log(`    observation actions (snapshot/evaluate/extract/get-*) incur ZERO delay.`);
+if (failures.length) {
+  console.error(`\n❌ EXPERIMENT FAILED:\n  - ${failures.join('\n  - ')}`);
+  process.exit(1);
+}
+console.log('\n✅ EXPERIMENT PASSED — tab reuse makes multi-turn automation effective.');

package/src/core/__tests__/stateManager.test.js CHANGED Viewed

@@ -721,4 +721,29 @@ describe('StateManager', () => {
       expect(['repaired', 'partial']).toContain(restored._restoreRecoveries[0].kind);
     });
   });
+  // ─── getAllAvailableAgents: orphan recovery count ──────────────────────
+  describe('getAllAvailableAgents recovery count', () => {
+    test('logs a numeric (not NaN) count of agents recovered from disk', async () => {
+      // Empty index + two on-disk state files not in the index → 2 recovered.
+      mockReadFile.mockResolvedValue('{}');
+      mockReaddir.mockResolvedValueOnce(['agent-aaa-state.json', 'agent-bbb-state.json', 'not-an-agent.txt']);
+      await sm.getAllAvailableAgents('/proj', null);
+      const msg = logger.info.mock.calls.map((c) => c[0]).find((m) => /Updated agent index with .* recovered agents/.test(m));
+      expect(msg).toBe('Updated agent index with 2 recovered agents');
+      expect(msg).not.toMatch(/NaN/);
+    });
+    test('does not log a recovery line when there is nothing to recover', async () => {
+      mockReadFile.mockResolvedValue('{}');
+      mockReaddir.mockResolvedValueOnce([]); // no state files
+      await sm.getAllAvailableAgents('/proj', null);
+      const msg = logger.info.mock.calls.map((c) => c[0]).find((m) => /Updated agent index with/.test(m));
+      expect(msg).toBeUndefined();
+    });
+  });
 });

package/src/core/__tests__/structuralPreview.test.js ADDED Viewed

@@ -0,0 +1,87 @@
+import { describe, test, expect } from '@jest/globals';
+import { structuralPreview, DEFAULT_PREVIEW_LIMITS } from '../structuralPreview.js';
+describe('structuralPreview — primitives & strings', () => {
+  test('passes through small primitives unchanged, untruncated', () => {
+    for (const v of [null, 0, 42, true, false, 'short']) {
+      expect(structuralPreview(v)).toEqual({ preview: v, truncated: false });
+    }
+  });
+  test('truncates a long string with a char-count marker', () => {
+    const s = 'a'.repeat(500);
+    const { preview, truncated } = structuralPreview(s, { maxStringChars: 100 });
+    expect(truncated).toBe(true);
+    expect(preview).toBe('a'.repeat(100) + '…[+400 chars]');
+  });
+  test('a string exactly at the limit is not truncated', () => {
+    const s = 'a'.repeat(DEFAULT_PREVIEW_LIMITS.maxStringChars);
+    expect(structuralPreview(s)).toEqual({ preview: s, truncated: false });
+  });
+  test('drops functions/undefined (non-JSON)', () => {
+    expect(structuralPreview(undefined).preview).toBeUndefined();
+    expect(structuralPreview(() => {}).preview).toBeUndefined();
+  });
+});
+describe('structuralPreview — arrays', () => {
+  test('keeps first N items + an omission marker', () => {
+    const { preview, truncated } = structuralPreview([1, 2, 3, 4, 5], { maxArrayItems: 2 });
+    expect(preview).toEqual([1, 2, '…[+3 more of 5 items]']);
+    expect(truncated).toBe(true);
+  });
+  test('an array within the cap is untouched', () => {
+    expect(structuralPreview([1, 2], { maxArrayItems: 3 })).toEqual({ preview: [1, 2], truncated: false });
+  });
+});
+describe('structuralPreview — objects', () => {
+  test('keeps first N keys + a marker key', () => {
+    const obj = { a: 1, b: 2, c: 3, d: 4 };
+    const { preview, truncated } = structuralPreview(obj, { maxObjectKeys: 2 });
+    expect(preview).toEqual({ a: 1, b: 2, '…': '[+2 more keys]' });
+    expect(truncated).toBe(true);
+  });
+  test('an object within the cap is untouched', () => {
+    expect(structuralPreview({ a: 1 }, { maxObjectKeys: 5 })).toEqual({ preview: { a: 1 }, truncated: false });
+  });
+});
+describe('structuralPreview — depth', () => {
+  test('depth-caps nested objects', () => {
+    const deep = { l1: { l2: { l3: 'too deep' } } };
+    const { preview, truncated } = structuralPreview(deep, { maxDepth: 2 });
+    expect(preview).toEqual({ l1: { l2: '[…nested object, depth capped]' } });
+    expect(truncated).toBe(true);
+  });
+  test('depth-caps nested arrays', () => {
+    const deep = [[['x']]];
+    const { preview, truncated } = structuralPreview(deep, { maxDepth: 2 });
+    expect(preview).toEqual([['[…1 items, depth capped]']]);
+    expect(truncated).toBe(true);
+  });
+});
+describe('structuralPreview — representative tool output (schema-agnostic)', () => {
+  test('an email-list shape collapses to a small, structure-preserving sample', () => {
+    const emails = Array.from({ length: 10 }, (_, i) => ({
+      id: `m${i}`, subject: `Subject ${i}`, from: { name: 'X', address: 'x@y.z' },
+      bodyPreview: 'short preview', body: { contentType: 'html', content: '<div>' + 'z'.repeat(50000) + '</div>' },
+    }));
+    const payload = { success: true, output: { '@odata.context': 'u'.repeat(300), value: emails } };
+    const { preview, truncated } = structuralPreview(payload);
+    expect(truncated).toBe(true);
+    // structure preserved
+    expect(preview.success).toBe(true);
+    expect(Array.isArray(preview.output.value)).toBe(true);
+    // only first N emails kept + marker
+    expect(preview.output.value.length).toBe(DEFAULT_PREVIEW_LIMITS.maxArrayItems + 1);
+    expect(preview.output.value[DEFAULT_PREVIEW_LIMITS.maxArrayItems]).toMatch(/more of 10 items/);
+    // huge body truncated, useful fields intact
+    expect(preview.output.value[0].subject).toBe('Subject 0');
+    expect(preview.output.value[0].bodyPreview).toBe('short preview');
+    expect(preview.output.value[0].body.content).toMatch(/\[\+\d+ chars\]$/);
+    // and the whole thing is now tiny
+    expect(JSON.stringify(preview).length).toBeLessThan(2000);
+  });
+});

package/src/core/__tests__/toolResultOffload.test.js CHANGED Viewed

@@ -100,6 +100,34 @@ describe('maybeOffloadToolResult', () => {
     expect(tr.result.recallHint).toMatch(/Recall relevant passages semantically/);
   });
+  test('externalizes a large OBJECT result with a schema-agnostic structural preview', async () => {
+    const mem = fakeMemory();
+    const emails = Array.from({ length: 8 }, (_, i) => ({ id: `m${i}`, subject: `S${i}`, body: { content: 'z'.repeat(20000) } }));
+    const tr = { id: 'res-9', status: 'completed', toolId: 'composio', result: { success: true, output: { value: emails } } };
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(r.externalized).toBe(true);
+    // Full payload offloaded losslessly.
+    expect(mem.remember).toHaveBeenCalledWith('a1', expect.objectContaining({ source: 'tool://composio/res-9' }));
+    // Inline preview is the structural clone (not a raw head-slice) — structure preserved, tiny.
+    expect(tr.result.toolOutputExternalized).toBe(true);
+    expect(tr.result.resultsTruncated).toBe(true);
+    expect(typeof tr.result.preview).toBe('object');
+    expect(tr.result.preview.success).toBe(true);
+    expect(tr.result.preview.output.value[0].subject).toBe('S0');
+    expect(JSON.stringify(tr.result.preview).length).toBeLessThan(2000);
+    expect(tr.result.omittedChars).toBeGreaterThan(100000);
+  });
+  test('string results keep the leading-chars preview (resultsTruncated set)', async () => {
+    const mem = fakeMemory();
+    const tr = { status: 'completed', toolId: 'terminal', result: big() };
+    await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(typeof tr.result.preview).toBe('string');
+    expect(tr.result.resultsTruncated).toBe(true);
+  });
   test('recallHint reflects embeddings OFF', async () => {
     const mem = fakeMemory({ embeddingsEnabled: false, indexed: false });
     const tr = { status: 'completed', toolId: 'filesystem', result: big() };

package/src/core/agentScheduler.js CHANGED Viewed

@@ -38,6 +38,8 @@ import {
 import { DocumentStore } from '../services/documents/documentStore.js';
 import { DocumentMemory } from '../services/documents/documentMemory.js';
 import { DocumentIndexer } from '../services/embeddings/indexers/documentIndexer.js';
+import { AttachmentContextBuilder, latestUserQuery } from '../services/attachments/attachmentContextBuilder.js';
+import { VisionAnalysisService } from '../services/vision/visionAnalysisService.js';
 import {
   maybeOffloadToolResult,
   DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD,
@@ -188,6 +190,7 @@ class AgentScheduler {
     // after construction). Set the threshold to Infinity to disable.
     this.toolOutputOffloadThreshold = DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD;
     this._toolOutputDocumentMemory = null;
+    this._attachmentContextBuilder = null;
   }
   /**
@@ -208,6 +211,28 @@ class AgentScheduler {
     return this._toolOutputDocumentMemory;
   }
+  /**
+   * Lazy accessor for the strategy-aware attachment context builder. Reuses the
+   * ContextInjectionService's FileAttachmentService (same attachments the old
+   * injector read) and the tool-output DocumentMemory for large-file recall.
+   * @returns {AttachmentContextBuilder}
+   * @private
+   */
+  _getAttachmentContextBuilder() {
+    if (this._attachmentContextBuilder) return this._attachmentContextBuilder;
+    this._attachmentContextBuilder = new AttachmentContextBuilder({
+      attachmentService: this.contextInjectionService?.attachmentService,
+      documentMemory: this._getToolOutputDocumentMemory(),
+      visionAnalysisService: new VisionAnalysisService({
+        aiService: this.aiService,
+        modelsService: this.modelsService,
+        logger: this.logger,
+      }),
+      logger: this.logger,
+    });
+    return this._attachmentContextBuilder;
+  }
   /**
    * Externalize any oversized results in `results` in place before they are
    * rendered into a tool-results feedback message. Best-effort: any failure
@@ -2131,13 +2156,19 @@ class AgentScheduler {
         // Note: Consecutive no-tool reminders are now sent as tool results (see _processAIResponse)
       }
-      // Inject dynamic file attachment context
+      // Inject dynamic file attachment context — strategy-aware: small text is
+      // inlined, large text is recalled (relevant chunks only) by the current
+      // query, images become references/analysis. Falls back to inline content
+      // when recall is unavailable, so there's no regression vs. the previous
+      // always-inline injector. Rebuilt every turn from the persistent store →
+      // survives compaction.
       try {
-        const fileAttachmentContext = await this.contextInjectionService.buildDynamicContext(agentId);
-        if (fileAttachmentContext) {
-          enhancedSystemPrompt = (enhancedSystemPrompt || '') + fileAttachmentContext;
+        const query = latestUserQuery(messagesToSend);
+        const { systemAdditions } = await this._getAttachmentContextBuilder().build(agentId, { query, conversationId: sessionId });
+        if (systemAdditions) {
+          enhancedSystemPrompt = (enhancedSystemPrompt || '') + systemAdditions;
           this.logger.debug(`Injected file attachment context for agent ${agentId}`, {
-            contextLength: fileAttachmentContext.length
+            contextLength: systemAdditions.length
           });
         }
       } catch (error) {

package/src/core/stateManager.js CHANGED Viewed

@@ -1572,6 +1572,7 @@ class StateManager {
         const stateFiles = files.filter(f => f.endsWith('-state.json'));
         let indexUpdated = false;
+        let recoveredCount = 0;
         for (const stateFile of stateFiles) {
           // Extract agent ID from filename: agent-{agentId}-state.json
@@ -1617,6 +1618,7 @@ class StateManager {
               capabilities: agentInfo.capabilities
             };
             indexUpdated = true;
+            recoveredCount++;
             this.logger.info(`Recovered agent from disk: ${agentInfo.name} (${agentId})`);
           } catch (err) {
@@ -1628,7 +1630,7 @@ class StateManager {
         if (indexUpdated) {
           const indexFile = path.join(this.stateDirectory, this.stateFiles.agentIndex);
           await this.saveJSON(indexFile, agentIndex);
-          this.logger.info(`Updated agent index with ${agents.length - Object.keys(agentIndex).length + Object.keys(processedAgentIds).size} recovered agents`);
+          this.logger.info(`Updated agent index with ${recoveredCount} recovered agents`);
         }
       } catch (err) {
         this.logger.warn(`Failed to scan agents directory: ${err.message}`);

package/src/core/structuralPreview.js ADDED Viewed

@@ -0,0 +1,79 @@
+/**
+ * Schema-agnostic structural preview of an arbitrary JSON value.
+ *
+ * Produces a compact, representative clone by applying uniform caps — long
+ * strings are truncated, long arrays keep their first N items, wide objects
+ * keep their first N keys, and recursion is depth-bounded. The full key
+ * SKELETON is preserved so an agent sees what fields exist plus sample values,
+ * regardless of the tool that produced it (emails, GitHub issues, Sheets rows,
+ * Drive files — any shape). No field-name assumptions, so it fits every
+ * Composio toolkit (and every tool) identically.
+ *
+ * Pairs with the lossless tool-output offload: the FULL payload is persisted to
+ * the document store; this preview is what goes inline, with `truncated`
+ * signalling that the rest is retrievable via recall / read-range.
+ */
+export const DEFAULT_PREVIEW_LIMITS = {
+  maxArrayItems: 3,   // keep the first N items of any array
+  maxStringChars: 200, // truncate any string longer than this
+  maxObjectKeys: 30,  // keep the first N keys of any object
+  maxDepth: 6,        // stop descending past this depth
+};
+/**
+ * @param {*} value - any JSON-ish value
+ * @param {Partial<typeof DEFAULT_PREVIEW_LIMITS>} [limits]
+ * @returns {{ preview: *, truncated: boolean }}
+ */
+export function structuralPreview(value, limits = {}) {
+  const L = { ...DEFAULT_PREVIEW_LIMITS, ...limits };
+  let truncated = false;
+  function walk(v, depth) {
+    if (v === null || typeof v === 'number' || typeof v === 'boolean') return v;
+    if (typeof v === 'string') {
+      if (v.length > L.maxStringChars) {
+        truncated = true;
+        return `${v.slice(0, L.maxStringChars)}…[+${v.length - L.maxStringChars} chars]`;
+      }
+      return v;
+    }
+    if (Array.isArray(v)) {
+      if (depth >= L.maxDepth) {
+        truncated = true;
+        return `[…${v.length} items, depth capped]`;
+      }
+      const out = v.slice(0, L.maxArrayItems).map((x) => walk(x, depth + 1));
+      if (v.length > L.maxArrayItems) {
+        truncated = true;
+        out.push(`…[+${v.length - L.maxArrayItems} more of ${v.length} items]`);
+      }
+      return out;
+    }
+    if (typeof v === 'object') {
+      if (depth >= L.maxDepth) {
+        truncated = true;
+        return '[…nested object, depth capped]';
+      }
+      const keys = Object.keys(v);
+      const out = {};
+      for (const k of keys.slice(0, L.maxObjectKeys)) out[k] = walk(v[k], depth + 1);
+      if (keys.length > L.maxObjectKeys) {
+        truncated = true;
+        out['…'] = `[+${keys.length - L.maxObjectKeys} more keys]`;
+      }
+      return out;
+    }
+    // functions / undefined / symbol — not valid JSON tool output; drop.
+    return undefined;
+  }
+  return { preview: walk(value, 0), truncated };
+}
+export default structuralPreview;

package/src/core/toolResultOffload.js CHANGED Viewed

@@ -21,6 +21,8 @@
  * offload). Failed/short results are left untouched.
  */
+import { structuralPreview } from './structuralPreview.js';
 /** Default body size (chars) above which a tool result is externalized. */
 export const DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD = 6000;
 /** How many leading chars of the body to keep inline as a preview. */
@@ -90,6 +92,7 @@ export async function maybeOffloadToolResult({
   if (!body || body.length < threshold) {
     return { externalized: false, toolResult };
   }
+  const original = toolResult.result;
   const toolId = toolResult.toolId || 'tool';
   const source = `tool://${toolId}/${toolResult.id || 'result'}`;
@@ -107,11 +110,29 @@ export async function maybeOffloadToolResult({
     return { externalized: false, toolResult };
   }
+  // Build the inline preview. For STRUCTURED results, a schema-agnostic
+  // structural preview (caps arrays/strings/keys, preserves the skeleton) is
+  // far more representative than the head-of-JSON slice — it shows every field
+  // and a sample of items for ANY tool/shape. Scalar/string results keep the
+  // leading-chars slice. The full body is offloaded either way (lossless).
+  let preview;
+  let resultsTruncated;
+  if (original && typeof original === 'object') {
+    const sp = structuralPreview(original);
+    preview = sp.preview;
+    resultsTruncated = sp.truncated;
+  } else {
+    preview = body.slice(0, previewChars);
+    resultsTruncated = body.length > previewChars;
+  }
+  const previewChars2 = typeof preview === 'string' ? preview.length : JSON.stringify(preview).length;
   toolResult.result = {
     toolOutputExternalized: true,
     tool: toolId,
-    preview: body.slice(0, previewChars),
-    omittedChars: Math.max(0, body.length - previewChars),
+    preview,
+    resultsTruncated,
+    omittedChars: Math.max(0, body.length - previewChars2),
     document: {
       docId: handle.docId,
       lines: handle.lines,

package/src/interfaces/__tests__/attachmentRoutes.test.js ADDED Viewed

@@ -0,0 +1,118 @@
+import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import { registerAttachmentRoutes } from '../attachmentRoutes.js';
+async function post(url, body) {
+  const resp = await globalThis.fetch(url, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body || {}),
+  });
+  const ct = resp.headers.get('content-type') || '';
+  return { status: resp.status, body: ct.includes('json') ? await resp.json() : await resp.text() };
+}
+function startApp(getIngestionService) {
+  const app = express();
+  // NOTE: deliberately NO global express.json — the route mounts its own parser.
+  registerAttachmentRoutes(app, { getIngestionService, logger: { error: jest.fn() } });
+  const server = createServer(app);
+  return new Promise((r) => server.listen(0, () => r({ server, baseUrl: `http://localhost:${server.address().port}` })));
+}
+let ingestion;
+beforeEach(() => {
+  ingestion = {
+    ingestUpload: jest.fn().mockResolvedValue({ fileId: 'f1', fileName: 'pic.png' }),
+    ingestServerPath: jest.fn().mockResolvedValue({ fileId: 'f2', fileName: 'doc.pdf' }),
+  };
+});
+describe('POST /api/agents/:id/attachments', () => {
+  let server, baseUrl;
+  beforeEach(async () => { ({ server, baseUrl } = await startApp(() => ingestion)); });
+  afterEach(() => server?.close());
+  it('routes a base64 upload to ingestUpload', async () => {
+    const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'pic.png', dataBase64: 'AAAA', mode: 'content' });
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ success: true, attachment: { fileId: 'f1', fileName: 'pic.png' } });
+    expect(ingestion.ingestUpload).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'a1', fileName: 'pic.png', dataBase64: 'AAAA', mode: 'content' }));
+    expect(ingestion.ingestServerPath).not.toHaveBeenCalled();
+  });
+  it('routes a server filePath to ingestServerPath', async () => {
+    const r = await post(`${baseUrl}/api/agents/a1/attachments`, { filePath: '/srv/doc.pdf', fileName: 'doc.pdf' });
+    expect(r.status).toBe(200);
+    expect(r.body.attachment.fileId).toBe('f2');
+    expect(ingestion.ingestServerPath).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'a1', filePath: '/srv/doc.pdf', fileName: 'doc.pdf' }));
+  });
+  it('forwards scope + conversationId to ingestion', async () => {
+    await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA', scope: 'conversation', conversationId: 'c1' });
+    expect(ingestion.ingestUpload).toHaveBeenCalledWith(expect.objectContaining({ scope: 'conversation', conversationId: 'c1' }));
+  });
+  it('prefers dataBase64 over filePath when both are present', async () => {
+    await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA', filePath: '/srv/x' });
+    expect(ingestion.ingestUpload).toHaveBeenCalledTimes(1);
+    expect(ingestion.ingestServerPath).not.toHaveBeenCalled();
+  });
+  it('400s when neither source is provided', async () => {
+    const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x' });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toMatch(/Provide dataBase64.*or filePath/);
+  });
+  it('400s with the error message when ingestion throws (validation)', async () => {
+    ingestion.ingestUpload.mockRejectedValueOnce(new Error('Executable files (.exe) are not allowed'));
+    const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'm.exe', dataBase64: 'AA' });
+    expect(r.status).toBe(400);
+    expect(r.body).toMatchObject({ success: false, error: /not allowed/ });
+  });
+});
+describe('service-absent + defensive', () => {
+  it('503 when the ingestion service is not wired yet (boot ordering)', async () => {
+    const { server, baseUrl } = await startApp(() => null);
+    try {
+      const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA' });
+      expect(r.status).toBe(503);
+    } finally { server.close(); }
+  });
+  it('503 when no thunk is supplied at all', async () => {
+    const { server, baseUrl } = await startApp(undefined);
+    try {
+      expect((await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA' })).status).toBe(503);
+    } finally { server.close(); }
+  });
+  it('no-ops when app is null (with and without an options object)', () => {
+    expect(() => registerAttachmentRoutes(null, {})).not.toThrow();
+    expect(() => registerAttachmentRoutes(undefined)).not.toThrow(); // default {} options arm
+  });
+  it('handles a request whose body the JSON parser left unset (non-JSON content-type)', async () => {
+    const { server, baseUrl } = await startApp(() => ingestion);
+    try {
+      const resp = await globalThis.fetch(`${baseUrl}/api/agents/a1/attachments`, {
+        method: 'POST', headers: { 'content-type': 'text/plain' }, body: 'not json',
+      });
+      expect(resp.status).toBe(400); // req.body || {} → no source → 400, no crash
+    } finally { server.close(); }
+  });
+  it('works with no logger supplied (uses the no-op fallback) on the error path', async () => {
+    const ing = { ingestUpload: jest.fn().mockRejectedValue(new Error('boom')), ingestServerPath: jest.fn() };
+    const app = express();
+    registerAttachmentRoutes(app, { getIngestionService: () => ing }); // no logger
+    const server = createServer(app);
+    await new Promise((r) => server.listen(0, r));
+    const baseUrl = `http://localhost:${server.address().port}`;
+    try {
+      const r = await post(`${baseUrl}/api/agents/a1/attachments`, { fileName: 'x', dataBase64: 'AA' });
+      expect(r.status).toBe(400); // error path ran through the no-op logger without throwing
+    } finally { server.close(); }
+  });
+});