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

onbuzz 5.1.0 → 5.4.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 (1949) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "5.1.0",
+  "version": "5.4.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/agentPool.js CHANGED Viewed

@@ -144,7 +144,8 @@ class AgentPool {
             layered: config.layeredToolDescriptions || false,
             includeExamples: config.includeToolExamples !== false,
             includeUsageGuidelines: config.includeUsageGuidelines !== false,
-            includeSecurityNotes: config.includeSecurityNotes !== false
+            includeSecurityNotes: config.includeSecurityNotes !== false,
+            mode: config.mode  // gates the jobdone must-have (AGENT mode only)
           }
         );
@@ -429,7 +430,8 @@ class AgentPool {
             compact: agent.compactToolDescriptions || false,
             includeExamples: agent.includeToolExamples !== false,
             includeUsageGuidelines: agent.includeUsageGuidelines !== false,
-            includeSecurityNotes: agent.includeSecurityNotes !== false
+            includeSecurityNotes: agent.includeSecurityNotes !== false,
+            mode: updates.mode || agent.mode  // gates the jobdone must-have
           }
         );
@@ -1341,7 +1343,8 @@ class AgentPool {
           compact: options.compact || false,
           includeExamples: options.includeExamples !== false,
           includeUsageGuidelines: options.includeUsageGuidelines !== false,
-          includeSecurityNotes: options.includeSecurityNotes !== false
+          includeSecurityNotes: options.includeSecurityNotes !== false,
+          mode: agent.mode  // gates the jobdone must-have (AGENT mode only)
         }
       );

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) {
@@ -2482,7 +2513,7 @@ class AgentScheduler {
       // them back into the CLI's inline JSON-block format on the wire. For
       // chat-completion models the backend ignores this field and the model
       // uses the system prompt's inline-JSON instructions as before.
-      const toolSchemas = getToolSchemasForAgent(agent.capabilities || []);
+      const toolSchemas = getToolSchemasForAgent(agent.capabilities || [], agent.mode);
       if (streamingEnabled && this.aiService.sendMessageStream) {
         // Build flow context if this is part of a flow execution
@@ -2610,7 +2641,7 @@ class AgentScheduler {
       let rebuilt = registry.enhanceSystemPrompt(
         agent.originalSystemPrompt,
         agent.capabilities || [],
-        { apiType: 'responses' },
+        { apiType: 'responses', mode: agent.mode },
       );
       // Re-inject ASSIGNED SKILLS block if present (createAgent appends

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,