onbuzz 5.0.1 → 5.1.0

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

@@ -0,0 +1,140 @@
+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('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,13 @@ 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 {
+  maybeOffloadToolResult,
+  DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD,
+} from './toolResultOffload.js';
 
 /**
  * True iff `text` contains the digit sequence `code` not flanked by other
@@ -173,6 +180,62 @@ 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;
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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 +1094,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 +1164,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 +1376,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);
@@ -1777,6 +1856,41 @@ class AgentScheduler {
    * @returns {Promise<Object|null>} AI response or null if failed
    * @private
    */
+  /**
+   * Decide what to send when an agent's PERSISTED conversation is empty
+   * but the scheduler still picked it up (AGENT mode with pending tasks, or
+   * residual TTL). Without this, getMessagesForAI() returns [] and the AI
+   * service throws "No messages to send - messages array is empty" every
+   * cycle — a visible, recurring error stream that never makes progress.
+   *
+   * Returns:
+   *   - a one-element kickoff message array (transient, NOT persisted) when
+   *     the agent is in AGENT mode and has at least one actionable
+   *     (pending/in-progress) task — so the model can start its task list;
+   *   - null otherwise, signalling the caller to skip the AI request and
+   *     leave the agent idle until real work arrives.
+   *
+   * Pure + side-effect-free → unit-testable in isolation.
+   *
+   * @param {Object} agent
+   * @returns {Array<{role:string,content:string}>|null}
+   */
+  _resolveEmptyConversationMessages(agent) {
+    const tasks = agent?.taskList?.tasks || [];
+    const hasActionableTask = tasks.some(
+      (t) => t && (t.status === 'pending' || t.status === 'in_progress')
+    );
+    if (agent?.mode === AGENT_MODES.AGENT && hasActionableTask) {
+      return [{
+        role: MESSAGE_ROLES.USER,
+        content:
+          'Begin working on your pending tasks. Review your task list with the ' +
+          'TaskManager tool and proceed with the next actionable task.',
+      }];
+    }
+    return null;
+  }
+
   async getAgentAIResponse(agentId) {
     try {
       const agent = await this.agentPool.getAgent(agentId);
@@ -1965,7 +2079,28 @@ class AgentScheduler {
       }
 
       // After compaction, retrieve messages from AgentPool (will use compacted if available)
-      const messagesToSend = await this.agentPool.getMessagesForAI(agentId, targetModel);
+      let messagesToSend = await this.agentPool.getMessagesForAI(agentId, targetModel);
+
+      // Empty-conversation guard. The agent can be scheduled active while its
+      // persisted conversation is empty (history cleared, imported/seeded
+      // agent, or tasks that outlived their messages). Sending [] makes the
+      // AI service throw "messages array is empty" on EVERY cycle. Resolve it
+      // deterministically: seed a transient kickoff turn when there's still
+      // actionable work, otherwise skip the doomed request and stay idle.
+      if (!messagesToSend || messagesToSend.length === 0) {
+        const seeded = this._resolveEmptyConversationMessages(agent);
+        if (!seeded) {
+          this.logger.debug(
+            `Skipping AI request for agent ${agentId}: empty conversation and no actionable tasks`
+          );
+          return null;
+        }
+        this.logger.info(
+          `Seeding kickoff turn for agent ${agentId} (empty conversation, actionable task pending)`,
+          { agentName: agent.name }
+        );
+        messagesToSend = seeded;
+      }
 
       // ── Pick the right system-prompt shape for the target model ──
       // Default: use the agent's persisted `systemPrompt` (baked at
@@ -2140,6 +2275,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
@@ -2280,15 +2447,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 {
@@ -2965,6 +3135,33 @@ class AgentScheduler {
       || errorMessage.includes('enotfound')
       || errorMessage.includes('fetch failed');
 
+    // INTERNAL client-side payload-validation failure — NOT a model/provider
+    // fault. The AI service throws "No messages to send - messages array is
+    // empty" from its own pre-flight guard when we hand it an empty array.
+    // If this falls through to the `else` (unknown) branch it gets recorded
+    // as a 'server-error' turn ATTRIBUTED TO agent.currentModel (and stamped
+    // into agent.lastError.model) and broadcast to the UI/Telegram — i.e. a
+    // perfectly good model gets "burned" for our bug. Detect it here and
+    // handle it quietly: no model-blaming failure turn, no user alarm.
+    const isInternalEmptyPayload =
+         errorMessage.includes('no messages to send')
+      || errorMessage.includes('messages array is empty');
+
+    if (isInternalEmptyPayload) {
+      // Quiet, model-agnostic handling. Deliberately does NOT call
+      // _recordAgentFailure (which would attribute the error to the model)
+      // and does NOT broadcast agent_error. A short delay prevents a hot
+      // loop if some upstream path keeps producing an empty payload.
+      this.logger.warn(
+        `Agent ${agentId} skipped a cycle: empty AI payload (internal, not a model error)`,
+        { errorMessage: error.message }
+      );
+      agent.delayEndTime = new Date(Date.now() + SCHEDULER_CONFIG.NETWORK_ERROR_DELAY_MS).toISOString();
+      await this.agentPool.persistAgentState(agentId);
+      await this.broadcastAgentStateUpdate(agentId, 'internal-empty-payload');
+      return;
+    }
+
     if (isAuthError) {
       // PERSISTENT — only the user can resolve. Long pause + broadcast so
       // the Telegram fanout (and UI banner) tell them what's wrong.

package/src/core/toolResultOffload.js

@@ -0,0 +1,131 @@
+/**
+ * Generic large-tool-output offload.
+ *
+ * The web tool already externalizes large fetched pages into the per-agent
+ * DocumentStore (see webTool._maybeOffload) so a 200 KB article never enters
+ * the conversation. But EVERY other tool — terminal, filesystem, office,
+ * desktop/foundry, etc. — still dumps its raw result verbatim into the
+ * `[Tool Results — …]` feedback message (agentScheduler.processAgentQueues →
+ * formatToolResult). A single `cat` of a big file or a chatty build log can
+ * add tens of thousands of tokens that then ride along in context every turn
+ * and force premature compaction.
+ *
+ * This module applies the SAME externalize-and-handle treatment generically,
+ * at the one chokepoint all tool results pass through. For any completed result
+ * whose serialized body exceeds a threshold, it persists the full body to the
+ * agent's DocumentStore and replaces the body with a compact preview + a
+ * recall handle. The agent can recall passages semantically or read exact
+ * lines via code-map — without the full body surviving in the conversation.
+ *
+ * Web results that the web tool already externalized are skipped (no double
+ * offload). Failed/short results are left untouched.
+ */
+
+/** 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. */
+export const DEFAULT_TOOL_OUTPUT_PREVIEW_CHARS = 1500;
+
+/**
+ * Reproduce the large-content branches of agentScheduler.formatToolResult so
+ * the threshold reflects the actual text cost the body would add to context.
+ * Only `completed` results carry potentially-large bodies; failed/other
+ * statuses render to short strings and are never worth externalizing.
+ *
+ * @param {object} toolResult
+ * @returns {string|null} the serialized body, or null if not offload-eligible.
+ */
+export function serializeToolResultBody(toolResult) {
+  if (!toolResult || toolResult.status !== 'completed') return null;
+  const r = toolResult.result;
+  if (r === undefined || r === null) return null;
+  if (typeof r === 'object') {
+    try {
+      return JSON.stringify(r, null, 2);
+    } catch {
+      return null; // circular / non-serializable → leave it to formatToolResult
+    }
+  }
+  return String(r);
+}
+
+/**
+ * Externalize a single large tool result in place. No-op (returns unchanged)
+ * when there's no document memory / agent context, the body is below
+ * threshold, the result was already externalized by its producing tool, or
+ * persistence fails. Mutates `toolResult.result` to a compact handle when it
+ * does externalize.
+ *
+ * @param {object} args
+ * @param {object} args.documentMemory  DocumentMemory instance (remember()).
+ * @param {string} args.agentId
+ * @param {object} args.toolResult       Mutated in place when externalized.
+ * @param {number} [args.threshold]
+ * @param {number} [args.previewChars]
+ * @returns {Promise<{externalized: boolean, toolResult: object}>}
+ */
+export async function maybeOffloadToolResult({
+  documentMemory,
+  agentId,
+  toolResult,
+  threshold = DEFAULT_TOOL_OUTPUT_OFFLOAD_THRESHOLD,
+  previewChars = DEFAULT_TOOL_OUTPUT_PREVIEW_CHARS,
+} = {}) {
+  if (!documentMemory || !agentId || !toolResult) {
+    return { externalized: false, toolResult };
+  }
+
+  // Skip results a producing tool already externalized (e.g. webTool sets
+  // contentExternalized; our own handle sets toolOutputExternalized).
+  const existing = toolResult.result;
+  if (
+    existing &&
+    typeof existing === 'object' &&
+    (existing.contentExternalized || existing.toolOutputExternalized)
+  ) {
+    return { externalized: false, toolResult };
+  }
+
+  const body = serializeToolResultBody(toolResult);
+  if (!body || body.length < threshold) {
+    return { externalized: false, toolResult };
+  }
+
+  const toolId = toolResult.toolId || 'tool';
+  const source = `tool://${toolId}/${toolResult.id || 'result'}`;
+
+  let handle;
+  try {
+    handle = await documentMemory.remember(agentId, {
+      source,
+      title: `${toolId} output`,
+      content: body,
+    });
+  } catch {
+    // Best-effort: a persistence failure must never drop the result — keep it
+    // inline so the agent still sees its output this turn.
+    return { externalized: false, toolResult };
+  }
+
+  toolResult.result = {
+    toolOutputExternalized: true,
+    tool: toolId,
+    preview: body.slice(0, previewChars),
+    omittedChars: Math.max(0, body.length - previewChars),
+    document: {
+      docId: handle.docId,
+      lines: handle.lines,
+      bytes: handle.bytes,
+      chunkCount: handle.chunkCount,
+      indexed: handle.indexed,
+      embeddingsEnabled: handle.embeddingsEnabled,
+    },
+    recallHint: handle.embeddingsEnabled
+      ? `Full ${toolId} output saved as document ${handle.docId} (${handle.lines} lines). Recall relevant passages semantically over your saved documents, or read exact lines with code-map read-range on the saved file.`
+      : `Full ${toolId} output saved as document ${handle.docId} (${handle.lines} lines); semantic recall is OFF (set an embeddings provider in Settings to enable search). You can still read it with code-map read-range.`,
+  };
+
+  return { externalized: true, toolResult };
+}
+
+export default { serializeToolResultBody, maybeOffloadToolResult };