onbuzz 5.0.2 → 5.3.0

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

@@ -0,0 +1,168 @@
+import { describe, test, expect, jest } from '@jest/globals';
+import {
+  serializeToolResultBody,
+  maybeOffloadToolResult,
+  DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD,
+  DEFAULT_TOOL_OUTPUT_PREVIEW_CHARS,
+} from '../toolResultOffload.js';
+
+const big = (n = DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD + 500) => 'x'.repeat(n);
+
+function fakeMemory(handle = {}) {
+  return {
+    remember: jest.fn().mockResolvedValue({
+      docId: 'doc-1',
+      lines: 42,
+      bytes: 9000,
+      chunkCount: 3,
+      indexed: true,
+      embeddingsEnabled: true,
+      ...handle,
+    }),
+  };
+}
+
+describe('serializeToolResultBody', () => {
+  test('null for non-completed / empty results', () => {
+    expect(serializeToolResultBody(null)).toBeNull();
+    expect(serializeToolResultBody({ status: 'failed', error: 'boom' })).toBeNull();
+    expect(serializeToolResultBody({ status: 'completed', result: null })).toBeNull();
+    expect(serializeToolResultBody({ status: 'completed', result: undefined })).toBeNull();
+  });
+
+  test('serializes a completed object result as pretty JSON', () => {
+    const body = serializeToolResultBody({ status: 'completed', result: { a: 1 } });
+    expect(body).toBe(JSON.stringify({ a: 1 }, null, 2));
+  });
+
+  test('stringifies a completed scalar result', () => {
+    expect(serializeToolResultBody({ status: 'completed', result: 'hello' })).toBe('hello');
+    expect(serializeToolResultBody({ status: 'completed', result: 12345 })).toBe('12345');
+  });
+
+  test('returns null when the result cannot be serialized (circular)', () => {
+    const circular = {};
+    circular.self = circular;
+    expect(serializeToolResultBody({ status: 'completed', result: circular })).toBeNull();
+  });
+});
+
+describe('maybeOffloadToolResult', () => {
+  test('no-op without document memory / agentId / toolResult', async () => {
+    expect(await maybeOffloadToolResult()).toEqual({ externalized: false, toolResult: undefined });
+    expect(await maybeOffloadToolResult({})).toEqual({ externalized: false, toolResult: undefined });
+    expect(await maybeOffloadToolResult({ documentMemory: fakeMemory(), agentId: 'a1' }))
+      .toEqual({ externalized: false, toolResult: undefined });
+    const tr = { status: 'completed', result: big() };
+    expect(await maybeOffloadToolResult({ documentMemory: fakeMemory(), toolResult: tr }))
+      .toEqual({ externalized: false, toolResult: tr });
+  });
+
+  test('skips results already externalized by their producing tool', async () => {
+    const mem = fakeMemory();
+    const webResult = { status: 'completed', toolId: 'web', result: { contentExternalized: true, x: big() } };
+    const r1 = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: webResult });
+    expect(r1.externalized).toBe(false);
+
+    const ours = { status: 'completed', toolId: 'terminal', result: { toolOutputExternalized: true, x: big() } };
+    const r2 = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: ours });
+    expect(r2.externalized).toBe(false);
+    expect(mem.remember).not.toHaveBeenCalled();
+  });
+
+  test('leaves small results inline', async () => {
+    const mem = fakeMemory();
+    const tr = { status: 'completed', toolId: 'terminal', result: 'short output' };
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(r.externalized).toBe(false);
+    expect(tr.result).toBe('short output');
+    expect(mem.remember).not.toHaveBeenCalled();
+  });
+
+  test('externalizes a large result and replaces it with a compact handle (embeddings ON)', async () => {
+    const mem = fakeMemory();
+    const body = big();
+    const tr = { id: 'res-7', status: 'completed', toolId: 'terminal', result: body };
+
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+
+    expect(r.externalized).toBe(true);
+    expect(mem.remember).toHaveBeenCalledWith('a1', {
+      source: 'tool://terminal/res-7',
+      title: 'terminal output',
+      content: body,
+    });
+    expect(tr.result.toolOutputExternalized).toBe(true);
+    expect(tr.result.tool).toBe('terminal');
+    expect(tr.result.preview).toBe(body.slice(0, DEFAULT_TOOL_OUTPUT_PREVIEW_CHARS));
+    expect(tr.result.omittedChars).toBe(body.length - DEFAULT_TOOL_OUTPUT_PREVIEW_CHARS);
+    expect(tr.result.document.docId).toBe('doc-1');
+    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() };
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(r.externalized).toBe(true);
+    expect(tr.result.recallHint).toMatch(/semantic recall is OFF/);
+  });
+
+  test('falls back to a generic source/tool label when toolId/id are absent', async () => {
+    const mem = fakeMemory();
+    const tr = { status: 'completed', result: big() };
+    await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(mem.remember).toHaveBeenCalledWith('a1', expect.objectContaining({
+      source: 'tool://tool/result',
+      title: 'tool output',
+    }));
+  });
+
+  test('keeps the result inline when persistence fails', async () => {
+    const mem = { remember: jest.fn().mockRejectedValue(new Error('disk full')) };
+    const body = big();
+    const tr = { status: 'completed', toolId: 'terminal', result: body };
+    const r = await maybeOffloadToolResult({ documentMemory: mem, agentId: 'a1', toolResult: tr });
+    expect(r.externalized).toBe(false);
+    expect(tr.result).toBe(body); // unchanged — agent still sees its output
+  });
+
+  test('respects a custom threshold/previewChars', async () => {
+    const mem = fakeMemory();
+    const tr = { status: 'completed', toolId: 'x', result: 'abcdefghij' };
+    const r = await maybeOffloadToolResult({
+      documentMemory: mem, agentId: 'a1', toolResult: tr, threshold: 5, previewChars: 3,
+    });
+    expect(r.externalized).toBe(true);
+    expect(tr.result.preview).toBe('abc');
+    expect(tr.result.omittedChars).toBe(7);
+  });
+});

