@animalabs/agent-framework 0.15.0 → 0.16.0

package/src/modules/history/index.ts

@@ -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.
@@ -30,12 +42,13 @@
 import { Worker } from 'node:worker_threads';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import type { ContextManager, StoredMessage, ChannelCount, ChannelTokenStats } from '@animalabs/context-manager';
+import type { ContextManager, StoredMessage, ChannelCount, ChannelTokenStats, TimeRangeSummaryEntry } from '@animalabs/context-manager';
 import type { ContentBlock } from '@animalabs/membrane';
 import type { Module, ModuleContext } from '../../types/module.js';
 import type { ToolDefinition, ToolCall, ToolResult, ProcessEvent } from '../../types/events.js';
 import type { EventResponse, ProcessState } from '../../types/module.js';
 import type { SearchWorkerMessage, SearchWorkerMatch } from './search-regex-worker.js';
+import type { ChannelRegistry } from '../../mcpl/channel-registry.js';
 
 // ============================================================================
 // Tool input shapes
@@ -67,6 +80,14 @@ interface SearchInput {
   maxScan?: number;
 }
 
+interface OverviewInput {
+  from?: string;
+  to?: string;
+  channelId?: string;
+  level?: number;
+  limit?: number;
+}
+
 // ============================================================================
 // Limits
 // ============================================================================
@@ -93,6 +114,28 @@ 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. */
@@ -119,16 +162,100 @@ export class HistoryModule implements Module {
 
   private ctx: ModuleContext | null = null;
   private cm: ContextManager | null = null;
+  private channelRegistry: ChannelRegistry | null = 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: ContextManager): void {
+  bind(contextManager: ContextManager, channelRegistry?: ChannelRegistry): void {
     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.
+   */
+  private resolveChannel(input: string | undefined): string | undefined {
+    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`).
+   */
+  private earliestMessageMs(toMs: number | undefined): number | undefined {
+    const cm = this.cm as ContextManager;
+    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.
+   */
+  private boundaryMessagesAt(ms: number): StoredMessage[] {
+    const cm = this.cm as ContextManager;
+    return cm.queryMessagesByTime({ fromMs: ms, toMs: ms }).messages;
   }
 
   async start(ctx: ModuleContext): Promise<void> {
@@ -154,7 +281,7 @@ export class HistoryModule implements Module {
           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.' },
           },
         },
       },
@@ -170,7 +297,7 @@ export class HistoryModule implements Module {
           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").' },
@@ -194,13 +321,58 @@ export class HistoryModule implements Module {
             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' as const,
+          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.`,
+            },
+          },
+        },
+      },
     ];
   }
 
@@ -216,6 +388,8 @@ export class HistoryModule implements Module {
           return this.handleExtract((call.input ?? {}) as ExtractInput);
         case 'search':
           return await this.handleSearch((call.input ?? {}) as SearchInput);
+        case 'overview':
+          return this.handleOverview((call.input ?? {}) as OverviewInput);
         default:
           return { success: false, isError: true, error: `Unknown tool: ${call.name}` };
       }
@@ -228,9 +402,9 @@ export class HistoryModule implements Module {
       // 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,
@@ -248,6 +422,7 @@ export class HistoryModule implements Module {
   // ==========================================================================
 
   private handleStats(input: StatsInput): ToolResult {
+    const channelId = this.resolveChannel(input.channelId);
     const fromMs = parseIsoDate(input.from, 'from');
     const toMs = parseIsoDate(input.to, 'to');
     const cm = this.cm as ContextManager;
@@ -255,8 +430,8 @@ export class HistoryModule implements Module {
     let messageCountsAllTime: ChannelCount[] = cm.getChannelMessageCounts();
     let tokenStatsForRange: ChannelTokenStats = 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
@@ -265,7 +440,7 @@ export class HistoryModule implements Module {
         // 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),
       };
     }
 
@@ -284,6 +459,7 @@ export class HistoryModule implements Module {
   // ==========================================================================
 
   private handleExtract(input: ExtractInput): ToolResult {
+    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');
@@ -294,7 +470,7 @@ export class HistoryModule implements Module {
     const result = cm.queryMessagesByTimeAndChannel({
       fromMs,
       toMs,
-      channelId: input.channelId,
+      channelId,
       limit,
       offset,
     });
@@ -317,6 +493,7 @@ export class HistoryModule implements Module {
     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');
@@ -346,7 +523,7 @@ export class HistoryModule implements Module {
     const probe = cm.queryMessagesByTimeAndChannel({
       fromMs,
       toMs,
-      channelId: input.channelId,
+      channelId,
       limit: maxScan + 1,
       offset: 0,
     });
@@ -467,6 +644,380 @@ export class HistoryModule implements Module {
       if (worker) void worker.terminate().catch(() => {});
     }
   }
+
+  // ==========================================================================
+  // overview
+  // ==========================================================================
+
+  private handleOverview(input: OverviewInput): ToolResult {
+    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 as ContextManager;
+
+    let entries: TimeRangeSummaryEntry[];
+    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: Array<{
+      startMs: number;
+      endMs: number;
+      summarized: true;
+      content: string;
+      level: number;
+      stats: ChannelTokenStats;
+      boundaryUncertain?: boolean;
+    }> = entries.map((entry) => ({
+      startMs: entry.startMs,
+      endMs: entry.endMs,
+      summarized: true as const,
+      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: number;
+    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: Array<{ startMs: number; endMs: number; summarized: false; stats: ChannelTokenStats; boundaryUncertain?: boolean }> = [];
+    // 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<string>();
+    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<string, StoredMessage>();
+      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: StoredMessage[] = [];
+      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,
+          };
+        }),
+      },
+    };
+  }
 }
 
 // ============================================================================
@@ -485,6 +1036,19 @@ function parseIsoDate(value: string | undefined, field: string): number | undefi
   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: number | undefined, toMs: number | undefined, fromRaw: string | undefined, toRaw: string | undefined): void {
+  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:
@@ -531,6 +1095,106 @@ function getChannelId(msg: StoredMessage): string | undefined {
   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: ChannelTokenStats, foreign: StoredMessage[]): ChannelTokenStats {
+  if (foreign.length === 0) return stats;
+  const countByChannel = new Map<string, number>();
+  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: StoredMessage[]): ChannelTokenStats {
+  const byChannel = new Map<string, number>();
+  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: ChannelTokenStats, b: ChannelTokenStats): ChannelTokenStats {
+  const byChannel = new Map<string, { messages: number; tokensEstimate: number }>();
+  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: Array<{ startMs: number; endMs: number; summarized: false; stats: ChannelTokenStats; boundaryUncertain?: boolean }>,
+  boundaryMs: number,
+  side: 'before' | 'after',
+  foreign: StoredMessage[],
+): void {
+  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: StoredMessage, format: 'text' | 'raw'): Record<string, unknown> {
   return {
     id: String(msg.id),