@animalabs/agent-framework 0.15.0 → 0.17.0

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

@@ -9,13 +9,25 @@
  * this module can answer "what happened in #foo last Tuesday" against a
  * multi-million-message store without walking the whole log.
  *
- * Three tools:
- *  - `stats`   — per-channel message counts (all-time) + token totals
- *                (range-scoped), for orienting before pulling raw content.
- *  - `extract` — paginated raw messages for a time range and/or channel.
- *  - `search`  — substring/regex match over a narrowed candidate window,
- *                with an explicit truncation signal when the caller's
- *                filter was too broad for `maxScan`.
+ * Four tools:
+ *  - `stats`    — per-channel message counts (all-time) + token totals
+ *                 (range-scoped), for orienting before pulling raw content.
+ *  - `extract`  — paginated raw messages for a time range and/or channel.
+ *  - `search`   — substring/regex match over a narrowed candidate window,
+ *                 with an explicit truncation signal when the caller's
+ *                 filter was too broad for `maxScan`.
+ *  - `overview` — a compression-summary table of contents (zero new LLM
+ *                 calls) for a time range, gap-filled with raw message
+ *                 counts wherever nothing has been summarized yet. See
+ *                 `handleOverview` for the fold-reduction and gap-fill
+ *                 algorithm.
+ *
+ * All four accept `channelId` as either a channel label (e.g. `#general`)
+ * or a raw internal channel id — `resolveChannel()` resolves a label via
+ * the bound `ChannelRegistry`'s durable label history before it reaches any
+ * context-manager call. A host that hasn't wired up MCPL (no registry
+ * bound) sees unchanged behavior: `channelId` is treated as already the raw
+ * internal id.
  *
  * Kept deliberately read-only, same posture as HealthModule: no side
  * effects, no message mutation. `onProcess` is a no-op.
@@ -51,6 +63,26 @@ const SEARCH_DEFAULT_LIMIT = 20;
 const SEARCH_MAX_LIMIT = 100;
 const SEARCH_DEFAULT_MAX_SCAN = 5000;
 const SEARCH_MAX_MAX_SCAN = 50000;
+/**
+ * `overview` response entry cap — unlike `stats`/`extract`/`search`, which
+ * all clamp their result sizes, `overview` had none: an unbounded call
+ * against a long-lived resident with thousands of minted summaries would
+ * return every overlapping summary's full `content` text inlined, with one
+ * `getChannelTokenStats` native call per entry, synchronously, with no
+ * limit — exactly the resource this tool exists to conserve. Default/max
+ * roughly match `extract`'s own scale.
+ */
+const OVERVIEW_DEFAULT_LIMIT = 50;
+const OVERVIEW_MAX_LIMIT = 200;
+/**
+ * A `<@id>`/`<@!id>` Discord-style mention — same shape `ChannelRegistry`
+ * uses for its own DM mention-form matching. A string matching this can
+ * never legitimately BE a raw internal channelId (unlike a bare word,
+ * which an agent could plausibly be echoing back), so `resolveChannel`
+ * treats an unresolved mention the same as an unresolved `#`/`@` label:
+ * a clean error, not a silent empty-result passthrough.
+ */
+const DM_MENTION_RE = /^<@!?\d+>$/;
 /** Characters of surrounding context kept on each side of a search snippet. */
 const SNIPPET_CONTEXT_CHARS = 80;
 /** Fallback snippet length when a match position isn't meaningful to center on. */
