@animalabs/agent-framework 0.32.0 → 0.33.0

package/dist/src/modules/history/index.js

@@ -32,6 +32,35 @@
  * Kept deliberately read-only, same posture as HealthModule: no side
  * effects, no message mutation. `onProcess` is a no-op.
  *
+ * The tools read the record, not an agent's window (#291): an agent's
+ * window is the rows its requests were given, which once agents share a
+ * slot is not the whole record. Where the framework offers the window
+ * lookup (ModuleContext.windowStatusOf), each entry `extract`, `search` and
+ * `semantic_search` return for a row the caller isn't shown says so
+ * (`window: "not-shown" | "undone"`), relative to the agent whose call it
+ * is, or to the delivery agent for a call no agent made. A row the caller
+ * is shown is one its window holds and its view keeps
+ * (ModuleContext.viewKeeps): a window written down from the shared record
+ * can hold another agent's stored context injection or a held row, which
+ * its requests never carry. For an agent's call, another agent's own rows
+ * (its rounds, its notes, its stored injections) that it isn't shown are
+ * left out unless it observes that agent (decision 1), counted as
+ * `leftOut`; without an author filter extract's `offset` counts them, so a
+ * caller pages on by `returned + leftOut`, and with one it counts only the
+ * rows the filter keeps, which a caller pages on by `resume`. A row stored before the audience stamp, whose owner
+ * isn't recorded, is nobody's own and isn't left out: it carries `window`
+ * where the caller isn't shown it. The summaries `overview` and `semantic_search` read fold the
+ * bound context's agent's window (ModuleContext.agentNameOf says whose), so
+ * for another agent's call that doesn't observe that agent they are left
+ * out too: `overview` keeps each summarized span's time, level and counts
+ * and leaves out its text (`content: null`, `contentLeftOut: true`,
+ * counted as `summariesLeftOut`), and `semantic_search` leaves out summary
+ * hits, counted in `index.leftOut`. That is for now; serving such a caller
+ * its own context's summaries is later work. An operator's call stays
+ * record-wide, and so does the bound agent's own. `stats` stays an
+ * aggregate over the record, unmarked, as do overview's counts. Without
+ * the lookup every tool and every answer is as it was before the index.
+ *
  * Every query dispatch collapses onto `queryMessagesByTimeAndChannel` — its
  * own implementation already handles "only a time range", "only a channel",
  * or "neither" by delegating to the single-filter native queries (see
@@ -41,9 +70,12 @@
 import { Worker } from 'node:worker_threads';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { EmbedServiceError, SemanticIndexClient, SemanticIndexer, messageIndexText, parseSummaryKey, summaryIndexText } from './semantic.js';
+import { ERROR_MARK, EmbedServiceError, SemanticIndexClient, SemanticIndexer, messageIndexText, parseSummaryKey, summaryIndexText } from './semantic.js';
 import { unknownToolMessage } from '../unknown-tool.js';
+import { speechOf } from '../../send-tools.js';
 import { safeSlice } from '../../safe-slice.js';
+import { audienceOf } from '../../dendrite/audience.js';
+import { storedInjectionMarkOf } from '../../stored-injections.js';
 // ============================================================================
 // Limits
 // ============================================================================
@@ -546,6 +578,16 @@ export class HistoryModule {
         return this.indexer ? this.indexer.catchUp(maxItems) : null;
     }
     getTools() {
+        // With the framework's window lookup (#291), entries say which rows the
+        // caller isn't being shown, and another agent's own rows are left out
+        // for an agent that doesn't observe it: one sentence more in each
+        // description that returns rows, and in overview's, whose summaries'
+        // text is left out the same way. Without it, the tools are as they were.
+        const windowed = !!this.ctx?.windowStatusOf;
+        const windowNote = windowed ? WINDOW_NOTE : '';
+        // extract's offset counts the rows left out for the caller, as the page's
+        // place in the window does.
+        const extractWindowNote = windowed ? WINDOW_NOTE + EXTRACT_OFFSET_NOTE : '';
         return [
             {
                 name: 'stats',
@@ -567,7 +609,9 @@ export class HistoryModule {
                 name: 'extract',
                 description: 'Fetch raw, uncompressed messages for a time range and/or channel, paginated oldest-first. ' +
                     'Use after `stats` to pull the actual content. format:"text" flattens each message to a short ' +
-                    'readable string (tool_use/tool_result/thinking/images rendered as bracketed labels); ' +
+                    'readable string (a call of a tool the framework names for sending, editing or saying a message, such as ' +
+                    'send_message, as its name and its words when it carries words, such as "[telegram--send_message] …", its name ending ", error" when its result, stored after it, is flagged as an error; ' +
+                    'other tool_use/tool_result/thinking/images as bracketed labels, a tool_result flagged as an error ending ", error"); ' +
                     'format:"raw" returns the content blocks unmodified. ' +
                     'Two extra modes: (1) aroundId — pass a message id (e.g. from `search`) to get the conversation ' +
                     'around it: `before` messages before it, the message itself (anchor:true), and `after` messages ' +
@@ -576,7 +620,8 @@ export class HistoryModule {
                     'authors; this is filtered in-process over at most maxScan messages of the window, so a response ' +
                     'may report truncated:true with a `resume` object ({windowOffset, offset, afterId}) — repeat the call with ' +
                     'those fields added to continue exactly where it stopped. If messages were added or removed in the window ' +
-                    'meanwhile, the resume re-anchors on afterId and says so (windowChanged), or fails loudly when it can\'t.',
+                    'meanwhile, the resume re-anchors on afterId and says so (windowChanged), or fails loudly when it can\'t.' +
+                    extractWindowNote,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -613,7 +658,8 @@ export class HistoryModule {
                     'wholeWord:true stops "mission" from matching inside "uncommissioned". Each match carries an `id` ' +
                     'you can hand to extract({aroundId}) to read the conversation around it. ' +
                     'regex:true matching runs under a wall-clock deadline and is cleanly failed ' +
-                    `(not silently empty) if a pattern is too slow — avoid nested-quantifier patterns like (a+)+.`,
+                    `(not silently empty) if a pattern is too slow — avoid nested-quantifier patterns like (a+)+.` +
+                    windowNote,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -660,7 +706,8 @@ export class HistoryModule {
                     'with a clear error rather than silently returning no spans. An entry marked boundaryUncertain:true ' +
                     'had a millisecond-timestamp collision at its edge with another span (rare — two distinct messages ' +
                     'landing in the same millisecond); its messageCount is still exact but tokensEstimate may be off by ' +
-                    'a small, bounded amount.',
+                    'a small, bounded amount.' +
+                    (windowed ? WINDOW_NOTE_OVERVIEW : ''),
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -685,6 +732,9 @@ export class HistoryModule {
         ];
     }
     semanticSearchTool() {
+        // An undo moves no branch since #291, so with the window lookup an
+        // undone message is a hit, marked, rather than dropped off the branch.
+        const windowed = !!this.ctx?.windowStatusOf;
         return {
             name: 'semantic_search',
             description: 'Search your own history by MEANING, not exact words: an embedding index over your raw messages ' +
@@ -698,12 +748,13 @@ export class HistoryModule {
                 'searching (bounded, so a huge backlog is reported as `index.behind` rather than blocking; if a ' +
                 'background sync is already running, the search waits for that run to finish instead). ' +
                 'Purely a read: nothing is written to your history. Hits are checked against your current branch ' +
-                'before they come back: a message you undid or a summary from a branch you left is dropped and ' +
+                `before they come back: ${windowed ? 'a message or ' : 'a message you undid or '}a summary from a branch you left is dropped and ` +
                 'counted in index.droppedOffBranch; a message edited down to nothing searchable is dropped and ' +
                 'counted in index.droppedStale. When that leaves fewer than `limit` hits and the index may hold more, it ' +
                 'searches again, deeper, down to its first 200 hits; if a search after the first fails, the hits found so ' +
                 'far come back, with why in index.searchAgainError. Message snippets ' +
-                'always show the current text of the message.',
+                'always show the current text of the message.' +
+                (windowed ? WINDOW_NOTE_SEMANTIC : ''),
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -733,13 +784,13 @@ export class HistoryModule {
                 case 'stats':
                     return this.handleStats((call.input ?? {}));
                 case 'extract':
-                    return this.handleExtract((call.input ?? {}));
+                    return this.handleExtract((call.input ?? {}), this.viewFor(call));
                 case 'search':
-                    return await this.handleSearch((call.input ?? {}));
+                    return await this.handleSearch((call.input ?? {}), this.viewFor(call));
                 case 'overview':
-                    return this.handleOverview((call.input ?? {}));
+                    return this.handleOverview((call.input ?? {}), this.viewFor(call));
                 case 'semantic_search':
-                    return await this.handleSemanticSearch((call.input ?? {}));
+                    return await this.handleSemanticSearch((call.input ?? {}), this.viewFor(call));
                 default:
                     return { success: false, isError: true, error: unknownToolMessage(this.name, call.name, this.getTools()) };
             }
@@ -766,6 +817,130 @@ export class HistoryModule {
     async onProcess(_event, _state) {
         return {};
     }
+    /**
+     * How one call's caller sees the record (#291), when the framework offers
+     * the window lookup (ModuleContext.windowStatusOf); undefined otherwise,
+     * and then every entry is as it was before the presentation index. The
+     * caller is the agent whose call it is (callerAgentName), or, for a call
+     * no agent made (an operator's, a host's), the delivery agent, for marks
+     * only. A row the caller is shown is one its window holds and its view
+     * keeps (ModuleContext.viewKeeps): a window written down from the record
+     * the residents share can hold another agent's stored context injection,
+     * or a row a tune-out holds from the residents, which the caller's
+     * requests never carry. A row the caller isn't shown is marked
+     * (`window`); for an agent's call, another agent's own row (its rounds,
+     * its notes, its stored injections) that it isn't shown is left out,
+     * unless it observes that agent: seeing another agent's thread is a
+     * declared relationship (decision 1), an observe edge, such as a
+     * resident's `AgentConfig.observes`. Each row's status is read once per
+     * call.
+     *
+     * The bound context's summaries fold its agent's window, that agent's own
+     * rounds and notes among it, so for another agent's call that doesn't
+     * observe that agent they are left out too (`leavesSummaries`). That is
+     * for now: serving such a caller summaries of its own context is later
+     * work. An agent's call where the framework can't say whose context the
+     * module is bound to (ModuleContext.agentNameOf missing, or answering
+     * that it is no live agent's) leaves them out as well. A call no agent
+     * made, and the bound agent's own, read them as before.
+     */
+    viewFor(call) {
+        const ctx = this.ctx;
+        if (!ctx?.windowStatusOf)
+            return undefined;
+        const caller = call.callerAgentName;
+        const forCaller = caller === undefined ? undefined : { forAgent: caller };
+        const statuses = new Map();
+        // Set once a lookup throws: an agent the framework no longer knows. Its
+        // window is taken as holding nothing, so each row is marked not shown.
+        let unknown = false;
+        const statusOf = (msg) => {
+            if (unknown)
+                return null;
+            const id = String(msg.id);
+            let status = statuses.get(id);
+            if (status === undefined) {
+                try {
+                    status = ctx.windowStatusOf(msg.id, forCaller);
+                }
+                catch {
+                    unknown = true;
+                    return null;
+                }
+                statuses.set(id, status);
+            }
+            return status;
+        };
+        // Whether the caller's view keeps a row its window holds. Without the
+        // lookup, every row its window holds is taken as shown, as before it.
+        const kept = new Map();
+        const keeps = (msg) => {
+            if (!ctx.viewKeeps)
+                return true;
+            const id = String(msg.id);
+            let keep = kept.get(id);
+            if (keep === undefined) {
+                try {
+                    keep = ctx.viewKeeps(msg, forCaller);
+                }
+                catch {
+                    unknown = true;
+                    return false;
+                }
+                kept.set(id, keep);
+            }
+            return keep;
+        };
+        const shown = (msg) => statusOf(msg) === 'in' && keeps(msg);
+        const observed = new Map();
+        const observes = (owner) => {
+            let sees = observed.get(owner);
+            if (sees === undefined) {
+                try {
+                    sees = ctx.observes?.(caller, owner) ?? false;
+                }
+                catch {
+                    sees = false;
+                }
+                observed.set(owner, sees);
+            }
+            return sees;
+        };
+        let leavesSummaries = false;
+        if (caller !== undefined) {
+            let bound;
+            try {
+                bound = this.cm ? ctx.agentNameOf?.(this.cm) : undefined;
+            }
+            catch {
+                bound = undefined;
+            }
+            leavesSummaries = bound === undefined || (bound !== caller && !observes(bound));
+        }
+        return {
+            mark: (msg) => {
+                const status = statusOf(msg);
+                if (unknown)
+                    return 'not-shown';
+                if (status === 'undone')
+                    return 'undone';
+                if (status === 'out' || status === 'absent')
+                    return 'not-shown';
+                return status === 'in' && !keeps(msg) ? 'not-shown' : undefined;
+            },
+            leaves: (msg) => {
+                if (caller === undefined)
+                    return false;
+                // A stored injection from before the audience stamp names its agent
+                // in its own mark: it is that agent's context, as every view reads it.
+                const owner = audienceOf(msg.metadata)?.ownRowOf ?? storedInjectionMarkOf(msg.metadata)?.agent;
+                if (owner === undefined || owner === caller)
+                    return false;
+                return !shown(msg) && !observes(owner);
+            },
+            leavesSummaries,
+        };
+    }
     // ==========================================================================
     // stats
     // ==========================================================================
@@ -801,9 +976,9 @@ export class HistoryModule {
     // ==========================================================================
     // extract
     // ==========================================================================
-    handleExtract(input) {
+    handleExtract(input, view) {
         if (input.aroundId !== undefined)
-            return this.handleExtractAround(input);
+            return this.handleExtractAround(input, view);
         const aroundOnly = ['before', 'after', 'allChannels'].filter((k) => input[k] !== undefined);
         if (aroundOnly.length > 0) {
             const one = aroundOnly.length === 1;
@@ -828,6 +1003,17 @@ export class HistoryModule {
                 'author filter, use "offset".');
         }
         if (authorFilter) {
+            // A row left out for the caller (viewFor) is one the filter doesn't
+            // keep, counted in leftOut.
+            let leftOut = 0;
+            const keeps = (m) => {
+                if (!authorFilter(m))
+                    return false;
+                if (!view?.leaves(m))
+                    return true;
+                leftOut++;
+                return false;
+            };
             // No native author index: page through the time/channel window and
             // filter here. offset/limit apply to the FILTERED sequence. Stop as
             // soon as the requested page is full; otherwise scan to maxScan. Only
@@ -842,7 +1028,7 @@ export class HistoryModule {
             const maxScan = clampCount(input.maxScan, EXTRACT_FILTER_DEFAULT_MAX_SCAN, EXTRACT_FILTER_MAX_MAX_SCAN, 'maxScan', 'read', 1);
             const requestedOffset = clampCount(input.windowOffset, 0, NATIVE_OFFSET_MAX, 'windowOffset', 'read');
             // A position is only meaningful against the window it was taken in:
-            // a removal before it (every discord:delete, host hide, /undo) shifts
+            // a removal before it (every discord:delete, host hide) shifts
             // later positions left, and a message inserted before it (a
             // time-ordered window with backfill) shifts them right. Either would
             // silently skip or repeat a message. afterId pins the position to the
@@ -880,9 +1066,13 @@ export class HistoryModule {
             let kept = 0;
             let scanned = 0;
             let lastScanned;
-            // Window position just past the last message put on the page, and that message.
+            // Window position just past the last message put on the page, that
+            // message, and the rows left out up to it: a page-full stop resumes
+            // there, so the rows the lookahead passed after it are the next page's
+            // to count.
             let afterPage = windowOffset;
             let lastOnPage;
+            let leftOutAtPage = 0;
             let exhausted = false;
             let pageFull = false;
             outer: for (;;) {
@@ -899,12 +1089,13 @@ export class HistoryModule {
                 for (const m of chunk) {
                     scanned++;
                     lastScanned = m;
-                    if (!authorFilter(m))
+                    if (!keeps(m))
                         continue;
                     if (kept >= offset && page.length < limit) {
                         page.push(m);
                         afterPage = windowOffset + scanned;
                         lastOnPage = m;
+                        leftOutAtPage = leftOut;
                     }
                     kept++;
                     if (limit > 0 && page.length >= limit && kept > offset + limit) {
@@ -931,19 +1122,22 @@ export class HistoryModule {
                 if (next.length === 0)
                     exhausted = true;
             }
+            const counted = pageFull ? leftOutAtPage : leftOut;
             return {
                 success: true,
                 data: {
                     // A resumed scan (windowOffset > 0) only saw the window from that
                     // position on, so its count is named for that — never a total. A
                     // page-full stop's lookahead match lies past the resume point and
-                    // is left out, so counts add up across a chain of resumes.
+                    // is left out, so counts add up across a chain of resumes, and so
+                    // do the rows left out on the way to it, which the resume scans.
                     ...(() => {
                         const n = pageFull ? kept - 1 : kept;
                         const base = windowOffset > 0 ? 'matchedSinceWindowOffset' : 'matchedCount';
                         return { [exhausted ? base : `${base}AtLeast`]: n };
                     })(),
                     returned: page.length,
+                    ...(counted > 0 ? { leftOut: counted } : {}),
                     scanned,
                     truncated: !exhausted,
                     ...(shift !== 0 || missed.length > 0 || unverified
@@ -962,7 +1156,7 @@ export class HistoryModule {
                                     ? {
                                         addedBefore: missed.length,
                                         // the ones this filter would have kept — fetch them with extract({aroundId})
-                                        missedIds: missed.filter(authorFilter).map((m) => String(m.id)),
+                                        missedIds: missed.filter((m) => authorFilter(m) && !view?.leaves(m)).map((m) => String(m.id)),
                                     }
                                     : {}),
                                 note: missed.length > 0 || shift > 0
@@ -1002,7 +1196,7 @@ export class HistoryModule {
                             };
                         })()
                         : {}),
-                    messages: page.map((msg) => projectMessage(msg, format)),
+                    messages: page.map((msg) => projectMessage(msg, format, (m) => this.failedSpeech(m), view?.mark(msg))),
                 },
             };
         }
@@ -1017,14 +1211,19 @@ export class HistoryModule {
             limit: limit + 1,
             offset,
         });
-        const page = result.messages.slice(0, limit);
+        const fetched = result.messages.slice(0, limit);
+        // Rows left out for the caller (viewFor) leave the page; the page's
+        // place in the window, and so offset and hasMore, stay the window's.
+        const page = view ? fetched.filter((msg) => !view.leaves(msg)) : fetched;
+        const leftOut = fetched.length - page.length;
         return {
             success: true,
             data: {
                 ...(channelId !== undefined ? { matchedCount: result.matchedCount } : {}),
                 returned: page.length,
+                ...(leftOut > 0 ? { leftOut } : {}),
                 hasMore: result.messages.length > limit,
-                messages: page.map((msg) => projectMessage(msg, format)),
+                messages: page.map((msg) => projectMessage(msg, format, (m) => this.failedSpeech(m), view?.mark(msg))),
             },
         };
     }
@@ -1035,7 +1234,7 @@ export class HistoryModule {
      * side still needs, the nearest messages strictly before/after it (both
      * via edgeWindow, which is exact by timestamp).
      */
-    handleExtractAround(input) {
+    handleExtractAround(input, view) {
         const windowFields = ['from', 'to', 'offset', 'windowOffset', 'limit'].filter((k) => input[k] !== undefined);
         if (windowFields.length > 0) {
             throw new Error(`Nothing was read: "aroundId" picks its own window, so it doesn't take ${quotedList(windowFields, 'or')}. Size ` +
@@ -1063,7 +1262,9 @@ export class HistoryModule {
                     ? 'the "messageId" of a history--semantic_search hit.'
                     : 'the "id" of a history--search or history--extract result.'));
         }
-        const anchor = cm.getMessage(rawId.replace(/^msg:/, ''));
+        const found = cm.getMessage(rawId.replace(/^msg:/, ''));
+        // A row left out for the caller (viewFor) is answered as one not there.
+        const anchor = found && !view?.leaves(found) ? found : null;
         if (!anchor) {
             throw new Error(`Nothing was read: no message in your history has the id ${shown(input.aroundId)}. Pass the "id" ` +
                 'of a history--search or history--extract result' +
@@ -1105,15 +1306,18 @@ export class HistoryModule {
         const needAfter = after - tiesAfter.length;
         const earlier = needBefore > 0 ? this.edgeWindow({ toMs: t - 1, channelId, n: needBefore, side: 'newest' }).messages.reverse() : [];
         const later = needAfter > 0 ? this.edgeWindow({ fromMs: t + 1, channelId, n: needAfter, side: 'oldest' }).messages : [];
-        const window = [...earlier, ...tiesBefore, ties[idx], ...tiesAfter, ...later];
+        const around = [...earlier, ...tiesBefore, ties[idx], ...tiesAfter, ...later];
+        const window = view ? around.filter((m) => !view.leaves(m)) : around;
+        const leftOut = around.length - window.length;
         return {
             success: true,
             data: {
                 anchorId,
                 channelId: channelId ?? null,
                 returned: window.length,
+                ...(leftOut > 0 ? { leftOut } : {}),
                 messages: window.map((m) => ({
-                    ...projectMessage(m, format),
+                    ...projectMessage(m, format, (n) => this.failedSpeech(n), view?.mark(m)),
                     ...(String(m.id) === anchorId ? { anchor: true } : {}),
                 })),
             },
@@ -1122,7 +1326,7 @@ export class HistoryModule {
     // ==========================================================================
     // search
     // ==========================================================================
-    async handleSearch(input) {
+    async handleSearch(input, view) {
         // A finite number is searched as its text, as a regular expression made
         // from it reads it; any other value that isn't text is refused.
         const given = input.query;
@@ -1203,11 +1407,32 @@ export class HistoryModule {
                 unscanned = w.total - (w.messages.length - pool.length) - windowMessages.length;
         }
         const candidatePoolSize = windowMessages.length;
-        const candidates = authorFilter ? windowMessages.filter(authorFilter) : windowMessages;
-        const poolInfo = {
-            candidatePoolSize,
-            ...(authorFilter ? { afterAuthorFilter: candidates.length } : {}),
-            order,
+        const byAuthor = authorFilter ? windowMessages.filter(authorFilter) : windowMessages;
+        // A row left out for the caller (viewFor) is no candidate. Beside each
+        // candidate, how many were left out before it.
+        const candidates = [];
+        const leftOutBefore = [];
+        let leftOutOfPool = 0;
+        for (const m of byAuthor) {
+            if (view?.leaves(m)) {
+                leftOutOfPool++;
+                continue;
+            }
+            candidates.push(m);
+            leftOutBefore.push(leftOutOfPool);
+        }
+        // A scan stopped at `limit` resumes after its last scanned candidate, so
+        // the rows left out past it are the next call's to count, as extract's
+        // page-full stop counts them (leftOutAtPage): counts add up across a
+        // chain of resumes.
+        const poolInfo = (scanned) => {
+            const leftOut = scanned > 0 && scanned < candidates.length ? leftOutBefore[scanned - 1] : leftOutOfPool;
+            return {
+                candidatePoolSize,
+                ...(authorFilter ? { afterAuthorFilter: byAuthor.length } : {}),
+                ...(leftOut > 0 ? { leftOut } : {}),
+                order,
+            };
         };
         // Where the scan stopped, when it stopped before the end of the window
         // the caller asked about: either `limit` matches came first (the rest of
@@ -1276,8 +1501,8 @@ export class HistoryModule {
             // through a worker thread instead, which can be forcibly terminated
             // on a deadline. See search-regex-worker.ts's header for the full
             // rationale.
-            const { matches, scanned } = await this.searchWithRegexWorker(candidates, query, flags, limit);
-            return { success: true, data: { scanned, ...poolInfo, truncated, ...resumeInfo(scanned, matches.length), matches } };
+            const { matches, scanned } = await this.searchWithRegexWorker(candidates, query, flags, limit, view);
+            return { success: true, data: { scanned, ...poolInfo(scanned), truncated, ...resumeInfo(scanned, matches.length), matches } };
         }
         // Plain substring search (String.prototype.indexOf) is inherently
         // linear in input length — no ReDoS-equivalent risk — so it stays
@@ -1304,14 +1529,73 @@ export class HistoryModule {
                 participant: msg.participant,
                 author: authorName(msg),
                 channelId: getChannelId(msg) ?? null,
-                snippet: snippetAround(text, hit.index, hit.length),
+                ...windowField(view?.mark(msg)),
+                snippet: this.hitSnippet(msg, text, hit.index, hit.length),
             });
         }
         return {
             success: true,
-            data: { scanned, ...poolInfo, truncated, ...resumeInfo(scanned, matches.length), matches },
+            data: { scanned, ...poolInfo(scanned), truncated, ...resumeInfo(scanned, matches.length), matches },
         };
     }
+    failedSpeech(msg) {
+        const pending = new Set();
+        for (const block of msg.content)
+            if (block.type === 'tool_use' && speechOf(block.name, block.input))
+                pending.add(block.id);
+        if (!pending.size)
+            return NO_FAILURES;
+        const cm = this.cm;
+        const fromMs = msg.timestamp.getTime();
+        const failed = new Set();
+        const answer = (blocks) => {
+            for (const block of blocks) {
+                if (block.type === 'tool_result' && pending.delete(block.toolUseId) && block.isError)
+                    failed.add(block.toolUseId);
+            }
+        };
+        answer(msg.content);
+        let past = false;
+        let body = msg.bodyGroupId;
+        for (let offset = 0; pending.size > 0; offset++) {
+            const later = cm.queryMessagesByTime({ fromMs, limit: 1, offset }).messages[0];
+            if (!later)
+                break;
+            if (!past) {
+                if (later.timestamp.getTime() > fromMs)
+                    break;
+                past = String(later.id) === String(msg.id);
+                continue;
+            }
+            const blocks = later.content;
+            if (later.bodyGroupId === undefined || later.bodyGroupId !== body) {
+                if (blocks.some((block) => block.type === 'tool_use') || !blocks.some((block) => block.type === 'tool_result'))
+                    break;
+                body = later.bodyGroupId;
+            }
+            answer(blocks);
+        }
+        return failed;
+    }
+    hitSnippet(msg, text, index, length) {
+        const content = msg.content;
+        const failed = this.failedSpeech(msg);
+        const spans = blockSpans(content);
+        for (const { block, at, label } of spans) {
+            if (block.type !== 'tool_use')
+                continue;
+            const said = speechOf(block.name, block.input);
+            const wordsAt = at + label.length - (said?.words.length ?? 0);
+            if (said && index >= wordsAt && index < at + label.length && index + length <= at + label.length) {
+                return `[${block.name}${failed.has(block.id) ? ERROR_MARK : ''}] ${snippetAround(said.words, index - wordsAt, length)}`;
+            }
+        }
+        if (!failed.size)
+            return snippetAround(text, index, length);
+        const marks = spans.flatMap(({ block, at }) => (block.type === 'tool_use' && failed.has(block.id) ? [at + 1 + block.name.length] : []));
+        const moved = (i) => i + ERROR_MARK.length * marks.filter((mark) => mark <= i).length;
+        return snippetAround(flattenContent(content, failed), moved(index), moved(index + length) - moved(index));
+    }
     /**
      * Run regex matching for `search` on a worker thread with a hard
      * wall-clock deadline, so a catastrophically-backtracking pattern can be
@@ -1326,7 +1610,7 @@ export class HistoryModule {
      * module) rather than returning an empty match list — a timed-out search
      * must never be indistinguishable from a clean "no matches" result.
      */
-    async searchWithRegexWorker(candidates, pattern, flags, limit) {
+    async searchWithRegexWorker(candidates, pattern, flags, limit, view) {
         const texts = candidates.map((msg) => flattenContent(msg.content));
         let worker;
         try {
@@ -1365,7 +1649,8 @@ export class HistoryModule {
                     participant: msg.participant,
                     author: authorName(msg),
                     channelId: getChannelId(msg) ?? null,
-                    snippet: snippetAround(text, matchIndex, matchLength),
+                    ...windowField(view?.mark(msg)),
+                    snippet: this.hitSnippet(msg, text, matchIndex, matchLength),
                 };
             });
             return { matches, scanned };
@@ -1381,7 +1666,7 @@ export class HistoryModule {
     // ==========================================================================
     // overview
     // ==========================================================================
-    async handleSemanticSearch(input) {
+    async handleSemanticSearch(input, view) {
         if (!this.semanticCfg || !this.semanticClient) {
             throw new Error("Nothing was searched: this host has no semantic index set up, so history--semantic_search isn't available " +
                 "here, and calling it again won't change that. history--search finds messages by their words.");
@@ -1488,16 +1773,23 @@ export class HistoryModule {
             };
         };
         // The remote index is append-only and knows nothing about branches: a
-        // message removed from the agent's reach by /undo, /checkout, /restore or
-        // /newtopic keeps its id (a new message gets a fresh one) and stays
-        // indexed. Check every hit against the CURRENT branch before it goes back
-        // to the model — getMessage/getSummary rebuild on branch switch, so an
-        // undone message, or a summary this branch doesn't hold, answers null.
-        // A branch made from an earlier point, as an undo makes one, can mint a
-        // summary id another branch already used, so a summary's key carries its
-        // creation time too, and a hit whose time isn't this branch's summary's
-        // is another branch's. k is small, so this is at most `limit` local
-        // lookups.
+        // message removed from the agent's reach by a rollback, /checkout,
+        // /restore or /newtopic keeps its id (a new message gets a fresh one) and
+        // stays indexed. Check every hit against the CURRENT branch before it goes
+        // back to the model — getMessage/getSummary rebuild on branch switch, so a
+        // message, or a summary, this branch doesn't hold answers null. An undo
+        // works on the agent's window since #291 and moves no branch, so an
+        // undone message stays on it and comes back, marked `window: "undone"`
+        // for the caller when the framework offers the window lookup (viewFor),
+        // as is one the caller wasn't shown; another agent's own row the caller
+        // doesn't observe is left out (index.leftOut), and so is a summary hit
+        // for another agent's call that doesn't observe the agent whose context
+        // the summaries fold (viewFor's leavesSummaries).
+        // A branch made from an earlier point, as a rollback makes one, can mint
+        // a summary id another branch already used, so a summary's key carries
+        // its creation time too, and a hit whose time isn't this branch's
+        // summary's is another branch's. k is small, so this is at most `limit`
+        // local lookups.
         // A message hit whose current text has nothing left to index (edited
         // blank, delete not yet applied) is dropped too, so its stale snippet is
         // never served. Dropped hits are replaced by over-fetching: when the
@@ -1511,6 +1803,8 @@ export class HistoryModule {
         // A summary hit's snippet is rebuilt from the local summary too, so a
         // service that keeps only vectors and ids (no text) still yields one.
         const currentText = new Map();
+        // Each message hit's mark for the caller (viewFor), by the hit's id.
+        const marks = new Map();
         const keep = (h) => {
             const msgId = /^msg:(.+)$/.exec(h.id)?.[1];
             const sum = parseSummaryKey(h.id);
@@ -1518,10 +1812,16 @@ export class HistoryModule {
                 const m = cm.getMessage(msgId);
                 if (!m)
                     return 'offBranch';
+                if (view?.leaves(m))
+                    return 'leftOut';
+                const mark = view?.mark(m);
+                if (mark !== undefined)
+                    marks.set(h.id, mark);
                 const text = safeSlice(messageIndexText(m, includePrivate), 0, this.semanticCfg.maxChars ?? 32_000);
                 if (!text)
                     return 'stale';
-                currentText.set(h.id, text);
+                const failed = this.failedSpeech(m);
+                currentText.set(h.id, { text, shown: failed.size ? safeSlice(messageIndexText(m, includePrivate, failed), 0, this.semanticCfg.maxChars ?? 32_000) : text });
                 return 'ok';
             }
             if (sum !== null) {
@@ -1539,6 +1839,8 @@ export class HistoryModule {
                     return 'superseded';
                 if (s.created !== sum.createdMs)
                     return 'offBranch';
+                if (view?.leavesSummaries)
+                    return 'leftOut';
                 const text = summaryIndexText(s, this.semanticCfg);
                 // An empty text here is mostly defensive: context-manager drops a
                 // summary that's empty after trimming when it loads, and refuses to
@@ -1547,7 +1849,7 @@ export class HistoryModule {
                 // text.
                 if (!text)
                     return 'stale';
-                currentText.set(h.id, text);
+                currentText.set(h.id, { text, shown: text });
                 return 'ok';
             }
             return 'ok';
@@ -1563,6 +1865,7 @@ export class HistoryModule {
         }
         let droppedOffBranch = 0;
         let droppedStale = 0;
+        let leftOut = 0;
         // Why searching again for more hits failed, when it did. The search
         // before it answered, so its hits on this branch are returned.
         let searchAgainError = null;
@@ -1571,18 +1874,24 @@ export class HistoryModule {
         const check = () => {
             droppedOffBranch = 0;
             droppedStale = 0;
+            leftOut = 0;
             onBranch = res.hits.filter((h) => {
                 const v = keep(h);
                 if (v === 'offBranch')
                     droppedOffBranch++;
                 else if (v === 'stale')
                     droppedStale++;
+                else if (v === 'leftOut')
+                    leftOut++;
                 return v === 'ok';
             });
         };
+        // A search of summaries alone, for a caller they're left out for, keeps
+        // no hit however deep it goes, so it isn't searched again.
+        const keepsNone = wantsSummariesOnly && view?.leavesSummaries === true;
         for (;;) {
             check();
-            if (onBranch.length >= limit || res.hits.length < k || k >= SEMANTIC_MAX_FETCH)
+            if (keepsNone || onBranch.length >= limit || res.hits.length < k || k >= SEMANTIC_MAX_FETCH)
                 break;
             k = Math.min(SEMANTIC_MAX_FETCH, k * 4);
             try {
@@ -1628,10 +1937,11 @@ export class HistoryModule {
                 score: h.score,
                 timestamp,
                 channelId: h.channel,
+                ...windowField(marks.get(h.id)),
                 participant: meta?.participant ?? null,
                 author: meta?.author ?? null,
-                snippet: currentText.has(h.id) ? snippetOf(currentText.get(h.id)) : (h.text ?? ''),
-                chars: currentText.has(h.id) ? currentText.get(h.id).length : h.chars,
+                snippet: currentText.has(h.id) ? snippetOf(currentText.get(h.id).shown) : (h.text ?? ''),
+                chars: currentText.has(h.id) ? currentText.get(h.id).text.length : h.chars,
             };
         });
         if (unread.length > 0) {
@@ -1653,6 +1963,8 @@ export class HistoryModule {
                     droppedOffBranch,
                     /** Hits for messages whose current text has nothing indexable (edited blank; the index keeps such a message until its delete goes through, and on a service without /delete it never does). */
                     droppedStale,
+                    /** Hits left out for the caller (#291): another agent's own rows it isn't shown and doesn't observe, and, for another agent's call that doesn't observe the agent whose context the summaries fold, summary hits; only when there were any. */
+                    ...(leftOut > 0 ? { leftOut } : {}),
                     /** When too few hits were on this branch and searching again for more failed: why, and whether calling again can help. */
                     searchAgainError,
                 },
@@ -1660,7 +1972,7 @@ export class HistoryModule {
             },
         };
     }
-    handleOverview(input) {
+    handleOverview(input, view) {
         const channelId = this.resolveChannel(input.channelId);
         const fromMs = parseIsoDate(input.from, 'from');
         const toMs = parseIsoDate(input.to, 'to');
@@ -1971,6 +2283,14 @@ export class HistoryModule {
         // `filtered.length - limit` has no such cliff, at limit:0 it's
         // `slice(filtered.length)` -> `[]`, the honest answer.
         const capped = truncated ? filtered.slice(filtered.length - limit) : filtered;
+        // The summaries fold the bound context's agent's window, its own rounds
+        // and notes among it (#291). For another agent's call that doesn't
+        // observe that agent (viewFor's leavesSummaries) a summarized span keeps
+        // its time, level and counts, which are the record's, and leaves out its
+        // text: `content: null` and `contentLeftOut: true`, counted at the top as
+        // `summariesLeftOut`.
+        const leavesContent = view?.leavesSummaries === true;
+        const summariesLeftOut = leavesContent ? capped.filter((e) => e.summarized).length : 0;
         return {
             success: true,
             data: {
@@ -1987,6 +2307,7 @@ export class HistoryModule {
                 ...(input.level !== undefined ? { level: input.level } : { maxLevelAvailable: cm.getMaxSummaryLevel() }),
                 truncated,
                 totalSpans,
+                ...(summariesLeftOut > 0 ? { summariesLeftOut } : {}),
                 entries: capped.map((e) => {
                     // When channelId narrows the response, the numbers an agent will
                     // actually reason over (messageCount/tokensEstimate) are scoped
@@ -2004,7 +2325,11 @@ export class HistoryModule {
                         from: new Date(e.startMs).toISOString(),
                         to: new Date(e.endMs).toISOString(),
                         summarized: e.summarized,
-                        ...(e.summarized ? { content: e.content, level: e.level } : {}),
+                        ...(e.summarized
+                            ? leavesContent
+                                ? { content: null, contentLeftOut: true, level: e.level }
+                                : { content: e.content, level: e.level }
+                            : {}),
                         // Set only when this entry's boundary-tie disambiguation (see
                         // the correction pass above) found and corrected a
                         // millisecond-timestamp collision at its edge. messageCount is
@@ -2223,31 +2548,71 @@ function mergeForeignIntoGap(gaps, boundaryMs, side, foreign) {
         gaps.push({ startMs: boundaryMs, endMs: boundaryMs, summarized: false, stats: addend, boundaryUncertain: true });
     }
 }
-function projectMessage(msg, format) {
+/** The sentence extract's and search's descriptions gain with the window lookup (getTools). */
+const WINDOW_NOTE = ' A message that isn\'t in your context carries `window`: "undone" for one an undo or a refusal rewind took ' +
+    'out of it, "not-shown" for one not in your context now, never shown to you or returned by an undo or rollback ' +
+    'to be shown again; another agent\'s own turns and notes that aren\'t in your context are left out unless you ' +
+    'observe that agent, and how many were is `leftOut`.';
+/** extract's addition to it: without an author filter its offset counts the rows left out, as its page's place in the window does; with one, only the rows the filter keeps. */
+const EXTRACT_OFFSET_NOTE = ' Without an author filter, `offset` counts the messages left out too: to page on, advance it by returned + leftOut. ' +
+    'With one, it counts only the messages the filter keeps: page on by `resume`.';
+/** semantic_search's form of it. */
+const WINDOW_NOTE_SEMANTIC = ' A message hit that isn\'t in your context carries `window` ("undone" for one an undo or a refusal rewind took ' +
+    'out of it, "not-shown" for one not in your context now, never shown to you or returned by an undo or rollback ' +
+    'to be shown again); another agent\'s own turns and notes that aren\'t in your ' +
+    'context are left out unless you observe that agent, and so are summary hits when the summaries fold another ' +
+    'agent\'s context (the one this history is bound to) and you don\'t observe that agent, all counted in ' +
+    'index.leftOut.';
+/** overview's form of it: its entries are spans, and only a summary's text is the bound agent's. */
+const WINDOW_NOTE_OVERVIEW = ' The summaries fold one agent\'s context, the one this history is bound to: when that isn\'t yours and you don\'t ' +
+    'observe that agent, a summarized span comes back with its time, level and counts but not its text ' +
+    '(content:null, contentLeftOut:true), and summariesLeftOut says how many did.';
+/** `{ window }` for a defined mark, nothing otherwise, so an entry in the caller's window is as it always was. */
+function windowField(mark) {
+    return mark === undefined ? {} : { window: mark };
+}
+function projectMessage(msg, format, failedOf, mark) {
     return {
         id: String(msg.id),
         timestamp: msg.timestamp.toISOString(),
         participant: msg.participant,
         author: authorName(msg),
         channelId: getChannelId(msg) ?? null,
-        content: format === 'raw' ? msg.content : flattenContent(msg.content),
+        ...windowField(mark),
+        content: format === 'raw' ? msg.content : flattenContent(msg.content, failedOf(msg)),
     };
 }
+const NO_FAILURES = new Set();
 /** Flatten a message's content blocks to one short, readable string. Text
- *  blocks verbatim; everything else (tool_use/tool_result/thinking/media) as
- *  a short bracketed label — this is for agent readability and search
- *  matching, not byte-faithful reconstruction. */
-function flattenContent(content) {
-    return content.map(blockLabel).join(' ').trim();
+ *  blocks verbatim; a speech tool's call (send-tools.ts) as its name and
+ *  words; everything else (tool_use/tool_result/thinking/media) as a short
+ *  bracketed label — this is for agent readability and search matching, not
+ *  byte-faithful reconstruction. */
+function flattenContent(content, failed = NO_FAILURES) {
+    return content.map((block) => blockLabel(block, failed)).join(' ').trim();
 }
-function blockLabel(block) {
+function blockSpans(content) {
+    const labels = content.map((block) => blockLabel(block));
+    const joined = labels.join(' ');
+    let at = joined.trimStart().length - joined.length;
+    return content.map((block, k) => {
+        const span = { block, at, label: labels[k] };
+        at += span.label.length + 1;
+        return span;
+    });
+}
+function blockLabel(block, failed = NO_FAILURES) {
     switch (block.type) {
         case 'text':
             return block.text;
-        case 'tool_use':
-            return `[tool_use: ${block.name}]`;
-        case 'tool_result':
-            return block.toolName ? `[tool_result: ${block.toolName}]` : '[tool_result]';
+        case 'tool_use': {
+            const said = speechOf(block.name, block.input);
+            return said ? `[${block.name}${failed.has(block.id) ? ERROR_MARK : ''}] ${said.words}` : `[tool_use: ${block.name}]`;
+        }
+        case 'tool_result': {
+            const mark = block.isError ? ERROR_MARK : '';
+            return block.toolName ? `[tool_result: ${block.toolName}${mark}]` : `[tool_result${mark}]`;
+        }
         case 'thinking':
         case 'redacted_thinking':
             return '[thinking]';