onbuzz 5.0.1 → 5.1.0

package/src/tools/webTool.js

@@ -119,6 +119,9 @@
 
 import { BaseTool } from './baseTool.js';
 import TagParser from '../utilities/tagParser.js';
+import { DocumentStore } from '../services/documents/documentStore.js';
+import { DocumentMemory } from '../services/documents/documentMemory.js';
+import { DocumentIndexer } from '../services/embeddings/indexers/documentIndexer.js';
 import path from 'path';
 import fs from 'fs/promises';
 import os from 'os';
@@ -158,6 +161,13 @@ class WebTool extends BaseTool {
     // Tab tracking: Map<agentId, Map<tabName, tabInfo>>
     this.agentTabs = new Map();
 
+    // Content offload (web-content → document memory). Large fetched content
+    // is persisted + indexed instead of dumped into the conversation; the
+    // tool returns a compact handle + preview. Thresholds are config-tunable.
+    this.contentOffloadThreshold = config.contentOffloadThreshold ?? 4000; // chars
+    this.contentPreviewChars = config.contentPreviewChars ?? 800;
+    this._documentMemory = null; // lazy — embeddingService is attached late
+
     // Known search engines
     this.searchEngines = [
       {
@@ -275,8 +285,31 @@ First FETCH the login page to identify form selectors, then authenticate:
 \`\`\`json
 {"toolId": "web", "operation": "fetch", "url": "https://example.com", "formats": ["title", "text", "links"]}
 \`\`\`
+LARGE PAGES ARE AUTO-SAVED: when a page is big, FETCH does NOT return the full
+text. It saves the content as a searchable "document" and returns a preview +
+a document handle (docId, lines) + a recallHint. To get the parts you need,
+add a "goal" so FETCH returns the most relevant passages immediately, then use
+RECALL (below) or read exact lines with the code-map tool's read-range:
+\`\`\`json
+{"toolId": "web", "operation": "fetch", "url": "https://example.com/long-article", "goal": "pricing tiers and limits"}
+\`\`\`
+
+3. RECALL - Semantic search over content you previously fetched (no browser)
+\`\`\`json
+{"toolId": "web", "operation": "recall", "query": "what are the rate limits?", "topK": 5}
+\`\`\`
+Optional "docId" restricts the search to one saved document. Each hit returns
+the matching passage plus its source docId and line range (lineStart/lineEnd)
+so you can read the full passage via code-map read-range.
+
+4. PIN - Keep an important saved document forever (never auto-evicted)
+\`\`\`json
+{"toolId": "web", "operation": "pin", "docId": "doc-...", "pinned": true}
+\`\`\`
+Pin a document you'll need long-term so retention-based cleanup never drops
+it. Pass "pinned": false to unpin.
 
-3. INTERACTIVE - Browser automation
+5. INTERACTIVE - Browser automation
 \`\`\`json
 {"toolId": "web", "operation": "interactive", "stealthLevel": "maximum", "actions": [
   {"type": "open-tab", "name": "main", "url": "https://example.com", "nestedActions": [
@@ -744,10 +777,29 @@ If blocked (CAPTCHA, access denied), use stealthLevel: "maximum" (visible browse
 
       // Ensure browser is initialized with the correct stealth level
       // Note: Each operation also calls ensureBrowser internally, but this pre-check
-      // ensures we don't unnecessarily restart the browser
-      await this.ensureBrowser({ stealthLevel: effectiveStealthLevel });
+      // ensures we don't unnecessarily restart the browser.
+      // `recall`/`pin` are pure document-memory operations — no browser
+      // needed, so we skip the (expensive) launch for them.
+      if (operation !== 'recall' && operation !== 'pin') {
+        await this.ensureBrowser({ stealthLevel: effectiveStealthLevel });
+      }
 
       switch (operation) {
+        case 'recall':
+          result = await this.recall(params.query, {
+            agentId,
+            docId: params.docId,
+            topK: params.topK,
+          });
+          break;
+
+        case 'pin':
+          result = await this.pinDocument(params.docId, {
+            agentId,
+            pinned: params.pinned !== undefined ? params.pinned : true,
+          });
+          break;
+
         case 'search':
           result = await this.search(params.query, {
             engine: params.engine || 'duckduckgo',
@@ -761,7 +813,10 @@ If blocked (CAPTCHA, access denied), use stealthLevel: "maximum" (visible browse
           result = await this.fetch(params.url, {
             formats: params.formats || ['title', 'text'],
             stealthLevel: effectiveStealthLevel,
-            agentId
+            agentId,
+            // Optional: when the agent states what it's after, fetch returns
+            // the most relevant passages of large content immediately.
+            goal: params.goal
           });
           break;
 
@@ -844,6 +899,21 @@ If blocked (CAPTCHA, access denied), use stealthLevel: "maximum" (visible browse
         ...(result.title !== undefined && { title: result.title }),
         ...(result.text !== undefined && { text: result.text }),
         ...(result.url !== undefined && { url: result.url }),
+        // Content-offload handle (large fetches): hoist so the agent sees the
+        // document reference + recall guidance instead of an inline body.
+        ...(result.contentExternalized && { contentExternalized: true }),
+        ...(result.document !== undefined && { document: result.document }),
+        ...(result.textPreview !== undefined && { textPreview: result.textPreview }),
+        ...(result.recallHint !== undefined && { recallHint: result.recallHint }),
+        ...(result.relevantChunks !== undefined && { relevantChunks: result.relevantChunks }),
+        ...(result.htmlOmitted !== undefined && { htmlOmitted: result.htmlOmitted }),
+        // RECALL operation results.
+        ...(result.hits !== undefined && { hits: result.hits }),
+        ...(result.count !== undefined && { count: result.count }),
+        ...(result.query !== undefined && { query: result.query }),
+        ...(result.note !== undefined && { note: result.note }),
+        // PIN operation result.
+        ...(result.pinned !== undefined && { pinned: result.pinned }),
         ...(result.results !== undefined && { results: result.results }),
         ...(result.resultsCount !== undefined && { resultsCount: result.resultsCount }),
         ...(result.httpStatus !== undefined && { httpStatus: result.httpStatus }),
@@ -1173,8 +1243,167 @@ If blocked (CAPTCHA, access denied), use stealthLevel: "maximum" (visible browse
    * @param {Object} options - Fetch options
    * @returns {Promise<Object>} Fetched content
    */
+  /**
+   * Lazy accessor for the per-tool DocumentMemory (store + index).
+   *
+   * Why lazy: the EmbeddingService is attached to aiService AFTER tool
+   * construction (mirrors MemoryTool._getMemoryIndexer). The DocumentStore
+   * works regardless of embeddings; the indexer no-ops when the service is
+   * missing/disabled, so content is always persisted (just not searchable
+   * until embeddings are configured).
+   *
+   * @returns {DocumentMemory}
+   * @private
+   */
+  _getDocumentMemory() {
+    if (this._documentMemory) return this._documentMemory;
+    const svc = this.aiService?.getEmbeddingService?.() || null;
+    const store = new DocumentStore({ logger: this.logger });
+    const indexer = new DocumentIndexer({ embeddingService: svc, logger: this.logger });
+    this._documentMemory = new DocumentMemory({ store, indexer, logger: this.logger });
+    return this._documentMemory;
+  }
+
+  /**
+   * Offload large fetched content to document memory and return a compact
+   * handle in place of the body. No-op (returns the result unchanged) when:
+   * there's no agentId, the content is below threshold, or persistence fails.
+   *
+   * The heavy `text`/`html` fields are replaced with a preview + a `document`
+   * handle (docId/lines/etc.) so the agent can recall passages semantically or
+   * read exact lines via code-map read-range — without the body ever entering
+   * the conversation (and thus surviving compaction).
+   *
+   * @param {object} result   The fetch result (mutated copy returned).
+   * @param {{agentId?: string, url: string, goal?: string}} ctx
+   * @returns {Promise<{externalized: boolean, result: object}>}
+   * @private
+   */
+  async _maybeOffload(result, { agentId, url, goal } = {}) {
+    const text = typeof result.text === 'string' ? result.text : null;
+    const html = typeof result.html === 'string' ? result.html : null;
+    const primary = text ?? html; // text is what agents reason over; prefer it
+    if (!agentId || !primary || primary.length < this.contentOffloadThreshold) {
+      return { externalized: false, result };
+    }
+
+    const mem = this._getDocumentMemory();
+    let handle;
+    try {
+      handle = await mem.remember(agentId, {
+        source: url,
+        title: result.title || url,
+        content: primary,
+      });
+    } catch (err) {
+      this.logger?.warn?.('[WebTool] content offload failed; returning inline', { url, error: err?.message });
+      return { externalized: false, result };
+    }
+
+    const out = { ...result };
+    if (text !== null) { delete out.text; out.textPreview = text.slice(0, this.contentPreviewChars); }
+    if (html !== null) { delete out.html; out.htmlOmitted = true; }
+    out.contentExternalized = true;
+    out.document = {
+      docId: handle.docId,
+      source: handle.source,
+      title: handle.title,
+      bytes: handle.bytes,
+      lines: handle.lines,
+      chunkCount: handle.chunkCount,
+      indexed: handle.indexed,
+      embeddingsEnabled: handle.embeddingsEnabled,
+    };
+    out.recallHint = handle.embeddingsEnabled
+      ? `Full content saved as document ${handle.docId} (${handle.lines} lines). Retrieve relevant passages by semantic recall over your saved documents, or read exact lines with code-map read-range on the saved file.`
+      : `Full content saved as document ${handle.docId} (${handle.lines} lines), but semantic recall is OFF — set an embeddings provider in Settings to enable search. You can still read it with code-map read-range.`;
+
+    // Goal-aware: surface the most relevant passages immediately so the common
+    // case is one round-trip (fetch → use), not fetch-then-recall.
+    if (goal && handle.embeddingsEnabled) {
+      try {
+        const recall = await mem.recall(agentId, goal, { topK: 3, docId: handle.docId });
+        out.relevantChunks = (recall.hits || []).map((h) => ({
+          lineStart: h.lineStart, lineEnd: h.lineEnd, text: h.text,
+        }));
+      } catch { /* best-effort */ }
+    }
+
+    return { externalized: true, result: out };
+  }
+
+  /**
+   * Semantic/hybrid recall over content this agent previously fetched (the
+   * `documents` surface). No browser involved.
+   *
+   * @param {string} query
+   * @param {object} options
+   * @param {string} options.agentId
+   * @param {string} [options.docId]  Restrict to a single saved document.
+   * @param {number} [options.topK=8]
+   * @returns {Promise<object>} { success, query, count, hits[], note? }
+   */
+  async recall(query, options = {}) {
+    const { agentId, docId, topK } = options;
+    if (!query || typeof query !== 'string' || query.trim().length === 0) {
+      return { success: false, error: 'A non-empty "query" is required for the recall operation' };
+    }
+    if (!agentId) {
+      return { success: false, error: 'recall requires an agent context' };
+    }
+
+    const mem = this._getDocumentMemory();
+    if (!mem.embeddingsEnabled) {
+      return {
+        success: true,
+        query,
+        count: 0,
+        hits: [],
+        note: 'Semantic recall is OFF — set an embeddings provider in Settings to search saved web documents. You can still read a known document by docId via code-map read-range.',
+      };
+    }
+
+    const res = await mem.recall(agentId, query, {
+      topK: typeof topK === 'number' && topK > 0 ? topK : 8,
+      ...(docId ? { docId } : {}),
+    });
+    const hits = (res.hits || []).map((h) => ({
+      docId: h.docId,
+      title: h.title,
+      source: h.source,
+      lineStart: h.lineStart,
+      lineEnd: h.lineEnd,
+      score: h.score,
+      text: h.text,
+    }));
+    return { success: true, query, count: hits.length, hits };
+  }
+
+  /**
+   * Pin (or unpin) a saved document so it is never evicted regardless of
+   * retention. Browserless.
+   *
+   * @param {string} docId
+   * @param {object} options  { agentId, pinned=true }
+   * @returns {Promise<object>} { success, docId, pinned } or { success:false, error }
+   */
+  async pinDocument(docId, options = {}) {
+    const { agentId, pinned = true } = options;
+    if (!docId || typeof docId !== 'string') {
+      return { success: false, error: 'A "docId" is required for the pin operation' };
+    }
+    if (!agentId) {
+      return { success: false, error: 'pin requires an agent context' };
+    }
+    const entry = await this._getDocumentMemory().pin(agentId, docId, pinned);
+    if (!entry) {
+      return { success: false, error: `No saved document with id "${docId}"` };
+    }
+    return { success: true, docId, pinned: !!entry.pinned };
+  }
+
   async fetch(url, options = {}) {
-    const { formats = ['title', 'text'], agentId, stealthLevel = 'standard' } = options;
+    const { formats = ['title', 'text'], agentId, stealthLevel = 'standard', goal } = options;
 
     // Validate URL before doing anything expensive
     if (!url || typeof url !== 'string' || url.trim().length === 0) {
@@ -1290,7 +1519,10 @@ If blocked (CAPTCHA, access denied), use stealthLevel: "maximum" (visible browse
       if (stealthDowngradeNotice) {
         fetchResult.stealthNotice = stealthDowngradeNotice;
       }
-      return fetchResult;
+      // Offload large content to document memory (handle + preview instead of
+      // dumping the whole page into the conversation). No-op for small pages.
+      const { result: finalResult } = await this._maybeOffload(fetchResult, { agentId, url, goal });
+      return finalResult;
 
     } finally {
       try { await page.close(); } catch { /* swallow */ }

package/src/utilities/__tests__/logger.test.js

@@ -127,3 +127,99 @@ describe('Logger', () => {
     infoSpy.mockRestore();
   });
 });
+
+describe('Logger — Monitor App ring buffer + events', () => {
+  let logSpy, errSpy;
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+    errSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+  afterEach(() => { logSpy.mockRestore(); errSpy.mockRestore(); });
+
+  test('captures entries (newest last) with level + message', () => {
+    const logger = new Logger();
+    logger.info('first');
+    logger.error('second');
+    const logs = logger.getRecentLogs();
+    expect(logs.map(r => r.message)).toEqual(['first', 'second']);
+    expect(logs[1].level).toBe('ERROR');
+  });
+
+  test('respects the level gate (debug not captured at info level)', () => {
+    const logger = new Logger({ level: 'info' });
+    logger.debug('hidden');
+    logger.info('shown');
+    expect(logger.getRecentLogs().map(r => r.message)).toEqual(['shown']);
+  });
+
+  test('captures agentId + category (logAgentActivity)', () => {
+    const logger = new Logger();
+    logger.logAgentActivity('agent-7', 'did a thing', { foo: 'bar' });
+    const [rec] = logger.getRecentLogs();
+    expect(rec.agentId).toBe('agent-7');
+    expect(rec.category).toBe('agent-activity');
+  });
+
+  test('captures error detail from meta.error', () => {
+    const logger = new Logger();
+    logger.error('boom', { error: 'disk full' });
+    expect(logger.getRecentLogs()[0].error).toBe('disk full');
+  });
+
+  test('object error is safe-stringified (no circular crash)', () => {
+    const logger = new Logger();
+    logger.error('boom', { error: { code: 'E_IO', detail: 'bad sector' } });
+    const rec = logger.getRecentLogs()[0];
+    expect(typeof rec.error).toBe('string');
+    expect(rec.error).toContain('E_IO');
+  });
+
+  test('filters by level / agentId / category / limit', () => {
+    const logger = new Logger();
+    logger.logAgentActivity('a1', 'x');     // info, agent-activity, a1
+    logger.error('e1', { agentId: 'a2' });  // error, a2
+    logger.info('plain');                   // info, no agent
+    expect(logger.getRecentLogs({ level: 'error' }).map(r => r.message)).toEqual(['e1']);
+    expect(logger.getRecentLogs({ agentId: 'a1' }).map(r => r.message)).toEqual(['[AGENT:a1] x']);
+    expect(logger.getRecentLogs({ category: 'agent-activity' })).toHaveLength(1);
+    expect(logger.getRecentLogs({ limit: 1 }).map(r => r.message)).toEqual(['plain']);
+  });
+
+  test('ring buffer is bounded by maxRecentLogs', () => {
+    const logger = new Logger({ maxRecentLogs: 3 });
+    for (let i = 0; i < 10; i++) logger.info(`m${i}`);
+    const logs = logger.getRecentLogs();
+    expect(logs).toHaveLength(3);
+    expect(logs.map(r => r.message)).toEqual(['m7', 'm8', 'm9']);
+  });
+
+  test('logEvents emits each captured entry', () => {
+    const logger = new Logger();
+    const seen = [];
+    logger.logEvents.on('entry', r => seen.push(r));
+    logger.warn('hey');
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toMatchObject({ level: 'WARN', message: 'hey' });
+  });
+
+  test('a throwing logEvents listener does not break logging', () => {
+    const logger = new Logger();
+    logger.logEvents.on('entry', () => { throw new Error('listener boom'); });
+    expect(() => logger.info('still works')).not.toThrow();
+    expect(logger.getRecentLogs().map(r => r.message)).toContain('still works');
+  });
+
+  test('clearRecentLogs empties the buffer and returns the count', () => {
+    const logger = new Logger();
+    logger.info('a'); logger.info('b');
+    expect(logger.clearRecentLogs()).toBe(2);
+    expect(logger.getRecentLogs()).toEqual([]);
+  });
+
+  test('getRecentLogs returns a copy (caller cannot mutate the buffer)', () => {
+    const logger = new Logger();
+    logger.info('a');
+    logger.getRecentLogs().push({ message: 'injected' });
+    expect(logger.getRecentLogs().map(r => r.message)).toEqual(['a']);
+  });
+});

package/src/utilities/__tests__/updateNotifier.test.js

@@ -11,6 +11,7 @@ import {
   runUpdateCheck,
   isUpdateCheckDisabled,
   loadPackageJson,
+  getDistribution,
 } from '../updateNotifier.js';
 
 describe('isUpdateCheckDisabled', () => {
@@ -37,6 +38,24 @@ describe('isUpdateCheckDisabled', () => {
   });
 });
 
+describe('getDistribution', () => {
+  test('returns "electron" when LOXIA_ELECTRON is set', () => {
+    expect(getDistribution({}, { LOXIA_ELECTRON: '1' })).toBe('electron');
+  });
+
+  test('returns "pkg" for a standalone binary (process.pkg present)', () => {
+    expect(getDistribution({ pkg: {} }, {})).toBe('pkg');
+  });
+
+  test('electron takes precedence over pkg', () => {
+    expect(getDistribution({ pkg: {} }, { LOXIA_ELECTRON: '1' })).toBe('electron');
+  });
+
+  test('defaults to "npm" for a normal install', () => {
+    expect(getDistribution({}, {})).toBe('npm');
+  });
+});
+
 describe('loadPackageJson', () => {
   test('finds the CLI package.json by walking up from a starting dir', () => {
     // The helper looks for a pkg.json with `bin` OR `@loxia-labs/` name —
@@ -47,6 +66,31 @@ describe('loadPackageJson', () => {
     expect(typeof pkg.version).toBe('string');
   });
 
+  test('derives releasesUrl from build.publish github config', () => {
+    const fs = {
+      readFileSync: () => JSON.stringify({
+        name: '@loxia-labs/loxia-autopilot-one',
+        version: '4.6.4',
+        bin: { loxia: 'bin/cli.js' },
+        build: { publish: { provider: 'github', owner: 'Loxia-ai', repo: 'autopilot-releases' } },
+      }),
+    };
+    const pkg = loadPackageJson({ startDir: '/tmp', fs });
+    expect(pkg.releasesUrl).toBe('https://github.com/Loxia-ai/autopilot-releases/releases/latest');
+  });
+
+  test('releasesUrl is null when no github publish target exists', () => {
+    const fs = {
+      readFileSync: () => JSON.stringify({
+        name: '@loxia-labs/loxia-onbuzz',
+        version: '1.0.0',
+        bin: { onbuzz: 'bin/cli.js' },
+      }),
+    };
+    const pkg = loadPackageJson({ startDir: '/tmp', fs });
+    expect(pkg.releasesUrl).toBeNull();
+  });
+
   test('returns null when no qualifying package.json exists in the chain', () => {
     // Inject a stub that always returns ENOENT.
     const fs = {
@@ -78,6 +122,57 @@ describe('runUpdateCheck — kill-switches', () => {
     expect(r).toBeNull();
     expect(importImpl).not.toHaveBeenCalled();
   });
+
+  test('returns null (and never imports) for the electron distribution', async () => {
+    // Electron self-updates via electron-updater; the npm banner is wrong there.
+    const importImpl = jest.fn();
+    const r = await runUpdateCheck({
+      env: {},
+      pkg: { name: 'x', version: '1.0.0' },
+      importImpl,
+      distribution: 'electron',
+    });
+    expect(r).toBeNull();
+    expect(importImpl).not.toHaveBeenCalled();
+  });
+});
+
+describe('runUpdateCheck — pkg (standalone binary) message', () => {
+  test('uses the download URL and marks the install as non-global', async () => {
+    const notifyMock = jest.fn();
+    const updateNotifierFn = jest.fn().mockReturnValue({ notify: notifyMock });
+    const importImpl = jest.fn().mockResolvedValue({ default: updateNotifierFn });
+
+    const pkg = {
+      name: '@loxia-labs/loxia-autopilot-one',
+      version: '4.6.4',
+      releasesUrl: 'https://github.com/Loxia-ai/autopilot-releases/releases/latest',
+    };
+    await runUpdateCheck({ env: {}, pkg, importImpl, distribution: 'pkg' });
+
+    const notifyOpts = notifyMock.mock.calls[0][0];
+    expect(notifyOpts.isGlobal).toBe(false);
+    expect(notifyOpts.message).toContain('Download the latest build');
+    expect(notifyOpts.message).toContain(pkg.releasesUrl);
+    expect(notifyOpts.message).not.toContain('{packageName}');
+  });
+
+  test('falls back to a generic download message when releasesUrl is absent', async () => {
+    const notifyMock = jest.fn();
+    const updateNotifierFn = jest.fn().mockReturnValue({ notify: notifyMock });
+    const importImpl = jest.fn().mockResolvedValue({ default: updateNotifierFn });
+
+    await runUpdateCheck({
+      env: {},
+      pkg: { name: 'x', version: '1.0.0' },
+      importImpl,
+      distribution: 'pkg',
+    });
+
+    const notifyOpts = notifyMock.mock.calls[0][0];
+    expect(notifyOpts.isGlobal).toBe(false);
+    expect(notifyOpts.message).toContain('release source');
+  });
 });
 
 describe('runUpdateCheck — dependency tolerance', () => {

package/src/utilities/__tests__/userProfileInjection.test.js

@@ -0,0 +1,69 @@
+import { describe, test, expect } from '@jest/globals';
+import { buildUserProfileBlock, _USER_PROFILE_INTERNALS } from '../userProfileInjection.js';
+
+const { PER_ITEM_TOKEN_CAP, TOTAL_TOKEN_CAP, HEADER_OPEN, HEADER_CLOSE } = _USER_PROFILE_INTERNALS;
+
+describe('buildUserProfileBlock', () => {
+  test('empty / non-array → no block', () => {
+    expect(buildUserProfileBlock([])).toEqual({ block: '', truncated: [] });
+    expect(buildUserProfileBlock(null)).toEqual({ block: '', truncated: [] });
+    expect(buildUserProfileBlock(undefined)).toEqual({ block: '', truncated: [] });
+  });
+
+  test('formats title + content as a bullet, wrapped in the header', () => {
+    const { block } = buildUserProfileBlock([{ title: 'name', content: 'Daniel' }]);
+    expect(block).toContain(HEADER_OPEN.trim());
+    expect(block).toContain(HEADER_CLOSE);
+    expect(block).toContain('• name: Daniel');
+  });
+
+  test('title-only and content-only forms', () => {
+    expect(buildUserProfileBlock([{ title: 'vegetarian' }]).block).toContain('• vegetarian');
+    expect(buildUserProfileBlock([{ content: 'prefers metric units' }]).block).toContain('• prefers metric units');
+  });
+
+  test('skips fully-empty entries', () => {
+    const { block } = buildUserProfileBlock([{ title: '', content: '' }, { title: 'name', content: 'Daniel' }]);
+    expect(block).toContain('Daniel');
+    expect((block.match(/•/g) || []).length).toBe(1);
+  });
+
+  test('truncates an oversized item and reports it', () => {
+    const big = 'x'.repeat((PER_ITEM_TOKEN_CAP + 200) * 4);
+    const { block, truncated } = buildUserProfileBlock([{ title: 'bio', content: big }]);
+    expect(block).toContain('…');
+    expect(truncated.some(t => /per-item cap/.test(t.reason))).toBe(true);
+  });
+
+  test('drops items beyond the total cap (keeps the block lean)', () => {
+    // Each item ~110 tokens (under the per-item cap, so no per-item truncation);
+    // 8 of them (~880 tokens) blow past the 600-token total cap → later ones drop.
+    const items = Array.from({ length: 8 }, (_, i) => ({ title: `k${i}`, content: 'x'.repeat(440) }));
+    const { block, truncated } = buildUserProfileBlock(items);
+    expect(block).toContain('k0:');                                   // first fits
+    expect(block).not.toContain('k7:');                              // last dropped
+    expect(truncated.some(t => /profile cap/.test(t.reason))).toBe(true);
+  });
+
+  test('falls back to description when content is absent', () => {
+    const { block } = buildUserProfileBlock([{ title: 'note', description: 'likes brevity' }]);
+    expect(block).toContain('• note: likes brevity');
+  });
+
+  test('untitled items report "(untitled)" when truncated or dropped', () => {
+    // No title + oversized content → truncated, reported as "(untitled)".
+    const big = 'z'.repeat((PER_ITEM_TOKEN_CAP + 100) * 4);
+    const t1 = buildUserProfileBlock([{ content: big }]).truncated;
+    expect(t1.some(t => t.title === '(untitled)')).toBe(true);
+
+    // No-title items that overflow the total cap → dropped as "(untitled)".
+    const items = Array.from({ length: 8 }, () => ({ content: 'x'.repeat(440) }));
+    const t2 = buildUserProfileBlock(items).truncated;
+    expect(t2.some(t => t.title === '(untitled)' && /profile cap/.test(t.reason))).toBe(true);
+  });
+
+  test('a non-empty list of empty items yields no block', () => {
+    const { block } = buildUserProfileBlock([{ title: '', content: '' }, {}, { description: '' }]);
+    expect(block).toBe('');
+  });
+});