@@ -73,15 +105,96 @@ export class HistoryModule {
     name = 'history';
     ctx = null;
     cm = null;
+    channelRegistry = null;
     /**
-     * Wire the context-manager instance. Host calls this after
-     * ContextManager.open() so the module can issue the native index-backed
-     * queries — ModuleContext itself exposes no store/context-manager
-     * reference, only the narrower message CRUD surface (addMessage/getMessage/
-     * queryMessages), which can't do range or channel queries.
+     * Wire the context-manager instance, and optionally the host's
+     * ChannelRegistry. Host calls this after ContextManager.open() so the
+     * module can issue the native index-backed queries — ModuleContext itself
+     * exposes no store/context-manager reference, only the narrower message
+     * CRUD surface (addMessage/getMessage/queryMessages), which can't do
+     * range or channel queries.
+     *
+     * `channelRegistry` is optional: a host without MCPL wired up has no
+     * registry to pass, and `resolveChannel()` falls back to treating
+     * `channelId` as already the raw internal id — today's behavior,
+     * unchanged.
      */
-    bind(contextManager) {
+    bind(contextManager, channelRegistry) {
         this.cm = contextManager;
+        this.channelRegistry = channelRegistry ?? null;
+    }
+    /**
+     * Resolve an agent-supplied channel spec — a label like `#general` or an
+     * already-raw internal channelId — to the internal id used by
+     * context-manager's channel-indexed queries, via the bound
+     * ChannelRegistry's durable label history (`resolveProseTargetDurable`,
+     * which survives the bot disconnecting from or restarting on a channel —
+     * exactly the case that matters for browsing OLD history).
+     *
+     * Falls through the input unchanged when no registry is bound (host
+     * without MCPL — today's behavior). On a registry MISS, the response
+     * depends on whether the spec actually looks like a label: `#general`,
+     * `@name`, or a `<@id>`/`<@!id>` mention (the syntaxes `resolveProseTarget`
+     * itself treats as unambiguously label-shaped — see its own leading
+     * `#`/`@` and mention-regex handling) is very likely a typo or a
+     * never-registered target, not a raw internal id, so a miss there throws
+     * a clean tool error (with any `candidates` suggestions folded in)
+     * instead of quietly treating it as an empty/nonexistent channel. A
+     * mention in particular can never legitimately BE a raw internal
+     * channelId, so the escape-hatch rationale below doesn't even apply to
+     * it. Anything else is
+     * passed through as an escape hatch — an agent can legitimately already
+     * hold a raw channelId (e.g. echoed back by a prior
+     * `stats`/`extract`/`search`/`overview` call), and erroring on that would
+     * break working addressing to "fix" a spec that was never a label at all.
+     *
+     * The thrown message is deliberately NOT `resolved.error` verbatim:
+     * `resolveProseTargetDurable`'s underlying live resolver
+     * (`resolveProseTarget`) writes its error text for a SEND context (e.g.
+     * a DM miss says '...use the send_dm tool') — sensible advice when
+     * you're trying to deliver a message, nonsense advice from a read-only
+     * history tool. This module always uses its own read-only-appropriate
+     * wording instead, regardless of which branch of the live resolver
+     * produced the miss.
+     */
+    resolveChannel(input) {
+        if (!input || !this.channelRegistry)
+            return input;
+        const resolved = this.channelRegistry.resolveProseTargetDurable(input);
+        if (!('error' in resolved))
+            return resolved.channelId;
+        if (input.startsWith('#') || input.startsWith('@') || DM_MENTION_RE.test(input)) {
+            const suggestions = resolved.candidates?.length ? ` Did you mean: ${resolved.candidates.join(', ')}?` : '';
+            throw new Error(`No channel history found for "${input}" — it may never have been seen by this resident, or predates this feature.${suggestions}`);
+        }
+        return input;
+    }
+    /**
+     * Earliest message timestamp anywhere in the store, constrained to
+     * `toMs` when given (never look past the caller's own upper bound while
+     * anchoring). Used by `handleOverview` to anchor its gap-walk cursor when
+     * `from` is omitted — see the cursor-anchoring comment there for why
+     * falling back to "now" instead is wrong. Cheap: a single native
+     * time-indexed query for one message (oldest-first is
+     * `queryMessagesByTime`'s default order). Returns undefined for a
+     * genuinely empty store (or empty up to `toMs`).
+     */
+    earliestMessageMs(toMs) {
+        const cm = this.cm;
+        const probe = cm.queryMessagesByTime({ toMs, limit: 1 });
+        return probe.messages[0]?.timestamp.getTime();
+    }
+    /**
+     * Every raw message sharing exactly `ms` (a single-point, both-ends-
+     * inclusive time query). Used by `handleOverview`'s boundary-tie
+     * disambiguation to see past `getChannelTokenStats`'s aggregate-only,
+     * sequence-blind view of a millisecond — see the correction pass there
+     * for why. Cheap: at most a handful of messages share one millisecond in
+     * practice.
+     */
+    boundaryMessagesAt(ms) {
+        const cm = this.cm;
+        return cm.queryMessagesByTime({ fromMs: ms, toMs: ms }).messages;
     }
     async start(ctx) {
         this.ctx = ctx;
@@ -103,7 +216,7 @@ export class HistoryModule {
                     properties: {
                         from: { type: 'string', description: 'ISO 8601 inclusive lower bound for tokenStatsForRange. Omit for open-ended.' },
                         to: { type: 'string', description: 'ISO 8601 inclusive upper bound for tokenStatsForRange. Omit for open-ended.' },
-                        channelId: { type: 'string', description: 'Restrict both parts of the response to one channel.' },
+                        channelId: { type: 'string', description: 'Restrict both parts of the response to one channel. Accepts a channel label (e.g. "#general") or the raw internal channel id.' },
                     },
                 },
             },
@@ -118,7 +231,7 @@ export class HistoryModule {
                     properties: {
                         from: { type: 'string', description: 'ISO 8601 inclusive lower bound. Omit for open-ended.' },
                         to: { type: 'string', description: 'ISO 8601 inclusive upper bound. Omit for open-ended.' },
-                        channelId: { type: 'string', description: 'Restrict to one channel.' },
+                        channelId: { type: 'string', description: 'Restrict to one channel. Accepts a channel label (e.g. "#general") or the raw internal channel id.' },
                         limit: { type: 'number', description: `Max messages to return (default ${EXTRACT_DEFAULT_LIMIT}, hard cap ${EXTRACT_MAX_LIMIT}). Must be a non-negative integer.` },
                         offset: { type: 'number', description: `Number of matching messages to skip (default 0, capped to ${NATIVE_OFFSET_MAX}). Must be a non-negative integer.` },
                         format: { type: 'string', enum: ['text', 'raw'], description: 'Content rendering (default "text").' },
@@ -141,13 +254,56 @@ export class HistoryModule {
                         caseSensitive: { type: 'boolean', description: 'Case-sensitive match (default false).' },
                         from: { type: 'string', description: 'ISO 8601 inclusive lower bound. Omit for open-ended.' },
                         to: { type: 'string', description: 'ISO 8601 inclusive upper bound. Omit for open-ended.' },
-                        channelId: { type: 'string', description: 'Restrict to one channel.' },
+                        channelId: { type: 'string', description: 'Restrict to one channel. Accepts a channel label (e.g. "#general") or the raw internal channel id.' },
                         limit: { type: 'number', description: `Max matches to return (default ${SEARCH_DEFAULT_LIMIT}, hard cap ${SEARCH_MAX_LIMIT}). Must be a non-negative integer.` },
                         maxScan: { type: 'number', description: `Max candidate messages to scan (default ${SEARCH_DEFAULT_MAX_SCAN}, hard cap ${SEARCH_MAX_MAX_SCAN}). Must be a non-negative integer.` },
                     },
                     required: ['query'],
                 },
             },
+            {
+                name: 'overview',
+                description: 'Browse a time range when you don\'t know exactly what you\'re looking for yet: returns existing ' +
+                    'compression summaries as a table of contents, at zero new LLM cost (purely a read over summaries ' +
+                    'already produced by compression). Spans not yet summarized fall back to raw message counts, ' +
+                    'marked summarized:false. Omit `level` to let each span show its own coarsest available summary ' +
+                    '(spans can end up at DIFFERENT levels — the response then reports maxLevelAvailable rather than ' +
+                    'a single `level`, since no one number would describe a mixed result); pass an exact `level` for ' +
+                    'flat, single-granularity results instead (finer detail = lower level), and the response then ' +
+                    'echoes that `level` back. `channelId` (a label like "#general" or the raw internal id) narrows ' +
+                    'WHICH spans are shown (only spans with at least one message from that channel) and scopes each ' +
+                    'entry\'s messageCount/tokensEstimate to that channel\'s own numbers (spanMessageCount/' +
+                    'spanTokensEstimate carry the whole-span totals alongside, for context) — but does NOT scope a ' +
+                    'kept entry\'s summary TEXT to that channel: compression doesn\'t chunk per-channel, so a ' +
+                    'summary may describe other channels\' traffic too. A wide or unbounded from/to can be expensive ' +
+                    'on a cold cache — same cost class as `stats`\'s tokenStatsForRange — since gap-filling still ' +
+                    'walks the underlying message range wherever nothing has been summarized yet. Response spans are ' +
+                    'capped at `limit`, keeping the MOST RECENT spans and reporting truncated:true + totalSpans when ' +
+                    'more exist — narrow the range or raise `limit` to see further back. `from` after `to` is rejected ' +
+                    '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.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        from: { type: 'string', description: 'ISO 8601 inclusive lower bound. Omit for open-ended.' },
+                        to: { type: 'string', description: 'ISO 8601 inclusive upper bound. Omit for open-ended.' },
+                        channelId: { type: 'string', description: 'Only show spans with traffic from this channel. Accepts a channel label (e.g. "#general") or the raw internal channel id.' },
+                        level: {
+                            type: 'number',
+                            description: 'Exact summary level to fetch, flat (no fold-reduction across levels). Omit to default to ' +
+                                'each span\'s own coarsest currently-available summary (a mix of levels across the response ' +
+                                'is expected and normal), reduced so a folded summary\'s now-superseded child does not also ' +
+                                'appear alongside a coarser entry that already covers its span.',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: `Max spans to return, keeping the most recent (default ${OVERVIEW_DEFAULT_LIMIT}, hard cap ${OVERVIEW_MAX_LIMIT}). Must be a non-negative integer.`,
+                        },
+                    },
+                },
+            },
         ];
     }
     async handleToolCall(call) {
@@ -162,6 +318,8 @@ export class HistoryModule {
                     return this.handleExtract((call.input ?? {}));
                 case 'search':
                     return await this.handleSearch((call.input ?? {}));
+                case 'overview':
+                    return this.handleOverview((call.input ?? {}));
                 default:
                     return { success: false, isError: true, error: `Unknown tool: ${call.name}` };
             }
@@ -175,9 +333,9 @@ export class HistoryModule {
             // capability-absent error ("Chronicle history index unsupported...",
             // thrown by queryMessagesByTime/queryMessagesByChannel/
             // queryMessagesByTimeAndChannel/getChannelMessageCounts/
-            // getChannelTokenStats on a chronicle build that predates the native
-            // index-query capability) — all surfaced as a normal tool error
-            // rather than crashing the module.
+            // getChannelTokenStats/getSummariesInRange/getMaxSummaryLevel on a
+            // chronicle/strategy build that predates the relevant capability) —
+            // all surfaced as a normal tool error rather than crashing the module.
             return {
                 success: false,
                 isError: true,
@@ -192,13 +350,14 @@ export class HistoryModule {
     // stats
     // ==========================================================================
     handleStats(input) {
+        const channelId = this.resolveChannel(input.channelId);
         const fromMs = parseIsoDate(input.from, 'from');
         const toMs = parseIsoDate(input.to, 'to');
         const cm = this.cm;
         let messageCountsAllTime = cm.getChannelMessageCounts();
         let tokenStatsForRange = cm.getChannelTokenStats({ fromMs, toMs });
-        if (input.channelId) {
-            messageCountsAllTime = messageCountsAllTime.filter((c) => c.channelId === input.channelId);
+        if (channelId) {
+            messageCountsAllTime = messageCountsAllTime.filter((c) => c.channelId === channelId);
             tokenStatsForRange = {
                 // Totals stay whole-range (they're documented as store-wide-for-the-range,
                 // not per-channel); only the byChannel breakdown is narrowed. Labeling the
@@ -207,7 +366,7 @@ export class HistoryModule {
                 // misleadingly-merged single-channel total.
                 totalMessages: tokenStatsForRange.totalMessages,
                 totalTokensEstimate: tokenStatsForRange.totalTokensEstimate,
-                byChannel: tokenStatsForRange.byChannel.filter((c) => c.channelId === input.channelId),
+                byChannel: tokenStatsForRange.byChannel.filter((c) => c.channelId === channelId),
             };
         }
         return {
@@ -223,6 +382,7 @@ export class HistoryModule {
     // extract
     // ==========================================================================
     handleExtract(input) {
+        const channelId = this.resolveChannel(input.channelId);
         const fromMs = parseIsoDate(input.from, 'from');
         const toMs = parseIsoDate(input.to, 'to');
         const limit = clampCount(input.limit, EXTRACT_DEFAULT_LIMIT, EXTRACT_MAX_LIMIT, 'limit');
@@ -232,7 +392,7 @@ export class HistoryModule {
         const result = cm.queryMessagesByTimeAndChannel({
             fromMs,
             toMs,
-            channelId: input.channelId,
+            channelId,
             limit,
             offset,
         });
@@ -252,6 +412,7 @@ export class HistoryModule {
         if (!input.query) {
             throw new Error('search requires a non-empty "query".');
         }
+        const channelId = this.resolveChannel(input.channelId);
         const fromMs = parseIsoDate(input.from, 'from');
         const toMs = parseIsoDate(input.to, 'to');
         const limit = clampCount(input.limit, SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LIMIT, 'limit');
@@ -280,7 +441,7 @@ export class HistoryModule {
         const probe = cm.queryMessagesByTimeAndChannel({
             fromMs,
             toMs,
-            channelId: input.channelId,
+            channelId,
             limit: maxScan + 1,
             offset: 0,
         });
@@ -391,6 +552,369 @@ export class HistoryModule {
                 void worker.terminate().catch(() => { });
         }
     }
+    // ==========================================================================
+    // overview
+    // ==========================================================================
+    handleOverview(input) {
+        const channelId = this.resolveChannel(input.channelId);
+        const fromMs = parseIsoDate(input.from, 'from');
+        const toMs = parseIsoDate(input.to, 'to');
+        assertOrderedRange(fromMs, toMs, input.from, input.to);
+        const limit = clampCount(input.limit, OVERVIEW_DEFAULT_LIMIT, OVERVIEW_MAX_LIMIT, 'limit');
+        const cm = this.cm;
+        let entries;
+        if (input.level !== undefined) {
+            // Caller asked for one exact level: flat, no fold-reduction — they
+            // want that granularity, not the coarsest-available mix below.
+            entries = cm.getSummariesInRange({ fromMs, toMs, level: input.level });
+        }
+        else {
+            // No level given: fetch every level overlapping the range, then
+            // reduce to only "current" (non-superseded) entries. getSummariesInRange
+            // does NOT filter by fold status — a folded child and the coarser
+            // parent it was folded into can BOTH independently overlap the query
+            // range and BOTH come back in `all` (see TimeRangeSummaryEntry.parentId's
+            // doc comment in context-manager).
+            //
+            // Two complementary checks, because an ancestor CHAIN can be broken:
+            // `listSummariesInRange` silently skips an entry whose source range no
+            // longer resolves (a pruned/redacted source message, or a viewFilter
+            // exclusion — a real, named failure mode elsewhere in
+            // autobiographical.ts's contiguousMergeCandidates). If that skipped
+            // entry is an INTERMEDIATE level, its children's parentId points at an
+            // id that never made it into `all`, so the immediate-parent check
+            // alone can't see past the gap and a since-superseded child survives
+            // alongside the coarser grandparent that already covers its span.
+            //  1. Immediate-parent check (cheap, covers the intact-chain case).
+            //  2. Containment sweep (backstop, robust to a broken chain): drop an
+            //     entry if any OTHER fetched entry is STRICTLY coarser (higher
+            //     level) and its span fully contains this one — that entry
+            //     already covers the same messages regardless of whether the
+            //     parentId pointer chain between them survived intact.
+            //     EXCEPTION: a zero-width entry (e.startMs === e.endMs — a tiny
+            //     chunk that landed entirely within one millisecond) that merely
+            //     TOUCHES a coarser entry's boundary at exactly that one point
+            //     trivially satisfies "f.startMs <= e.startMs && f.endMs >=
+            //     e.endMs" without f actually being an ancestor — a genuinely
+            //     unrelated, later-starting/earlier-ending coarser summary can
+            //     coincidentally share one endpoint with it. A real (non-zero-
+            //     width) entry can't trigger this false positive: satisfying
+            //     containment on BOTH ends while only touching at one means f
+            //     must still genuinely extend past the entry's other, non-touching
+            //     side. A genuine same-point fold is still caught by the
+            //     immediate-parentId check above when the chain is intact.
+            // O(n^2) in the fetched set size, which is fine at summary-archive
+            // scale (bounded by how much has been compressed into this range, not
+            // by raw message count).
+            const all = cm.getSummariesInRange({ fromMs, toMs });
+            const idsInSet = new Set(all.map((e) => e.id));
+            entries = all.filter((e) => {
+                if (e.parentId && idsInSet.has(e.parentId))
+                    return false;
+                return !all.some((f) => {
+                    if (f.id === e.id || f.level <= e.level)
+                        return false;
+                    if (!(f.startMs <= e.startMs && f.endMs >= e.endMs))
+                        return false;
+                    if (e.startMs === e.endMs && (e.startMs === f.startMs || e.endMs === f.endMs))
+                        return false;
+                    return true;
+                });
+            });
+        }
+        entries.sort((a, b) => a.startMs - b.startMs);
+        // Per-summary channel/token stats — same call `stats` uses, scoped to
+        // just this entry's own source span.
+        const summarized = entries.map((entry) => ({
+            startMs: entry.startMs,
+            endMs: entry.endMs,
+            summarized: true,
+            content: entry.content,
+            level: entry.level,
+            stats: cm.getChannelTokenStats({ fromMs: entry.startMs, toMs: entry.endMs }),
+        }));
+        // Gap-fill: walk the sorted summary spans and probe seams wide enough
+        // to be worth a getChannelTokenStats call. A gap with real traffic
+        // becomes a synthetic summarized:false entry; an empty gap (nothing
+        // happened there) is skipped rather than cluttering the response.
+        //
+        // Cursor anchoring when `from` is omitted: NOT "now" — with zero
+        // summaries minted yet (first-ever call, or a PassthroughStrategy host
+        // where getSummariesInRange always returns []) that would make the
+        // whole walk a zero-width no-op and silently report entries:[] even
+        // though the store is full of messages. And even WITH summaries
+        // present, starting at the first summary's startMs silently hides any
+        // older unsummarized traffic that predates every summary (e.g. history
+        // from before compression was enabled). Anchor instead at the earlier
+        // of "the first summary's start" and "the earliest real message in the
+        // store" — falling back to Date.now() only when NEITHER exists, i.e.
+        // the store is genuinely empty, where entries:[] is the correct answer.
+        const rangeEnd = toMs ?? Date.now();
+        const firstEntryStartMs = entries[0]?.startMs;
+        let cursor;
+        if (fromMs !== undefined) {
+            cursor = fromMs;
+        }
+        else {
+            const earliestMessageMs = this.earliestMessageMs(toMs);
+            cursor =
+                earliestMessageMs !== undefined && firstEntryStartMs !== undefined
+                    ? Math.min(earliestMessageMs, firstEntryStartMs)
+                    : earliestMessageMs ?? firstEntryStartMs ?? Date.now();
+        }
+        // Effective query start — captured BEFORE the gap loop below mutates
+        // `cursor` (it walks forward past each entry's endMs). Needed by the
+        // boundary-tie correction pass further down to clamp its output to
+        // what the caller actually asked for (see the comment there): when
+        // `fromMs` is omitted this equals the resolved anchor above, not
+        // `-Infinity` — an open-ended query still has a concrete effective
+        // start, it's just not caller-supplied.
+        const rangeStart = cursor;
+        const gaps = [];
+        // True once `cursor` has been advanced past at least one real summary
+        // entry's endMs — only THEN is `cursor` itself a value that a summary
+        // already claims (and so needs a +1 nudge below to probe half-open).
+        // The very first gap (before any entry) sits against `fromMs` or an
+        // earliest-message anchor, neither of which any summary has claimed,
+        // so it must NOT be nudged — nudging it would skip a real message
+        // sitting exactly at the anchor.
+        let cursorIsEntryBoundary = false;
+        for (const entry of entries) {
+            // getChannelTokenStats's range is BOTH-ENDS INCLUSIVE (chronicle's
+            // gte/lte), so probing the raw [cursor, entry.startMs] pair would
+            // re-count the neighboring summaries' own boundary messages (ts ===
+            // cursor from the entry before, ts === entry.startMs from this one)
+            // as if they were unsummarized — fabricating a phantom gap between
+            // EVERY pair of adjacent summaries, even when they cover 100% of
+            // traffic with zero real gap between them. Narrow to a half-open
+            // probe instead, and only skip the call when narrowing collapsed the
+            // width to zero or negative (`probeTo < probeFrom` — an entry that
+            // starts exactly where the previous one ended, or crosses it).
+            //
+            // Deliberately NO minimum-width threshold beyond that: an earlier
+            // version skipped any seam narrower than a fixed few seconds as
+            // "bookkeeping noise", but that check ran BEFORE the
+            // stats.totalMessages > 0 check below that actually decides whether
+            // real traffic exists — so a query window or a between-summaries
+            // seam narrower than the threshold silently reported entries:[] even
+            // when full of real messages (verified repro: 300 real messages,
+            // zero summaries, a 4-second window). The totalMessages > 0 check
+            // that follows is the one that's actually correct; nothing should
+            // gate the probe ahead of it.
+            const probeFrom = cursorIsEntryBoundary ? cursor + 1 : cursor;
+            const probeTo = entry.startMs - 1;
+            if (probeTo >= probeFrom) {
+                const stats = cm.getChannelTokenStats({ fromMs: probeFrom, toMs: probeTo });
+                if (stats.totalMessages > 0)
+                    gaps.push({ startMs: probeFrom, endMs: probeTo, summarized: false, stats });
+            }
+            cursor = Math.max(cursor, entry.endMs);
+            cursorIsEntryBoundary = true;
+        }
+        {
+            // Trailing gap: rangeEnd is either the caller's own inclusive `to`
+            // bound or Date.now() — never a summary boundary — so only the LOWER
+            // end gets the half-open nudge (same reasoning as inside the loop).
+            // Same no-threshold reasoning as above.
+            const probeFrom = cursorIsEntryBoundary ? cursor + 1 : cursor;
+            const probeTo = rangeEnd;
+            if (probeTo >= probeFrom) {
+                const stats = cm.getChannelTokenStats({ fromMs: probeFrom, toMs: probeTo });
+                if (stats.totalMessages > 0)
+                    gaps.push({ startMs: probeFrom, endMs: probeTo, summarized: false, stats });
+            }
+        }
+        // Boundary-tie disambiguation: getChannelTokenStats operates on
+        // wall-clock TIME ranges and has no visibility into chronicle's
+        // sequence numbers, so whenever a message that's genuinely NOT part of
+        // a summary's source span happens to share the EXACT millisecond with
+        // that summary's own first/last covered message (rapid-fire appends —
+        // wall-clock ms resolution isn't unique, sequence is), the per-span
+        // aggregate calls above silently fold it into the summary's counts —
+        // and the adjacent gap probe (which deliberately EXCLUDES that same ms
+        // via the half-open nudge, on the assumption the boundary ms belongs
+        // entirely to the neighboring summary) has no way to see it at all: it
+        // doesn't just get miscounted, it vanishes from the response entirely.
+        //
+        // Resolved using TimeRangeSummaryEntry's firstSequence/lastSequence
+        // (chronicle's per-record sequence number — strictly monotonic, never
+        // ties, unlike wall-clock ms) against the ACTUAL messages at each
+        // boundary ms (queried directly via boundaryMessagesAt — cheap, at
+        // most a handful of messages share one millisecond in practice).
+        //
+        // A "foreign" message found this way either belongs to ANOTHER fetched
+        // summary entry (its sequence falls in THAT entry's own range — its
+        // own inclusive-range getChannelTokenStats call already counts it
+        // correctly, so this entry just needs the erroneous count subtracted,
+        // nothing added elsewhere) or is genuinely unsummarized (belongs to the
+        // adjacent gap, extending it — or creating a new point-width gap
+        // fragment if no gap was probed there at all, which is exactly the
+        // "vanishes entirely" failure mode this fix exists for).
+        //
+        // MESSAGE COUNT/membership is corrected exactly — we know precisely
+        // which raw messages are foreign and their channelId. TOKEN weight for
+        // those specific messages is deliberately NOT recomputed:
+        // getChannelTokenStats can only report tokens for a TIME range, never
+        // for an arbitrary message subset, and reimplementing token estimation
+        // locally would silently drift from context-manager's own (mutable,
+        // calibration-adjusted) estimate — worse than admitting the gap. Any
+        // entry this pass touches is marked `boundaryUncertain: true` so a
+        // caller knows its tokensEstimate may be off by the small, bounded
+        // weight of the message(s) that moved, even though messageCount there
+        // is exact.
+        // Messages already routed into a gap by an EARLIER entry's pass in this
+        // same loop — without this, two entries that both touch the same
+        // boundary millisecond (e.g. summary A ends and summary B starts at the
+        // exact same ms, with one genuinely-unsummarized stray message also at
+        // that ms) each independently decide "not mine, not any other fetched
+        // SUMMARY's either" and BOTH call mergeForeignIntoGap for the same
+        // stray — mergeForeignIntoGap's own gap-lookup only checks for a gap
+        // immediately adjacent to ITS OWN entry's boundary, so it can't see the
+        // point-width gap the other entry's pass just created one step away,
+        // and the same message gets double-counted into two separate gap
+        // entries. Tracking ids already merged (not just already-seen) across
+        // the whole loop — not just within one entry's own pass — closes this.
+        const alreadyMergedForeignIds = new Set();
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            const own = summarized[i];
+            // Defensive: firstSequence/lastSequence are new fields on
+            // TimeRangeSummaryEntry (added alongside this correction pass) — if
+            // this module ever ends up running against an OLDER published
+            // context-manager whose getSummariesInRange doesn't populate them
+            // (undefined, not a type error at runtime), every comparison below
+            // would silently evaluate false, foreignById would always be empty,
+            // and this whole pass would silently no-op — resurrecting the exact
+            // boundary-tie bug it exists to fix, with no error and no
+            // boundaryUncertain signal. Skip explicitly instead of trusting the
+            // type system alone.
+            if (typeof entry.firstSequence !== 'number' || typeof entry.lastSequence !== 'number')
+                continue;
+            const boundaryMsList = entry.startMs === entry.endMs ? [entry.startMs] : [entry.startMs, entry.endMs];
+            const foreignById = new Map();
+            for (const ms of boundaryMsList) {
+                for (const m of this.boundaryMessagesAt(ms)) {
+                    if (m.sequence < entry.firstSequence || m.sequence > entry.lastSequence) {
+                        foreignById.set(String(m.id), m);
+                    }
+                }
+            }
+            if (foreignById.size === 0)
+                continue;
+            const genuinelyUnsummarized = [];
+            for (const m of foreignById.values()) {
+                const owner = entries.find((e) => e.id !== entry.id &&
+                    typeof e.firstSequence === 'number' &&
+                    typeof e.lastSequence === 'number' &&
+                    m.sequence >= e.firstSequence &&
+                    m.sequence <= e.lastSequence);
+                if (!owner && !alreadyMergedForeignIds.has(String(m.id)))
+                    genuinelyUnsummarized.push(m);
+            }
+            own.stats = subtractMessagesFromStats(own.stats, [...foreignById.values()]);
+            own.boundaryUncertain = true;
+            // getSummariesInRange intentionally returns WHOLE summaries that
+            // overlap the query — a summary's own startMs/endMs can legitimately
+            // extend past the caller's requested [rangeStart, rangeEnd] (that's
+            // correct: the summary itself, and its corrected messageCount above,
+            // belong in the response either way). But a correction-pass GAP
+            // anchored at entry.startMs/entry.endMs must NOT be added when that
+            // boundary itself falls outside the query window — the ordinary gap
+            // walk elsewhere in this function never synthesizes a gap outside
+            // [rangeStart, rangeEnd], and this pass shouldn't either. Without
+            // this check, a narrow-window query landing entirely inside an
+            // already-summarized span could still surface phantom
+            // summarized:false rows anchored at that summary's FAR boundaries,
+            // outside anything the caller asked about.
+            const before = genuinelyUnsummarized.filter((m) => m.sequence < entry.firstSequence);
+            const after = genuinelyUnsummarized.filter((m) => m.sequence > entry.lastSequence);
+            const startInRange = entry.startMs >= rangeStart && entry.startMs <= rangeEnd;
+            const endInRange = entry.endMs >= rangeStart && entry.endMs <= rangeEnd;
+            if (before.length > 0 && startInRange) {
+                mergeForeignIntoGap(gaps, entry.startMs, 'before', before);
+                for (const m of before)
+                    alreadyMergedForeignIds.add(String(m.id));
+            }
+            if (after.length > 0 && endInRange) {
+                mergeForeignIntoGap(gaps, entry.endMs, 'after', after);
+                for (const m of after)
+                    alreadyMergedForeignIds.add(String(m.id));
+            }
+        }
+        // Merge summary-backed + gap-filled spans, apply the channel filter
+        // (drop any span with zero messages from the requested channel — but
+        // keep a kept summary's `content` unfiltered: compression doesn't chunk
+        // per-channel, so the text may legitimately describe other channels
+        // too), sort, and project to the response shape.
+        const merged = [...summarized, ...gaps].sort((a, b) => a.startMs - b.startMs);
+        const filtered = channelId
+            ? merged.filter((e) => e.stats.byChannel.some((c) => c.channelId === channelId))
+            : merged;
+        // Cap the final entry list — mirrors search's truncated:true contract.
+        // Keeps the MOST RECENT `limit` spans when the cap is hit (a browse
+        // tool defaulting to "what's happened lately" should keep the tail, not
+        // silently cut off at the oldest end) while the survivors stay in their
+        // own chronological (oldest-first) order within the response, matching
+        // extract's/search's own ordering convention.
+        const totalSpans = filtered.length;
+        const truncated = totalSpans > limit;
+        // NOT `filtered.slice(-limit)`: `slice(-0)` is `slice(+0)` (negative
+        // zero coerces away), so `limit: 0` — a value clampCount explicitly
+        // accepts — would slice from index 0 and return the ENTIRE array while
+        // still reporting truncated:true. Same bug class already fixed twice
+        // elsewhere in this project (search's/extract's own limit:0 bugs);
+        // `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;
+        return {
+            success: true,
+            data: {
+                range: { from: input.from ?? null, to: input.to ?? null },
+                // Only meaningful as a single number when `level` was pinned: the
+                // default (fold-reduced) result mixes spans at whatever level each
+                // one's own coarsest-available summary happens to be, so reporting
+                // a single `level` there would be actively misleading (an agent
+                // could see level:3 while looking at an L1 entry). Each summarized
+                // entry already carries its own accurate `level`; the top-level
+                // field instead reports the ceiling as `maxLevelAvailable` in that
+                // case, distinctly named so it can't be mistaken for a uniform
+                // per-entry level.
+                ...(input.level !== undefined ? { level: input.level } : { maxLevelAvailable: cm.getMaxSummaryLevel() }),
+                truncated,
+                totalSpans,
+                entries: capped.map((e) => {
+                    // When channelId narrows the response, the numbers an agent will
+                    // actually reason over (messageCount/tokensEstimate) are scoped
+                    // to THAT channel — not the whole span, which can otherwise
+                    // include far more traffic from other channels sharing the same
+                    // summarized/gap span. This is a deliberate departure from
+                    // `stats`, which keeps its top-level totals whole-range and only
+                    // narrows the byChannel breakdown (documented in handleStats) —
+                    // here, an agent that asked to narrow by channel is reasoning
+                    // about that channel specifically, so the whole-span totals stay
+                    // available under distinctly-named spanMessageCount/
+                    // spanTokensEstimate instead of silently double-serving as both.
+                    const channelStats = channelId ? e.stats.byChannel.find((c) => c.channelId === channelId) : undefined;
+                    return {
+                        from: new Date(e.startMs).toISOString(),
+                        to: new Date(e.endMs).toISOString(),
+                        summarized: e.summarized,
+                        ...(e.summarized ? { 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
+                        // still exact there; tokensEstimate may be off by the small,
+                        // bounded weight of the message(s) that moved.
+                        ...(e.boundaryUncertain ? { boundaryUncertain: true } : {}),
+                        messageCount: channelStats ? channelStats.messages : e.stats.totalMessages,
+                        tokensEstimate: channelStats ? channelStats.tokensEstimate : e.stats.totalTokensEstimate,
+                        ...(channelId ? { spanMessageCount: e.stats.totalMessages, spanTokensEstimate: e.stats.totalTokensEstimate } : {}),
+                        byChannel: e.stats.byChannel,
+                    };
+                }),
+            },
+        };
+    }
 }
 // ============================================================================
 // Helpers
@@ -407,6 +931,18 @@ function parseIsoDate(value, field) {
     }
     return ms;
 }
+/**
+ * Reject an inverted range (`from` after `to`) with a clear error instead of
+ * silently matching nothing. Used by `overview`, where "found nothing" is
+ * reported as `entries: []` — the same shape a caller sees for a genuinely
+ * quiet span — so a simple from/to mixup should never be allowed to look
+ * like "you have no history here" instead of the input mistake it is.
+ */
+function assertOrderedRange(fromMs, toMs, fromRaw, toRaw) {
+    if (fromMs !== undefined && toMs !== undefined && fromMs > toMs) {
+        throw new Error(`"from" (${fromRaw}) must not be after "to" (${toRaw}).`);
+    }
+}
 /**
  * Validate a pagination-ish numeric input (limit/offset/maxScan) and clamp
  * it to an upper bound. `Math.min(value, max)` alone is NOT sufficient here:
@@ -453,6 +989,101 @@ function getChannelId(msg) {
         return metadata.channelId;
     return typeof metadata?.external?.channelId === 'string' ? metadata.external.channelId : undefined;
 }
+// ============================================================================
+// overview: boundary-tie correction helpers (see handleOverview)
+// ============================================================================
+/**
+ * Subtract the exact per-channel MESSAGE COUNT of `foreign` from `stats` —
+ * used to correct a summary entry's own stats once boundary-tie
+ * disambiguation finds messages counted in error (see handleOverview's
+ * correction pass). Deliberately leaves totalTokensEstimate/
+ * byChannel[].tokensEstimate untouched — see that pass's header comment
+ * for why an exact token subtraction isn't achievable from the available
+ * API.
+ */
+function subtractMessagesFromStats(stats, foreign) {
+    if (foreign.length === 0)
+        return stats;
+    const countByChannel = new Map();
+    for (const m of foreign) {
+        const ch = getChannelId(m);
+        if (ch === undefined)
+            continue; // unchanneled messages aren't tracked in byChannel at all
+        countByChannel.set(ch, (countByChannel.get(ch) ?? 0) + 1);
+    }
+    const byChannel = stats.byChannel
+        .map((c) => ({ ...c, messages: Math.max(0, c.messages - (countByChannel.get(c.channelId) ?? 0)) }))
+        .filter((c) => c.messages > 0);
+    return {
+        totalMessages: Math.max(0, stats.totalMessages - foreign.length),
+        totalTokensEstimate: stats.totalTokensEstimate,
+        byChannel,
+    };
+}
+/**
+ * Exact per-channel MESSAGE COUNT for a small raw message list, with
+ * tokensEstimate left at 0 (unknown — see handleOverview's boundary-tie
+ * correction pass). Only ever used to build a BRAND NEW synthetic gap
+ * fragment out of boundary-tie foreign messages — a real query result
+ * always goes through the real getChannelTokenStats aggregate instead.
+ */
+function statsFromMessages(messages) {
+    const byChannel = new Map();
+    for (const m of messages) {
+        const ch = getChannelId(m);
+        if (ch === undefined)
+            continue;
+        byChannel.set(ch, (byChannel.get(ch) ?? 0) + 1);
+    }
+    return {
+        totalMessages: messages.length,
+        totalTokensEstimate: 0,
+        byChannel: [...byChannel.entries()].map(([channelId, count]) => ({ channelId, messages: count, tokensEstimate: 0 })),
+    };
+}
+/** Add `b`'s counts into `a` — used to fold boundary-tie foreign messages
+ *  into an already-probed gap's stats. */
+function mergeStats(a, b) {
+    const byChannel = new Map();
+    for (const c of a.byChannel)
+        byChannel.set(c.channelId, { messages: c.messages, tokensEstimate: c.tokensEstimate });
+    for (const c of b.byChannel) {
+        const cur = byChannel.get(c.channelId) ?? { messages: 0, tokensEstimate: 0 };
+        cur.messages += c.messages;
+        cur.tokensEstimate += c.tokensEstimate;
+        byChannel.set(c.channelId, cur);
+    }
+    return {
+        totalMessages: a.totalMessages + b.totalMessages,
+        totalTokensEstimate: a.totalTokensEstimate + b.totalTokensEstimate,
+        byChannel: [...byChannel.entries()].map(([channelId, v]) => ({ channelId, ...v })),
+    };
+}
+/**
+ * Fold boundary-tie `foreign` messages into whichever gap sits immediately
+ * `side` of `boundaryMs`, extending that gap's span to include the tied
+ * millisecond — or, if no such gap currently exists (the common case when
+ * the seam had zero OTHER real traffic and so was never probed into
+ * existence), create a new point-width gap fragment exactly at
+ * `boundaryMs` to hold them. Always marks the result `boundaryUncertain:
+ * true` (see handleOverview's boundary-tie correction pass for what that
+ * means).
+ */
+function mergeForeignIntoGap(gaps, boundaryMs, side, foreign) {
+    const addend = statsFromMessages(foreign);
+    const existing = side === 'before' ? gaps.find((g) => g.endMs === boundaryMs - 1) : gaps.find((g) => g.startMs === boundaryMs + 1);
+    if (existing) {
+        existing.stats = mergeStats(existing.stats, addend);
+        if (side === 'before')
+            existing.endMs = boundaryMs;
+        else
+            existing.startMs = boundaryMs;
+        existing.boundaryUncertain = true;
+    }
+    else {
+        gaps.push({ startMs: boundaryMs, endMs: boundaryMs, summarized: false, stats: addend, boundaryUncertain: true });
+    }
+}
 function projectMessage(msg, format) {
     return {
         id: String(msg.id),