onbuzz 4.8.3 → 4.9.0

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

@@ -0,0 +1,332 @@
+/**
+ * composioService — shared SDK wrapper used by composioTool, REST
+ * endpoints, and the CLI.
+ *
+ * Tests inject a stub client via `_injectClientForTests` so we cover
+ * every method without depending on a real Composio account.
+ */
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import * as composioService from '../composioService.js';
+import {
+  registerApiKeyManager,
+  _resetApiKeyManagerRegistrationForTests,
+} from '../apiKeyManager.js';
+
+/** A minimal ApiKeyManager stand-in for tests. */
+function makeStubApiKeyManager(initial = {}) {
+  return {
+    keys: { loxiaApiKey: null, vendorKeys: { ...initial } },
+    setSessionKeys: jest.fn(async function (_sid, { vendorKeys = {} }) {
+      this.keys.vendorKeys = { ...this.keys.vendorKeys, ...vendorKeys };
+    }),
+    persist: jest.fn().mockResolvedValue(undefined),
+  };
+}
+
+function makeStubClient() {
+  return {
+    toolkits: {
+      list: jest.fn().mockResolvedValue([
+        { slug: 'github', name: 'GitHub' },
+        { slug: 'slack',  name: 'Slack' },
+      ]),
+    },
+    tools: {
+      list: jest.fn().mockResolvedValue([
+        { slug: 'GITHUB_CREATE_AN_ISSUE', description: 'Create issue' },
+      ]),
+      execute: jest.fn().mockResolvedValue({ successful: true, data: { issueNumber: 42 } }),
+    },
+    connectedAccounts: {
+      list:       jest.fn().mockResolvedValue([
+        { id: 'conn-1', toolkitSlug: 'github', status: 'ACTIVE' },
+        { id: 'conn-2', toolkitSlug: 'slack',  status: 'INITIATED' },
+      ]),
+      get:        jest.fn().mockResolvedValue({ id: 'conn-1', status: 'ACTIVE' }),
+      initiate:   jest.fn().mockResolvedValue({ id: 'conn-1', redirectUrl: 'https://connect.composio.dev/link/abc' }),
+      delete:     jest.fn().mockResolvedValue({ success: true }),
+    },
+  };
+}
+
+let savedApiKey;
+beforeEach(() => {
+  savedApiKey = process.env.COMPOSIO_API_KEY;
+  process.env.COMPOSIO_API_KEY = 'test-key';
+  _resetApiKeyManagerRegistrationForTests();
+  composioService._resetForTests();
+});
+afterEach(() => {
+  if (savedApiKey === undefined) delete process.env.COMPOSIO_API_KEY;
+  else process.env.COMPOSIO_API_KEY = savedApiKey;
+  _resetApiKeyManagerRegistrationForTests();
+  composioService._resetForTests();
+});
+
+describe('composioService — availability', () => {
+  test('reports unavailable when no key is set anywhere', async () => {
+    delete process.env.COMPOSIO_API_KEY;
+    composioService._resetForTests();
+    const r = await composioService.isAvailable();
+    expect(r.available).toBe(false);
+    expect(r.reason).toMatch(/No Composio API key/i);
+    expect(r.keySource).toBeNull();
+  });
+
+  test('isAvailable returns true when client is injected', async () => {
+    composioService._injectClientForTests(makeStubClient());
+    const r = await composioService.isAvailable();
+    expect(r.available).toBe(true);
+  });
+
+  test('keySource = "env" when only the env var is set', async () => {
+    process.env.COMPOSIO_API_KEY = 'env-key-12345';
+    composioService._resetForTests();
+    composioService._injectClientForTests(makeStubClient());
+    const r = await composioService.isAvailable();
+    expect(r.keySource).toBe('env');
+  });
+
+  test('keySource = "vault" when ApiKeyManager has the key (vault > env precedence)', async () => {
+    process.env.COMPOSIO_API_KEY = 'env-key';
+    registerApiKeyManager(makeStubApiKeyManager({ composio: 'vault-key-XYZ' }));
+    composioService._resetForTests();
+    composioService._injectClientForTests(makeStubClient());
+    const r = await composioService.isAvailable();
+    expect(r.keySource).toBe('vault');
+  });
+});
+
+describe('composioService — setApiKey + forgetApiKey', () => {
+  test('setApiKey persists via apiKeyManager and invalidates the client', async () => {
+    const mgr = makeStubApiKeyManager();
+    registerApiKeyManager(mgr);
+    // Seed a cached client with the old (env) key.
+    composioService._injectClientForTests(makeStubClient());
+
+    const r = await composioService.setApiKey('comp_abcdef123456');
+    expect(r.success).toBe(true);
+    expect(mgr.setSessionKeys).toHaveBeenCalledWith(null, { vendorKeys: { composio: 'comp_abcdef123456' } });
+    // The cached client was wiped — next op will re-derive from the new vault key.
+    composioService._injectClientForTests(makeStubClient()); // re-seed for the next assertion
+    const r2 = await composioService.isAvailable();
+    expect(r2.keySource).toBe('vault');
+  });
+
+  test('setApiKey rejects too-short keys', async () => {
+    registerApiKeyManager(makeStubApiKeyManager());
+    const r = await composioService.setApiKey('hi');
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/too short/i);
+  });
+
+  test('setApiKey with empty string clears the stored key', async () => {
+    const mgr = makeStubApiKeyManager({ composio: 'existing-key-XYZ' });
+    registerApiKeyManager(mgr);
+    const r = await composioService.setApiKey('');
+    expect(r.success).toBe(true);
+    expect(r.cleared).toBe(true);
+    expect(mgr.keys.vendorKeys.composio).toBeUndefined();
+    expect(mgr.persist).toHaveBeenCalled();
+  });
+
+  test('forgetApiKey is an alias for setApiKey("")', async () => {
+    const mgr = makeStubApiKeyManager({ composio: 'k' });
+    registerApiKeyManager(mgr);
+    const r = await composioService.forgetApiKey();
+    expect(r.success).toBe(true);
+    expect(r.cleared).toBe(true);
+    expect(mgr.keys.vendorKeys.composio).toBeUndefined();
+  });
+
+  test('setApiKey returns a friendly error if no ApiKeyManager is registered', async () => {
+    _resetApiKeyManagerRegistrationForTests();
+    const r = await composioService.setApiKey('comp_abcdef123456');
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/ApiKeyManager is not initialized/i);
+  });
+});
+
+describe('composioService — listToolkits', () => {
+  test('returns the SDK list', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    const r = await composioService.listToolkits();
+    expect(r.success).toBe(true);
+    expect(r.toolkits).toHaveLength(2);
+    expect(r.toolkits[0].slug).toBe('github');
+    expect(client.toolkits.list).toHaveBeenCalled();
+  });
+
+  test('surfaces SDK errors as success:false', async () => {
+    const client = makeStubClient();
+    client.toolkits.list = jest.fn().mockRejectedValue(new Error('rate limited'));
+    composioService._injectClientForTests(client);
+    const r = await composioService.listToolkits();
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/rate limited/);
+  });
+});
+
+describe('composioService — listConnections', () => {
+  test('forwards userId and returns array', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    const r = await composioService.listConnections('operator');
+    expect(r.success).toBe(true);
+    expect(r.connections).toHaveLength(2);
+    expect(client.connectedAccounts.list).toHaveBeenCalledWith({ userId: 'operator' });
+  });
+
+  test('accepts SDK list responses wrapped in {items: ...}', async () => {
+    const client = makeStubClient();
+    client.connectedAccounts.list = jest.fn().mockResolvedValue({
+      items: [{ id: 'x', toolkitSlug: 'gh', status: 'ACTIVE' }],
+    });
+    composioService._injectClientForTests(client);
+    const r = await composioService.listConnections('operator');
+    expect(r.connections).toHaveLength(1);
+    expect(r.connections[0].id).toBe('x');
+  });
+});
+
+describe('composioService — connectionStatus', () => {
+  test('maps ACTIVE → connected:true', async () => {
+    composioService._injectClientForTests(makeStubClient());
+    const r = await composioService.connectionStatus('operator', 'github');
+    expect(r.connected).toBe(true);
+    expect(r.status).toBe('ACTIVE');
+    expect(r.connectionId).toBe('conn-1');
+  });
+
+  test('maps missing connection → connected:false', async () => {
+    const client = makeStubClient();
+    client.connectedAccounts.get = jest.fn().mockResolvedValue(null);
+    composioService._injectClientForTests(client);
+    const r = await composioService.connectionStatus('operator', 'github');
+    expect(r.connected).toBe(false);
+    expect(r.status).toBe('NOT_CONNECTED');
+  });
+});
+
+describe('composioService — connect', () => {
+  test('forwards userId + toolkit and returns the connect link', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    const r = await composioService.connect('operator', 'github');
+    expect(r.success).toBe(true);
+    expect(r.connectLink).toMatch(/^https:\/\/connect\.composio\.dev/);
+    expect(r.connectionId).toBe('conn-1');
+    expect(client.connectedAccounts.initiate).toHaveBeenCalledWith({
+      userId: 'operator', toolkit: 'github',
+    });
+  });
+
+  test('passes through authConfigId when provided', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    await composioService.connect('operator', 'github', { authConfigId: 'auth-cfg-xyz' });
+    expect(client.connectedAccounts.initiate).toHaveBeenCalledWith({
+      userId: 'operator', toolkit: 'github', authConfigId: 'auth-cfg-xyz',
+    });
+  });
+});
+
+describe('composioService — disconnect', () => {
+  test('disconnect by connectionId', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    const r = await composioService.disconnect({ connectionId: 'conn-1' });
+    expect(r.success).toBe(true);
+    expect(client.connectedAccounts.delete).toHaveBeenCalledWith('conn-1');
+  });
+
+  test('disconnect by {userId, toolkitSlug} looks up the id first', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    const r = await composioService.disconnect({ userId: 'operator', toolkitSlug: 'github' });
+    expect(r.success).toBe(true);
+    expect(client.connectedAccounts.get).toHaveBeenCalledWith({ userId: 'operator', toolkit: 'github' });
+    expect(client.connectedAccounts.delete).toHaveBeenCalledWith('conn-1');
+  });
+
+  test('rejects with helpful error when no target shape is provided', async () => {
+    composioService._injectClientForTests(makeStubClient());
+    const r = await composioService.disconnect({});
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/connectionId/);
+  });
+
+  test('handles missing connection cleanly when looking up by toolkit', async () => {
+    const client = makeStubClient();
+    client.connectedAccounts.get = jest.fn().mockResolvedValue(null);
+    composioService._injectClientForTests(client);
+    const r = await composioService.disconnect({ userId: 'operator', toolkitSlug: 'github' });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/No active connection found/);
+  });
+});
+
+describe('composioService — listTools', () => {
+  test('forwards toolkit + userId', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    const r = await composioService.listTools('github', 'operator');
+    expect(r.success).toBe(true);
+    expect(r.tools[0].slug).toBe('GITHUB_CREATE_AN_ISSUE');
+    expect(client.tools.list).toHaveBeenCalledWith({ toolkit: 'github', userId: 'operator' });
+  });
+
+  test('omits userId from the SDK call when not provided', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    await composioService.listTools('github');
+    expect(client.tools.list).toHaveBeenCalledWith({ toolkit: 'github' });
+  });
+});
+
+describe('composioService — execute', () => {
+  test('forwards userId + actionSlug + arguments', async () => {
+    const client = makeStubClient();
+    composioService._injectClientForTests(client);
+    const r = await composioService.execute('operator', 'github', 'GITHUB_CREATE_AN_ISSUE', {
+      owner: 'acme', repo: 'api', title: 'Bug', body: '…',
+    });
+    expect(r.success).toBe(true);
+    expect(r.output).toEqual({ issueNumber: 42 });
+    expect(client.tools.execute).toHaveBeenCalledWith('GITHUB_CREATE_AN_ISSUE', {
+      userId: 'operator',
+      arguments: { owner: 'acme', repo: 'api', title: 'Bug', body: '…' },
+    });
+  });
+
+  test('upstream success=false is surfaced unchanged', async () => {
+    const client = makeStubClient();
+    client.tools.execute = jest.fn().mockResolvedValue({ successful: false, error: 'repo not found' });
+    composioService._injectClientForTests(client);
+    const r = await composioService.execute('op', 'gh', 'X', {});
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/repo not found/);
+  });
+});
+
+describe('composioService — every op fails gracefully when SDK is unavailable', () => {
+  beforeEach(() => {
+    delete process.env.COMPOSIO_API_KEY;
+    composioService._resetForTests();
+  });
+
+  test.each([
+    ['listToolkits',     () => composioService.listToolkits()],
+    ['listConnections',  () => composioService.listConnections('op')],
+    ['connectionStatus', () => composioService.connectionStatus('op', 'gh')],
+    ['connect',          () => composioService.connect('op', 'gh')],
+    ['disconnect',       () => composioService.disconnect({ connectionId: 'x' })],
+    ['listTools',        () => composioService.listTools('gh')],
+    ['execute',          () => composioService.execute('op', 'gh', 'X', {})],
+  ])('%s returns success:false with "no key" error', async (_label, op) => {
+    const r = await op();
+    expect(r.success).toBe(false);
+    expect((r.error || r.reason || '')).toMatch(/No Composio API key/i);
+  });
+});

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/apiKeyManager.js

@@ -296,3 +296,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,
+    };
+  });
+}