onbuzz 4.8.3 → 4.9.1

package/src/services/__tests__/memoryService.appendAndCatalog.test.js

@@ -0,0 +1,139 @@
+/**
+ * Tests for memoryService extensions:
+ *   - appendToMemory: additive update with timestamped blocks + soft-cap
+ *     behavior (older append blocks drop, original creation content
+ *     preserved)
+ *   - getCatalog: compact, recency-sorted, archived-excluded list for
+ *     system-prompt injection
+ *
+ * Together these enable the "task-attached memory grows as agent works"
+ * pattern and the per-turn AGENT MEMORY catalog injection.
+ */
+import { describe, test, expect, beforeEach } from '@jest/globals';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import MemoryService from '../memoryService.js';
+
+let tmpDir;
+let service;
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'memsvc-test-'));
+  service = new MemoryService({
+    info(){}, warn(){}, error(){}, debug(){},
+  });
+  // Skip initialize() (which sets up production paths) and override
+  // agentsDir to a temp dir for isolation. Must set `initialized=true`
+  // so loadMemories() doesn't re-run initialize() and clobber agentsDir.
+  service.agentsDir = tmpDir;
+  service.initialized = true;
+});
+
+describe('appendToMemory', () => {
+  test('appends a timestamped block to existing content', async () => {
+    const created = await service.addMemory('agent-1', {
+      title: 'task-context/foo', content: 'Initial context.',
+    });
+    const updated = await service.appendToMemory('agent-1', created.id, 'Finding: API uses bearer tokens.');
+    expect(updated).not.toBeNull();
+    expect(updated.content).toContain('Initial context.');
+    expect(updated.content).toMatch(/## \d{4}-\d{2}-\d{2}T[\d:.]+Z — agent/);
+    expect(updated.content).toContain('Finding: API uses bearer tokens.');
+  });
+
+  test('returns null for non-existent memory id', async () => {
+    const res = await service.appendToMemory('agent-1', 'mem-nope', 'whatever');
+    expect(res).toBeNull();
+  });
+
+  test('rejects empty body (no-op)', async () => {
+    const created = await service.addMemory('agent-1', { title: 't', content: 'c' });
+    expect(await service.appendToMemory('agent-1', created.id, '')).toBeNull();
+    expect(await service.appendToMemory('agent-1', created.id, null)).toBeNull();
+  });
+
+  test('updates the updatedAt timestamp', async () => {
+    const created = await service.addMemory('agent-1', { title: 't', content: 'c' });
+    const before = created.updatedAt;
+    await new Promise(r => setTimeout(r, 10));
+    const after = await service.appendToMemory('agent-1', created.id, 'more');
+    expect(after.updatedAt).not.toBe(before);
+  });
+
+  test('SOFT CAP: when content exceeds 16K, drops the OLDEST append block (creation content preserved)', async () => {
+    const ORIGINAL = 'ORIGINAL_CONTENT_MARKER ' + 'a'.repeat(1000);
+    const mem = await service.addMemory('agent-1', { title: 't', content: ORIGINAL });
+    // Append several large blocks until we go past the cap
+    for (let i = 0; i < 20; i++) {
+      await service.appendToMemory('agent-1', mem.id, `Append block ${i}: ` + 'X'.repeat(900));
+    }
+    const all = await service.loadMemories('agent-1');
+    const final = all.find(m => m.id === mem.id);
+    expect(final.content.length).toBeLessThanOrEqual(16_500); // a little slack for the cap math
+    // Original creation content MUST survive
+    expect(final.content).toContain('ORIGINAL_CONTENT_MARKER');
+    // Most recent append must survive
+    expect(final.content).toContain('Append block 19');
+    // Earliest append should have been dropped
+    expect(final.content).not.toContain('Append block 0:');
+  });
+});
+
+describe('getCatalog', () => {
+  test('returns empty catalog when no memories exist', async () => {
+    const cat = await service.getCatalog('agent-1');
+    expect(cat.entries).toEqual([]);
+    expect(cat.total).toBe(0);
+  });
+
+  test('lists memories sorted newest-first by updatedAt', async () => {
+    const m1 = await service.addMemory('agent-1', { title: 'first', content: 'a' });
+    await new Promise(r => setTimeout(r, 10));
+    const m2 = await service.addMemory('agent-1', { title: 'second', content: 'b' });
+    const cat = await service.getCatalog('agent-1');
+    expect(cat.entries).toHaveLength(2);
+    expect(cat.entries[0].id).toBe(m2.id);  // newest first
+    expect(cat.entries[1].id).toBe(m1.id);
+  });
+
+  test('caps at the requested limit and reports total', async () => {
+    for (let i = 0; i < 25; i++) {
+      await service.addMemory('agent-1', { title: `m-${i}`, content: 'x' });
+    }
+    const cat = await service.getCatalog('agent-1', 10);
+    expect(cat.entries).toHaveLength(10);
+    expect(cat.total).toBe(25);
+  });
+
+  test('excludes memories with archived=true', async () => {
+    const m1 = await service.addMemory('agent-1', { title: 'visible', content: 'a' });
+    const m2 = await service.addMemory('agent-1', { title: 'hidden',  content: 'b' });
+    // Manually archive m2 by direct file mutation (no archive API yet)
+    const all = await service.loadMemories('agent-1');
+    const idx = all.findIndex(m => m.id === m2.id);
+    all[idx].archived = true;
+    await service.saveMemories('agent-1', all);
+
+    const cat = await service.getCatalog('agent-1');
+    expect(cat.entries.map(e => e.id)).toContain(m1.id);
+    expect(cat.entries.map(e => e.id)).not.toContain(m2.id);
+    expect(cat.total).toBe(1);
+  });
+
+  test('catalog entries are compact: id, title, short description, updatedAt', async () => {
+    const m = await service.addMemory('agent-1', {
+      title: 'plan/foo',
+      description: 'A short description',
+      content: 'lots of content here that should NOT appear in the catalog',
+    });
+    const cat = await service.getCatalog('agent-1');
+    expect(cat.entries[0]).toEqual({
+      id: m.id,
+      title: 'plan/foo',
+      description: 'A short description',
+      updatedAt: m.updatedAt || m.createdAt,
+    });
+    // CRITICAL: content must NOT be in the catalog (prompt-token control)
+    expect(cat.entries[0]).not.toHaveProperty('content');
+  });
+});

package/src/services/__tests__/telegramService.test.js

@@ -559,6 +559,97 @@ describe('error fan-out vs watch-gating', () => {
     expect(sent).toBeDefined();
   });
 
+  test('agent_error dedup: identical errors within the window only send once', async () => {
+    const svc = makeService();
+    const bot = await connected(svc);
+    await bot.simulateMessage(userMsg(111, '/start'));
+
+    const payload = { type: 'agent_error', agentId: 'a1', agentName: 'Cody', message: 'boom' };
+    await svc._handleBroadcastEvent(payload);
+    await svc._handleBroadcastEvent(payload);
+    await svc._handleBroadcastEvent(payload);
+    await svc._handleBroadcastEvent(payload);
+
+    const errorMessages = bot.calls.sendMessage.filter(c => c.text.includes('Agent Error'));
+    // Only the first one should have made it through; the next three are
+    // counted but suppressed.
+    expect(errorMessages).toHaveLength(1);
+    // Dedup state confirms three were absorbed.
+    const entry = [...svc._errorBroadcastDedup.values()][0];
+    expect(entry?.count).toBe(4);
+  });
+
+  test('agent_error dedup: different agents do NOT collide', async () => {
+    const svc = makeService();
+    const bot = await connected(svc);
+    await bot.simulateMessage(userMsg(111, '/start'));
+
+    await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a1', agentName: 'Cody',  message: 'same' });
+    await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a2', agentName: 'Carol', message: 'same' });
+
+    const errorMessages = bot.calls.sendMessage.filter(c => c.text.includes('Agent Error'));
+    expect(errorMessages).toHaveLength(2);
+  });
+
+  test('agent_error dedup: textual variations of same error coalesce', async () => {
+    const svc = makeService();
+    const bot = await connected(svc);
+    await bot.simulateMessage(userMsg(111, '/start'));
+
+    // Same error, formatted slightly differently — should dedup.
+    await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a1', message: 'Connection refused' });
+    await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a1', message: 'connection refused' });
+    await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a1', message: '  Connection   refused  ' });
+
+    const errorMessages = bot.calls.sendMessage.filter(c => c.text.includes('Agent Error'));
+    expect(errorMessages).toHaveLength(1);
+  });
+
+  test('agent_error dedup: window close emits a "still happening" summary when count > 1', async () => {
+    jest.useFakeTimers();
+    try {
+      const svc = makeService();
+      const bot = await connected(svc);
+      await bot.simulateMessage(userMsg(111, '/start'));
+
+      // First fires immediately, plus two suppressed.
+      await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a1', agentName: 'Cody', message: 'boom' });
+      await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a1', agentName: 'Cody', message: 'boom' });
+      await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a1', agentName: 'Cody', message: 'boom' });
+
+      // Advance past the 5-minute dedup window.
+      jest.advanceTimersByTime(5 * 60 * 1000 + 100);
+      // Let the timer callback's microtasks resolve.
+      await Promise.resolve();
+      await Promise.resolve();
+
+      const summary = bot.calls.sendMessage.find(c => c.text.includes('still happening'));
+      expect(summary).toBeDefined();
+      expect(summary.text).toMatch(/2 more/);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  test('agent_error dedup: a single error does NOT trigger a summary', async () => {
+    jest.useFakeTimers();
+    try {
+      const svc = makeService();
+      const bot = await connected(svc);
+      await bot.simulateMessage(userMsg(111, '/start'));
+
+      await svc._handleBroadcastEvent({ type: 'agent_error', agentId: 'a1', message: 'one-off' });
+      jest.advanceTimersByTime(5 * 60 * 1000 + 100);
+      await Promise.resolve();
+
+      // The original message went out. No follow-up summary.
+      const summary = bot.calls.sendMessage.find(c => c.text.includes('still happening'));
+      expect(summary).toBeUndefined();
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
   test('execution_stopped does NOT relay unless /watch is on', async () => {
     const svc = makeService();
     const bot = await connected(svc);

package/src/services/aiService.js

@@ -187,6 +187,10 @@ class AIService {
     // Agent Pool reference (will be set by LoxiaSystem)
     this.agentPool = null;
 
+    // Embedding service reference (will be set by LoxiaSystem after config).
+    // Null when embeddings are not configured / disabled.
+    this.embeddingService = null;
+
     // Active requests tracking for abort support
     // Maps agentId -> { controller: AbortController, requestId: string, startTime: Date }
     this.activeRequests = new Map();
@@ -1117,6 +1121,139 @@ class AIService {
     });
   }
 
+  /**
+   * Attach the EmbeddingService instance so consumers can reach it via
+   * `aiService.getEmbeddingService()` — mirrors the apiKeyManager wiring
+   * pattern (one central hub, services flow through it).
+   *
+   * Caller (typically LoxiaSystem at startup) constructs the
+   * EmbeddingService and hands it here. Indexers / tools then do:
+   *
+   *     const svc = aiService.getEmbeddingService();
+   *     if (svc.isEnabled) { ... } else { /_ fall back to substring _/ }
+   *
+   * @param {import('./embeddings/embeddingService.js').EmbeddingService|null} svc
+   */
+  setEmbeddingService(svc) {
+    this.embeddingService = svc;
+    this.logger?.info?.('[aiService] Embedding service attached', { enabled: !!svc?.isEnabled });
+  }
+
+  getEmbeddingService() {
+    return this.embeddingService || null;
+  }
+
+  /**
+   * Convenience embed wrapper. Most callers want this two-shape API:
+   *   await aiService.embed("a query")            // single string  → Float32Array
+   *   await aiService.embed(["a", "b"], opts)     // array of texts → Float32Array[]
+   *
+   * `kind` selects the task prefix on models that distinguish queries
+   * vs documents (nomic, BGE). Defaults to 'document' for batch input
+   * and 'query' for single-string input — the common-case mapping.
+   *
+   * Throws when embeddings are disabled or no service is attached;
+   * callers should check `getEmbeddingService()?.isEnabled` first if
+   * they have a substring fallback path.
+   *
+   * @param {string|string[]} input
+   * @param {{ kind?: 'query'|'document' }} [opts]
+   * @returns {Promise<Float32Array|Float32Array[]>}
+   */
+  async embed(input, opts = {}) {
+    if (!this.embeddingService) {
+      throw new Error('No EmbeddingService attached; call aiService.setEmbeddingService(...) at startup');
+    }
+    if (Array.isArray(input)) {
+      return this.embeddingService.embedDocuments(input, opts.kind || 'document');
+    }
+    return this.embeddingService.embedQuery(input);
+  }
+
+  /**
+   * Augment a system prompt with auto-recalled context. The message
+   * processor calls this once per turn, BEFORE handing the prompt to
+   * the LLM, when the agent has the auto-recall feature enabled.
+   *
+   * Hybrid call path: voluntary `memory.semantic-search` stays the
+   * primary retrieval primitive; this is the silent, threshold-gated
+   * supplement for "things the model probably needs to know but hasn't
+   * thought to look up." Lit-aligned with the ChatGPT / Anthropic
+   * memory shape (see Phase 6 design notes).
+   *
+   * Best-effort: when embeddings are off, when no recent text is
+   * available, when no items cross the threshold — returns the prompt
+   * unchanged. NEVER throws. Errors from individual surfaces are
+   * swallowed inside `recallForPrompt`.
+   *
+   * @param {string} systemPrompt - The pre-built system prompt for this turn.
+   * @param {string} agentId
+   * @param {string} recentText   - The user's most recent message (or
+   *        last K turns concatenated by the caller).
+   * @param {object} [opts]       - Per-turn overrides for the auto-recall
+   *        config block (threshold, topK, maxTokens, surfaces).
+   * @returns {Promise<string>}    The (possibly augmented) system prompt.
+   */
+  async augmentSystemPrompt(systemPrompt, agentId, recentText, opts = {}) {
+    if (typeof systemPrompt !== 'string') systemPrompt = '';
+    if (!this.embeddingService || !this.embeddingService.isEnabled) return systemPrompt;
+    if (typeof recentText !== 'string' || !recentText.trim()) return systemPrompt;
+
+    let recallForPrompt, formatRecallSection;
+    try {
+      ({ recallForPrompt, formatRecallSection } = await import('./embeddings/autoRecall.js'));
+    } catch (err) {
+      this.logger?.warn?.('[aiService] auto-recall module import failed', { error: err?.message });
+      return systemPrompt;
+    }
+
+    const memoryIndexer = await this._buildMemoryIndexer();
+    const reminisceIndexer = await this._buildReminisceIndexer();
+
+    const deps = {
+      getIndexers: () => ({ memory: memoryIndexer, reminisce: reminisceIndexer }),
+      getConfig:   () => this.embeddingService.config,
+    };
+
+    let result;
+    try {
+      result = await recallForPrompt(deps, agentId, recentText, opts);
+    } catch (err) {
+      this.logger?.warn?.('[aiService] auto-recall failed', { error: err?.message });
+      return systemPrompt;
+    }
+    if (!result?.items?.length) return systemPrompt;
+
+    const section = formatRecallSection(result.items);
+    return systemPrompt + (systemPrompt.endsWith('\n') ? '' : '\n') + section;
+  }
+
+  /** @private — lazy MemoryIndexer construction (async dynamic import); cached on the service. */
+  async _buildMemoryIndexer() {
+    if (this._memoryIndexerForRecall) return this._memoryIndexerForRecall;
+    if (!this.embeddingService) return null;
+    try {
+      const { MemoryIndexer } = await import('./embeddings/indexers/memoryIndexer.js');
+      this._memoryIndexerForRecall = new MemoryIndexer({ embeddingService: this.embeddingService, logger: this.logger });
+      return this._memoryIndexerForRecall;
+    } catch (_err) {
+      return null;
+    }
+  }
+
+  /** @private — lazy ReminisceIndexer construction (async dynamic import). */
+  async _buildReminisceIndexer() {
+    if (this._reminisceIndexerForRecall) return this._reminisceIndexerForRecall;
+    if (!this.embeddingService) return null;
+    try {
+      const { ReminisceIndexer } = await import('./embeddings/indexers/reminisceIndexer.js');
+      this._reminisceIndexerForRecall = new ReminisceIndexer({ embeddingService: this.embeddingService, logger: this.logger });
+      return this._reminisceIndexerForRecall;
+    } catch (_err) {
+      return null;
+    }
+  }
+
   /**
    * Abort an active request for a specific agent
    * Used when user clicks "Stop" to immediately cancel streaming

package/src/services/apiKeyManager.js

@@ -253,6 +253,34 @@ class ApiKeyManager {
     return result;
   }
 
+  /**
+   * Get the API key the embedding provider should use.
+   *
+   * @param {'azure'|'openai'|'local'|'disabled'} provider
+   * @returns {string|null}
+   *
+   * Wiring:
+   *   - 'azure'  → Loxia backend proxy → uses loxiaApiKey (same as chat)
+   *   - 'openai' → direct to api.openai.com → uses vendorKeys.openai (BYOK)
+   *   - 'local'  → fully offline → no key needed
+   *   - 'disabled' → caller shouldn't be asking → returns null
+   *
+   * Called by EmbeddingService via the `getApiKey` callback passed to
+   * each provider. Callback (not stored string) so key rotation is
+   * picked up immediately without re-instantiating providers.
+   */
+  getEmbeddingApiKey(provider) {
+    switch (provider) {
+      case 'azure':         return this.keys?.loxiaApiKey || null;
+      case 'openai':        return this.keys?.vendorKeys?.openai || null;
+      case 'azure-custom':  return this.keys?.vendorKeys?.azureCustom || null;
+      case 'local':
+      case 'disabled':
+      default:
+        return null;
+    }
+  }
+
   /**
    * Remove API keys (clears all keys)
    * @param {string} sessionId - Ignored, kept for API compatibility
@@ -296,3 +324,36 @@ class ApiKeyManager {
 }
 
 export default ApiKeyManager;
+
+/* ------------------------------------------------------------------------ */
+/* Singleton accessor                                                        */
+/*                                                                           */
+/* The LoxiaSystem creates one ApiKeyManager and registers it here so cross- */
+/* cutting services (e.g. composioService) can read vendor keys without     */
+/* dragging the manager through 10 layers of constructor arguments. Pure    */
+/* accessor — no implicit instantiation, no I/O.                            */
+/* ------------------------------------------------------------------------ */
+
+let _registered = null;
+
+/**
+ * Register the system-level ApiKeyManager. Called once by LoxiaSystem
+ * (src/index.js) right after instantiation.
+ */
+export function registerApiKeyManager(instance) {
+  _registered = instance;
+}
+
+/**
+ * Returns the registered ApiKeyManager, or `null` if the system hasn't
+ * registered one yet (tests, or partial bootstrap). Callers should
+ * handle null gracefully — usually by falling back to env vars.
+ */
+export function getApiKeyManager() {
+  return _registered;
+}
+
+/** Test-only: clear the registration. */
+export function _resetApiKeyManagerRegistrationForTests() {
+  _registered = null;
+}

package/src/services/codeMapStubRenderer.js

@@ -0,0 +1,142 @@
+/**
+ * @file codeMapStubRenderer.js
+ * @description Optional renderer that replaces code-map tool-result content
+ *   in PRIOR turns with a compact stub. The current turn's content stays
+ *   intact so the agent can act on what it just fetched.
+ *
+ * Design principle (from the focused-agent thread):
+ *   - conversation = action log
+ *   - cache = knowledge store
+ *   - index injection = library map
+ *
+ * The agent's working context shouldn't hold duplicates of bulky tool
+ * results that are already in the cache and surfaced in the index.
+ *
+ * This module is INERT until called. Production renderers can opt in via
+ * `applyCodeMapStubbing(messages, { currentTurnId })`. Existing flows
+ * are unaffected.
+ *
+ * Stub format (descriptive, NOT prescriptive — minimal-format rule):
+ *   [code-map skeleton src/foo.ts — cached; see ## CODEBASE KNOWLEDGE]
+ *
+ * IDEMPOTENT — running this twice on the same message list produces
+ * the same result. Safe to call on every render.
+ */
+
+/**
+ * Detect a code-map tool-result message body so we can stub it.
+ *
+ * The agentScheduler's `formatToolResult` produces bodies that include
+ * the toolId; we look for a small set of clear markers and refuse to
+ * touch anything we're not certain is a code-map result.
+ *
+ * @param {string} content
+ * @returns {{ filePath?: string, kind: 'skeleton'|'read-range'|null }}
+ */
+export function detectCodeMapResult(content) {
+  if (typeof content !== 'string' || content.length === 0) {
+    return { kind: null };
+  }
+  // We only stub when we see a clear "code-map" + ("skeleton" or "read-range") signature.
+  // Substring checks only — no regex.
+  const isCodeMap = content.includes('code-map') || content.includes('codeMap');
+  if (!isCodeMap) return { kind: null };
+  const isSkeleton = content.includes('skeleton');
+  const isReadRange = content.includes('read-range') || content.includes('readRange');
+  if (!isSkeleton && !isReadRange) return { kind: null };
+
+  // Try to pull a filePath out of common shapes:
+  //   filePath: src/foo.ts
+  //   "filePath": "src/foo.ts"
+  //   file: src/foo.ts
+  // String-native (no regex): scan for the first occurrence and slice.
+  let filePath = null;
+  for (const marker of ['"filePath":', 'filePath:', '"file":', 'file:']) {
+    const idx = content.indexOf(marker);
+    if (idx === -1) continue;
+    let rest = content.slice(idx + marker.length).trimStart();
+    // Strip an opening quote if present.
+    if (rest.startsWith('"')) rest = rest.slice(1);
+    // Take up to the next quote, comma, newline, or space.
+    let end = rest.length;
+    for (const stop of ['"', ',', '\n', ' ', '\r']) {
+      const i = rest.indexOf(stop);
+      if (i !== -1 && i < end) end = i;
+    }
+    filePath = rest.slice(0, end).trim();
+    if (filePath) break;
+  }
+
+  return {
+    filePath: filePath || null,
+    kind: isSkeleton ? 'skeleton' : 'read-range',
+  };
+}
+
+/**
+ * Build the stub text for a detected code-map result.
+ * Descriptive only — no prescriptive prose (per the bait-avoidance rule).
+ */
+export function buildStub({ filePath, kind }) {
+  const where = filePath ? ` ${filePath}` : '';
+  return `[code-map ${kind}${where} — cached; see \`## CODEBASE KNOWLEDGE\`]`;
+}
+
+/**
+ * Rewrite the `content` field of prior-turn code-map tool-result messages
+ * to a stub. The CURRENT turn's tool results are left untouched so the
+ * agent can act on what it just fetched.
+ *
+ * @param {Array<object>} messages - conversation messages
+ * @param {object} opts
+ * @param {string|number|null} [opts.currentTurnId] - identifier of the
+ *   currently-active turn. Messages with this turnId (matched by
+ *   `responseTurnId` or `_turnId` if present) are NOT stubbed.
+ *   If null/undefined, the LAST message in the array is considered
+ *   "current" and is preserved verbatim.
+ * @returns {Array<object>} new array — original input is not mutated
+ */
+export function applyCodeMapStubbing(messages, opts = {}) {
+  if (!Array.isArray(messages) || messages.length === 0) return messages;
+  const { currentTurnId = null } = opts;
+
+  // If no currentTurnId was given, fall back to "preserve the last
+  // tool-result message" — that's the freshest one the agent just got.
+  let lastToolResultIdx = -1;
+  if (currentTurnId == null) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i]?.type === 'tool-result') { lastToolResultIdx = i; break; }
+    }
+  }
+
+  return messages.map((msg, idx) => {
+    if (!msg || typeof msg !== 'object') return msg;
+    if (msg.type !== 'tool-result') return msg;
+
+    // Already stubbed (from a prior render pass) — leave as-is so we
+    // don't re-stub the stub and clobber `_originalContent`.
+    if (msg._stubbed === true) return msg;
+
+    // Skip the current turn.
+    if (currentTurnId != null) {
+      const tid = msg.responseTurnId || msg._turnId;
+      if (tid === currentTurnId) return msg;
+    } else if (idx === lastToolResultIdx) {
+      return msg;
+    }
+
+    const detection = detectCodeMapResult(msg.content);
+    if (detection.kind == null) return msg;
+
+    const stub = buildStub(detection);
+    // Preserve the original content under a side field so persistence /
+    // replay / audit aren't lossy. The rendered field is what goes to
+    // the LLM.
+    return {
+      ...msg,
+      _originalContent: msg.content,
+      content: stub,
+      _stubbed: true,
+    };
+  });
+}