onbuzz 5.0.2 → 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__/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('');
+  });
+});

package/src/utilities/logger.js

@@ -11,6 +11,7 @@
 
 import { promises as fs } from 'fs';
 import path from 'path';
+import { EventEmitter } from 'events';
 
 import {
   SYSTEM_VERSION
@@ -91,7 +92,16 @@ class Logger {
       debug: '\x1b[90m', // Gray
       reset: '\x1b[0m'
     };
-    
+
+    // In-memory ring buffer for the Settings → Monitor App view. Always on
+    // (cheap: a bounded array of compact, scalar-only records — no
+    // serialization happens until the endpoint reads it). `logEvents` lets
+    // the webServer push new entries to the UI live.
+    this._recentLogs = [];
+    this._maxRecentLogs = config.maxRecentLogs || 500;
+    this.logEvents = new EventEmitter();
+    this.logEvents.setMaxListeners(0);
+
     this.initialized = false;
   }
 
@@ -238,7 +248,10 @@ class Logger {
     }
     
     const logEntry = this.createLogEntry(level, message, meta);
-    
+
+    // Capture into the Monitor App ring buffer (always on, bounded).
+    this._captureRecent(logEntry);
+
     // Output to configured destinations
     for (const output of this.outputs) {
       switch (output) {
@@ -252,6 +265,63 @@ class Logger {
     }
   }
 
+  /**
+   * Push a compact, scalar-only record into the ring buffer + emit it.
+   * Compact on purpose: we never store the raw meta (which can hold huge or
+   * circular objects), only the fields the Monitor App shows — so reading
+   * the buffer can't throw on serialization and memory stays bounded.
+   * @private
+   */
+  _captureRecent(entry) {
+    const record = {
+      timestamp: entry.timestamp,
+      level: entry.level,
+      message: typeof entry.message === 'string' ? entry.message : String(entry.message ?? ''),
+    };
+    if (entry.agentId != null) record.agentId = String(entry.agentId);
+    if (entry.category != null) record.category = String(entry.category);
+    if (entry.error != null) {
+      record.error = typeof entry.error === 'string' ? entry.error : _safeStringify(entry.error);
+    }
+
+    this._recentLogs.push(record);
+    if (this._recentLogs.length > this._maxRecentLogs) {
+      this._recentLogs.splice(0, this._recentLogs.length - this._maxRecentLogs);
+    }
+    try {
+      this.logEvents.emit('entry', record);
+    } catch {
+      // A telemetry listener must never break logging.
+    }
+  }
+
+  /**
+   * Recent log records for the Monitor App, newest LAST. Optional filters.
+   * @param {object} [opts]
+   * @param {string} [opts.level]    Only this level (case-insensitive).
+   * @param {string} [opts.agentId]  Only this agent.
+   * @param {string} [opts.category] Only this category.
+   * @param {number} [opts.limit]    Cap to the most recent N.
+   * @returns {object[]}
+   */
+  getRecentLogs({ level, agentId, category, limit } = {}) {
+    let out = this._recentLogs;
+    if (level)    { const L = String(level).toUpperCase(); out = out.filter(r => r.level === L); }
+    if (agentId)  out = out.filter(r => r.agentId === agentId);
+    if (category) out = out.filter(r => r.category === category);
+    if (Number.isInteger(limit) && limit > 0 && out.length > limit) {
+      out = out.slice(out.length - limit);
+    }
+    return out.slice(); // copy — callers shouldn't mutate the buffer
+  }
+
+  /** Clear the Monitor App ring buffer. @returns {number} entries removed. */
+  clearRecentLogs() {
+    const n = this._recentLogs.length;
+    this._recentLogs.length = 0;
+    return n;
+  }
+
   /**
    * Create structured log entry
    * @private