package/src/core/agentPool.js

@@ -21,6 +21,56 @@ import {
 import DirectoryAccessManager from '../utilities/directoryAccessManager.js';
 import { getVisualEditorBridge } from '../services/visualEditorBridge.js';
 
+/**
+ * Capabilities that were once granted but whose backing tool has since been
+ * removed from the registry. They linger in old persisted agent state. Both
+ * tool-advertisement paths (openaiFunctionSchemas.getToolSchemasForAgent and
+ * baseTool.generateToolDescriptionsForPrompt) already filter to registered
+ * tools, so a stale name is never offered as a usable tool — BUT it can still
+ * leak verbatim into "Capabilities: …" prompt text and tempt the model to
+ * call a non-existent tool. One customer log shows `foundry_web_search` doing
+ * exactly that 58× ("Tool not found"). Strip these whenever capabilities enter
+ * an agent so old agents self-heal on load.
+ */
+export const DEPRECATED_CAPABILITIES = new Set(['foundry_web_search']);
+
+/**
+ * Capabilities whose backing tool was consolidated into another tool. Old
+ * persisted agents that reference the former toolId are migrated to the
+ * replacement so they keep working through the new surface. `doc` (DOCX) and
+ * `spreadsheet` (Excel) were merged into the single `office` tool.
+ */
+export const CAPABILITY_ALIASES = new Map([
+  ['doc', 'office'],
+  ['spreadsheet', 'office'],
+]);
+
+/**
+ * Normalize a capability list: migrate consolidated capabilities to their
+ * replacement (CAPABILITY_ALIASES), drop deprecated ones
+ * (DEPRECATED_CAPABILITIES), and de-duplicate (e.g. an agent that had both
+ * `doc` and `office` collapses to a single `office`). Returns a new array
+ * (never mutates the input); non-array input is returned unchanged so callers
+ * can pass `config.capabilities` straight through.
+ * @param {Array<string>} capabilities
+ * @returns {Array<string>}
+ */
+export function sanitizeCapabilities(capabilities) {
+  if (!Array.isArray(capabilities)) return capabilities;
+  const out = [];
+  const seen = new Set();
+  for (const cap of capabilities) {
+    const lc = String(cap).toLowerCase();
+    if (DEPRECATED_CAPABILITIES.has(lc)) continue;
+    const mapped = CAPABILITY_ALIASES.get(lc) || cap;
+    const mappedLc = String(mapped).toLowerCase();
+    if (seen.has(mappedLc)) continue;
+    seen.add(mappedLc);
+    out.push(mapped);
+  }
+  return out;
+}
+
 class AgentPool {
   // Stopwords for the _tokenize / _jaccard similarity check used by
   // auto-save-as-plan dedup. Tight list — only words that appear in
@@ -169,7 +219,7 @@ class AgentPool {
       originalSystemPrompt: config.systemPrompt, // Store original for reference
       preferredModel: config.preferredModel,
       status: AGENT_STATUS.ACTIVE,
-      capabilities: config.capabilities || [],
+      capabilities: sanitizeCapabilities(config.capabilities || []),
       directoryAccess: directoryAccess, // Directory access configuration
       // Per-tool configuration — keyed by tool id (e.g., 'terminal',
       // 'filesystem'). When a tool is instantiated for this agent, the
@@ -357,6 +407,12 @@ class AgentPool {
       });
     }
 
+    // Strip deprecated capabilities from any incoming update so they never
+    // get re-persisted (and so the regenerated prompt below is built clean).
+    if (updates.capabilities) {
+      updates.capabilities = sanitizeCapabilities(updates.capabilities);
+    }
+
     // If capabilities or system prompt are being updated, regenerate the enhanced system prompt
     if ((updates.capabilities || updates.originalSystemPrompt !== undefined) && this.toolsRegistry) {
       try {
@@ -691,6 +747,12 @@ class AgentPool {
       status: agentData.status === 'paused' && this._isPauseExpired(agentData) ? 'active' : agentData.status
     };
 
+    // Self-heal: drop deprecated capabilities (e.g. foundry_web_search) that
+    // were persisted before the backing tool was removed. Without this, old
+    // agents keep advertising a dead capability name into prompt text.
+    // sanitizeCapabilities passes a missing/non-array list through unchanged.
+    agent.capabilities = sanitizeCapabilities(agent.capabilities);
+
     // RECOVERY: If agent was paused awaiting user input (e.g., credentials),
     // the promise is now lost due to server/UI restart. Resume the agent.
     if (agent.awaitingUserInput) {

package/src/core/agentScheduler.js

@@ -35,6 +35,15 @@ import {
   getActiveAgents,
   shouldSkipIteration
 } from '../services/agentActivityService.js';
+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,
+} from './toolResultOffload.js';
 
 /**
  * True iff `text` contains the digit sequence `code` not flanked by other
@@ -173,6 +182,85 @@ class AgentScheduler {
     // Configuration from constants (no magic numbers)
     this.iterationDelayMs = SCHEDULER_CONFIG.ITERATION_DELAY_MS;
     this.maxIterationsPerCycle = SCHEDULER_CONFIG.MAX_ITERATIONS_PER_CYCLE;
+
+    // Large-tool-output offload. The web tool already externalizes big fetched
+    // pages inside itself; this handles every OTHER tool's oversized result at
+    // the single point they're rendered into the `[Tool Results]` feedback
+    // message. Lazily built (the embedding service is attached to aiService
+    // after construction). Set the threshold to Infinity to disable.
+    this.toolOutputOffloadThreshold = DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD;
+    this._toolOutputDocumentMemory = null;
+    this._attachmentContextBuilder = null;
+  }
+
+  /**
+   * Lazy accessor for the DocumentMemory used to externalize large tool
+   * outputs. Mirrors webTool._getDocumentMemory: the DocumentStore persists
+   * regardless of embeddings; the indexer no-ops when embeddings are
+   * missing/disabled, so content is always saved (just not semantically
+   * searchable until an embeddings provider is configured).
+   * @returns {DocumentMemory}
+   * @private
+   */
+  _getToolOutputDocumentMemory() {
+    if (this._toolOutputDocumentMemory) return this._toolOutputDocumentMemory;
+    const svc = this.aiService?.getEmbeddingService?.() || null;
+    const store = new DocumentStore({ logger: this.logger });
+    const indexer = new DocumentIndexer({ embeddingService: svc, logger: this.logger });
+    this._toolOutputDocumentMemory = new DocumentMemory({ store, indexer, logger: this.logger });
+    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
+   * leaves the result inline so the agent never loses its output.
+   * @param {string} agentId
+   * @param {Array<object>} results  Tool-result message objects.
+   * @private
+   */
+  async _maybeOffloadToolResults(agentId, results) {
+    if (!Array.isArray(results) || results.length === 0) return;
+    let mem;
+    try {
+      mem = this._getToolOutputDocumentMemory();
+    } catch {
+      return; // no document memory available → leave everything inline
+    }
+    for (const toolResult of results) {
+      try {
+        await maybeOffloadToolResult({
+          documentMemory: mem,
+          agentId,
+          toolResult,
+          threshold: this.toolOutputOffloadThreshold,
+        });
+      } catch {
+        /* best-effort; never block tool-result assembly */
+      }
+    }
   }
 
   /**
@@ -1031,6 +1119,7 @@ class AgentScheduler {
     const hasNewMessages = (queues.userMessages?.length > 0) || (queues.interAgentMessages?.length > 0);
     if (agent.autonomousWorkComplete && queues.toolResults?.length > 0 && hasNewMessages) {
       const staleCount = queues.toolResults.length;
+      await this._maybeOffloadToolResults(agentId, queues.toolResults);
       let boundaryContent = '[Previous Task — Final Tool Results]\n';
       queues.toolResults.forEach(msg => {
         boundaryContent += `${this.formatToolResult(msg)}\n`;
@@ -1100,6 +1189,12 @@ class AgentScheduler {
     const toolResults = allMessages.filter(m => m.queueType === 'toolResults');
     let toolResultContent = '';
     if (toolResults.length > 0) {
+      // Externalize oversized results (terminal/filesystem/office/etc.) before
+      // rendering, mirroring the web tool's own offload. Keeps giant raw dumps
+      // out of the conversation so the agent reads less, remembers more, and
+      // compacts less often.
+      await this._maybeOffloadToolResults(agentId, toolResults);
+
       // Group results by responseTurnId (the AI message that triggered them)
       const turnGroups = new Map();
       for (const msg of toolResults) {
@@ -1306,6 +1401,15 @@ class AgentScheduler {
     agent.conversations.full.messages.push(formattedMessage);
     agent.conversations.full.lastUpdated = new Date().toISOString();
 
+    // Auto-index the conversation into the reminisce surface so the agent can
+    // semantically recall past messages. Incremental + idempotent + best-effort
+    // (fire-and-forget, never blocks the turn). Reconciles the whole history
+    // against a high-water mark, so it also catches messages appended by other
+    // paths on the next call.
+    if (this.aiService?.autoIndexReminisce) {
+      Promise.resolve(this.aiService.autoIndexReminisce(agent)).catch(() => {});
+    }
+
     // Add to current model conversation if exists
     if (agent.currentModel && agent.conversations[agent.currentModel]) {
       agent.conversations[agent.currentModel].messages.push(formattedMessage);
@@ -2052,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) {
@@ -2196,6 +2306,38 @@ class AgentScheduler {
         });
       }
 
+      // ── Auto-inject SHARED user memory as ABOUT THE USER ───────────
+      // When sharedUserMemory is enabled, inject a lean, always-on block of
+      // facts about the user (e.g. their name) from the shared store — every
+      // agent, every turn, NO similarity gate. This is the reliable
+      // cross-agent path: a question rarely scores close enough to the answer
+      // for similarity recall, so identity facts live here as a persistent
+      // profile (like ChatGPT's). Best-effort; embeddings-independent (plain
+      // file read). Mirrors the plan-injection block above.
+      try {
+        const sharedOn = this.aiService?.getEmbeddingService?.()?.config?.autoRecall?.sharedUserMemory;
+        if (sharedOn) {
+          const { getMemoryService, SHARED_MEMORY_SCOPE } = await import('../services/memoryService.js');
+          const memoryService = getMemoryService(this.logger);
+          await memoryService.initialize();
+          const sharedMemories = await memoryService.loadMemories(SHARED_MEMORY_SCOPE);
+          if (sharedMemories.length > 0) {
+            const { buildUserProfileBlock } = await import('../utilities/userProfileInjection.js');
+            const { block } = buildUserProfileBlock(sharedMemories);
+            if (block) enhancedSystemPrompt = (enhancedSystemPrompt || '') + block;
+          }
+          // Formation nudge (one concise line — not a data dump): so the model
+          // actually populates the shared store as it learns things about the
+          // user. This is the natural, model-driven formation path.
+          enhancedSystemPrompt = (enhancedSystemPrompt || '') +
+            '\n\n[Shared user-memory is ON: when you learn a durable fact about the USER (e.g. their name or a stable preference), save it with the memory tool using { shared: true } so every one of the user\'s agents knows it.]';
+        }
+      } catch (profileErr) {
+        this.logger.warn(`User-profile injection failed for agent ${agentId} (continuing without)`, {
+          error: profileErr?.message,
+        });
+      }
+
       // ── Auto-inject CURRENT TASK LIST every turn ───────────────────
       // The task list lives in `agent.taskList.tasks` — durable, never
       // affected by compaction. But the conversation messages that
@@ -2336,15 +2478,18 @@ class AgentScheduler {
       // explicit primitive; this is the silent supplement. Lit-aligned
       // with the ChatGPT / Anthropic Memory shape — see Phase 6 design.
       //
-      // Best-effort: failures NEVER block the turn. Gated by:
-      //   - agent has 'memory' capability (no point recalling for an
-      //     agent that can't read/write memories)
+      // Best-effort: failures NEVER block the turn. Gated only by:
       //   - aiService.augmentSystemPrompt is present (older builds
       //     without Phase 6d skip cleanly)
       //   - the helper itself short-circuits on disabled/empty config
+      //
+      // NOTE: this is intentionally NOT gated on the 'memory' capability.
+      // Recalling an agent's OWN past conversation (the reminisce surface) is a
+      // baseline behavior every agent should have — the 'memory' capability is
+      // about the explicit memory *tool*, which is a different concern. Gating
+      // recall on it meant memory-less agents indexed their conversation but
+      // never recalled it (so they "forgot" things they were just told).
       if (
-        Array.isArray(agent.capabilities) &&
-        agent.capabilities.includes('memory') &&
         typeof this.aiService?.augmentSystemPrompt === 'function'
       ) {
         try {

package/src/core/stateManager.js

@@ -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

@@ -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;