@animalabs/agent-framework 0.19.0 → 0.20.0

package/src/modules/history/index.ts

@@ -49,6 +49,7 @@ import type { ToolDefinition, ToolCall, ToolResult, ProcessEvent } from '../../t
 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';
+import { SemanticIndexClient, SemanticIndexer, messageIndexText, type SemanticIndexConfig, type SyncReport, type PendingChanges } from './semantic.js';
 
 // ============================================================================
 // Tool input shapes
@@ -60,6 +61,9 @@ interface StatsInput {
   channelId?: string;
 }
 
+/** One author spec or several — see `matchesAuthorFilter`. */
+type AuthorSpec = string | string[];
+
 interface ExtractInput {
   from?: string;
   to?: string;
@@ -67,15 +71,37 @@ interface ExtractInput {
   limit?: number;
   offset?: number;
   format?: 'text' | 'raw';
+  author?: AuthorSpec;
+  excludeAuthor?: AuthorSpec;
+  maxScan?: number;
+  /** Resume point of an author-filtered scan (from a previous `resume`). */
+  windowOffset?: number;
+  /** Id of the message just before `windowOffset` (from a previous `resume`). */
+  afterId?: string | null;
+  /** Time-ordered (no channelId) resume only: the store's highest sequence when the previous call ran. */
+  seqMark?: number;
+  aroundId?: string;
+  before?: number;
+  after?: number;
+  allChannels?: boolean;
 }
 
 interface SearchInput {
   query: string;
   regex?: boolean;
   caseSensitive?: boolean;
+  wholeWord?: boolean;
   from?: string;
   to?: string;
   channelId?: string;
+  author?: AuthorSpec;
+  excludeAuthor?: AuthorSpec;
+  order?: 'oldest' | 'newest';
+  /** Continuation only (from a previous `resume`): messages at exactly the
+   *  resume bound's millisecond whose sequence lies in [lo, hi] were already
+   *  scanned. A range, not a count, so a message added or removed at that
+   *  millisecond between calls can't shift what gets skipped. */
+  skipSequences?: [number, number];
   limit?: number;
   maxScan?: number;
 }
@@ -88,6 +114,22 @@ interface OverviewInput {
   limit?: number;
 }
 
+interface SemanticSearchInput {
+  query: string;
+  limit?: number;
+  from?: string;
+  to?: string;
+  channelId?: string;
+  kinds?: 'messages' | 'summaries' | 'both';
+  level?: number;
+  minScore?: number;
+}
+
+export interface HistoryModuleOptions {
+  /** Enable `semantic_search` against a shared embed-service (see ./semantic.ts). Absent = tool not offered. */
+  semantic?: SemanticIndexConfig;
+}
+
 // ============================================================================
 // Limits
 // ============================================================================
@@ -109,6 +151,42 @@ const EXTRACT_MAX_LIMIT = 200;
  */
 const NATIVE_OFFSET_MAX = 0xffffffff; // 4294967295
 
+/**
+ * `extract` with an author filter can't lean on a native index (chronicle
+ * indexes time and channel, not author), so it pages through the time/channel
+ * window and filters in-process. Bounded like `search`'s maxScan, with the
+ * same explicit truncated/scannedThrough signal when the window is larger.
+ */
+const EXTRACT_FILTER_DEFAULT_MAX_SCAN = 10000;
+const EXTRACT_FILTER_MAX_MAX_SCAN = 50000;
+/** How far (in window positions) a filtered-extract resume looks for its
+ *  `afterId` when the window moved since the previous call. */
+const RELOCATE_RADIUS = 1000;
+/** Most appends a no-channel resume walks back through to check for
+ *  messages added behind its cursor; past it the check is reported as
+ *  unverified rather than failing. */
+const APPENDED_SCAN_CAP = 200_000;
+/** Native page size for the in-process filtered scans above. */
+const FILTER_SCAN_PAGE = 1000;
+
+/** `extract({aroundId})` window sizes, per side. */
+const AROUND_DEFAULT = 10;
+const AROUND_MAX = 100;
+/** Upper bound on messages sharing the anchor's millisecond that
+ *  `extract({aroundId})` will fetch to order them by sequence — real stores
+ *  see a handful; past this the call fails loudly rather than guessing. */
+const AROUND_TIE_CAP = 5000;
+
+function tieCapError(anchorId: string, n: number): Error {
+  return new Error(
+    `Message ${anchorId} shares its timestamp with ${n} messages (more than ${AROUND_TIE_CAP}), too many to order ` +
+      'around it. Use extract with from/to set to that instant instead.',
+  );
+}
+
+/** Largest valid Date value (ms) — an open newest edge. */
+const MAX_DATE_MS = 8.64e15;
+
 const SEARCH_DEFAULT_LIMIT = 20;
 const SEARCH_MAX_LIMIT = 100;
 const SEARCH_DEFAULT_MAX_SCAN = 5000;
@@ -126,6 +204,16 @@ const SEARCH_MAX_MAX_SCAN = 50000;
 const OVERVIEW_DEFAULT_LIMIT = 50;
 const OVERVIEW_MAX_LIMIT = 200;
 
+const SEMANTIC_DEFAULT_LIMIT = 10;
+const SEMANTIC_MAX_LIMIT = 50;
+/** Largest k sent to the embed-service when over-fetching past dropped hits (its own cap is 200). */
+const SEMANTIC_MAX_FETCH = 200;
+/** Local snippet: the leading SEMANTIC_SNIPPET_CHARS of the current text. */
+function snippetOf(text: string): string {
+  return text.length <= SEMANTIC_SNIPPET_CHARS ? text : `${text.slice(0, SEMANTIC_SNIPPET_CHARS)}…`;
+}
+const SEMANTIC_SNIPPET_CHARS = 400;
+
 /**
  * A `<@id>`/`<@!id>` Discord-style mention — same shape `ChannelRegistry`
  * uses for its own DM mention-form matching. A string matching this can
@@ -157,12 +245,37 @@ const SEARCH_REGEX_TIMEOUT_MS = 2000;
  *  directory this module's own compiled output lives in. */
 const SEARCH_WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'search-regex-worker.js');
 
+// Declared as an array (tool-schema dialects vary on anyOf); a bare string is
+// also accepted at runtime — see toAuthorSet.
+const AUTHOR_SPEC_JSON_SCHEMA = { type: 'array', items: { type: 'string' } };
+const AUTHOR_SCHEMA = {
+  ...AUTHOR_SPEC_JSON_SCHEMA,
+  description:
+    'Only messages written by one of these authors (an array of names or ids). Matches, case-insensitively and exactly, ' +
+    'the author\'s display name or user id (a leading "@" or a <@id> mention is accepted), or the ' +
+    'stored participant for messages without author metadata — e.g. your own turns, under your name.',
+};
+const EXCLUDE_AUTHOR_SCHEMA = {
+  ...AUTHOR_SPEC_JSON_SCHEMA,
+  description: 'Drop messages written by any of these authors (an array of names or ids). Same matching as `author`.',
+};
+
 export class HistoryModule implements Module {
   readonly name = 'history';
 
   private ctx: ModuleContext | null = null;
   private cm: ContextManager | null = null;
   private channelRegistry: ChannelRegistry | null = null;
+  private readonly semanticCfg: SemanticIndexConfig | null;
+  private semanticClient: SemanticIndexClient | null = null;
+  private indexer: SemanticIndexer | null = null;
+  private syncTimer: ReturnType<typeof setInterval> | null = null;
+  private firstSyncTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(options: HistoryModuleOptions = {}) {
+    this.semanticCfg = options.semantic ?? null;
+    if (this.semanticCfg) this.semanticClient = new SemanticIndexClient(this.semanticCfg);
+  }
 
   /**
    * Wire the context-manager instance, and optionally the host's
@@ -180,6 +293,15 @@ export class HistoryModule implements Module {
   bind(contextManager: ContextManager, channelRegistry?: ChannelRegistry): void {
     this.cm = contextManager;
     this.channelRegistry = channelRegistry ?? null;
+    if (this.semanticCfg && this.semanticClient) {
+      this.indexer?.dispose();
+      this.indexer = new SemanticIndexer(contextManager, this.semanticClient, this.semanticCfg, (m) => console.warn(m));
+      // start() may already have run (framework start before host bind):
+      // wire persistence now, or pending changes are neither restored nor saved.
+      if (this.ctx) this.wireIndexer(this.ctx);
+      else this.indexer.attach();
+      this.startSyncTimer();
+    }
   }
 
   /**
@@ -258,12 +380,255 @@ export class HistoryModule implements Module {
     return cm.queryMessagesByTime({ fromMs: ms, toMs: ms }).messages;
   }
 
+  /** Messages at exactly `ms` (in `channelId` when given). Bounded by
+   *  AROUND_TIE_CAP: past it a same-millisecond group is too large to step
+   *  through by sequence, and the caller should narrow instead. */
+  private countAtMs(ms: number, channelId: string | undefined): number {
+    const cm = this.cm as ContextManager;
+    const n =
+      channelId !== undefined
+        ? cm.queryMessagesByTimeAndChannel({ fromMs: ms, toMs: ms, channelId, limit: 0 }).matchedCount
+        : cm.queryMessagesByTime({ fromMs: ms, toMs: ms, limit: AROUND_TIE_CAP + 1 }).messages.length;
+    if (n > AROUND_TIE_CAP) {
+      throw new Error(
+        `More than ${AROUND_TIE_CAP} messages share the instant ${new Date(ms).toISOString()}; a continuation can't step ` +
+          'through them. Narrow the search with channelId/author instead.',
+      );
+    }
+    return n;
+  }
+
+  /** Highest sequence in the store right now (the last append), or -1 when empty. */
+  private storeSeqMark(): number {
+    const cm = this.cm as ContextManager;
+    const count = cm.getMessageCount();
+    if (count === 0) return -1;
+    return cm.getMessageWindow(count - 1, 1).messages[0]?.sequence ?? -1;
+  }
+
+  /**
+   * Of the messages appended since `seqMark` (the store's append tail above
+   * it, walked back in pages), the ones `relevant` keeps. Unrelated appends
+   * cost a look but never count. `complete` is false when the walk stopped
+   * at APPENDED_SCAN_CAP before reaching seqMark — the result is then a
+   * lower bound, not a verification.
+   */
+  private appendedSince(
+    seqMark: number,
+    relevant: (m: StoredMessage) => boolean,
+  ): { messages: StoredMessage[]; complete: boolean } {
+    const cm = this.cm as ContextManager;
+    const out: StoredMessage[] = [];
+    let looked = 0;
+    let end = cm.getMessageCount();
+    while (end > 0) {
+      const start = Math.max(0, end - 1000);
+      const w = cm.getMessageWindow(start, end - start).messages;
+      for (let i = w.length - 1; i >= 0; i--) {
+        if (w[i]!.sequence <= seqMark) return { messages: out, complete: true };
+        if (relevant(w[i]!)) out.push(w[i]!);
+        if (++looked >= APPENDED_SCAN_CAP) return { messages: out, complete: false };
+      }
+      end = start;
+    }
+    return { messages: out, complete: true };
+  }
+
+  /**
+   * Validate a filtered-extract resume position against the window as it is
+   * NOW. `afterId` names the message the previous call saw at position
+   * `windowOffset - 1`. If it is still there, resume as asked. If the window
+   * moved (a removal or an insertion before that point since the previous
+   * call), look for it within RELOCATE_RADIUS positions either side and
+   * resume just past it, reporting the shift. If it can't be found — it was
+   * itself removed, or the window moved further than that — fail loudly:
+   * guessing is how a message gets silently skipped.
+   */
+  private relocateWindowOffset(
+    windowOffset: number,
+    afterId: string | null | undefined,
+    q: { fromMs?: number; toMs?: number; channelId?: string },
+  ): { windowOffset: number; shift: number } {
+    if (windowOffset === 0) {
+      if (afterId != null) throw new Error('"afterId" only applies together with a windowOffset > 0.');
+      return { windowOffset, shift: 0 };
+    }
+    if (afterId == null) {
+      throw new Error(
+        '"windowOffset" needs the "afterId" from the same `resume` object — without it a message added or removed ' +
+          'since the previous call would be silently skipped. Pass the whole `resume` object back.',
+      );
+    }
+    const cm = this.cm as ContextManager;
+    const at = cm.queryMessagesByTimeAndChannel({ ...q, limit: 1, offset: windowOffset - 1 }).messages[0];
+    if (at && String(at.id) === afterId) return { windowOffset, shift: 0 };
+    const lo = Math.max(0, windowOffset - 1 - RELOCATE_RADIUS);
+    const around = cm.queryMessagesByTimeAndChannel({ ...q, limit: 2 * RELOCATE_RADIUS + 1, offset: lo }).messages;
+    const i = around.findIndex((m) => String(m.id) === afterId);
+    if (i === -1) {
+      throw new Error(
+        `The window changed since the previous call: message ${afterId}, where that scan stopped, is no longer ` +
+          `within ${RELOCATE_RADIUS} positions of windowOffset ${windowOffset} (it may have been deleted). ` +
+          'Restart the scan without windowOffset/afterId, or narrow it with from/to.',
+      );
+    }
+    const relocated = lo + i + 1;
+    return { windowOffset: relocated, shift: relocated - windowOffset };
+  }
+
+  /**
+   * The `n` messages of a time/channel range nearest one of its edges, in
+   * TIMESTAMP order walking away from that edge (newest-first for
+   * side:"newest", oldest-first for side:"oldest"), plus whether the range
+   * holds more than `n`.
+   *
+   * Why not just `queryMessagesByTimeAndChannel` + offset: (a) a time-only
+   * query's `matchedCount` is the returned PAGE size, not a total (see
+   * context-manager MessageStore.queryByTime), so it can't locate a tail;
+   * (b) channel-scoped results come back in APPEND (ordinal) order, and
+   * Discord catch-up appends old-timestamped messages late — an ordinal
+   * tail is not the timestamp tail.
+   *
+   * No channel: chronicle's timestamp index answers directly (`reverse`
+   * for the newest edge). With a channel: channel queries report an exact
+   * matchedCount, so grow a time window out from the edge (×4 per step)
+   * until it holds ≥ n channel messages or covers the whole range. If that
+   * window holds more than `fetchCap` (a density jump across one step, or a
+   * burst), bisect its far bound between the last step that held < n and
+   * this one — counts are exact, so it lands on a window of [n, fetchCap].
+   * Only when a single millisecond holds the overflow does bisection bottom
+   * out; then the window is everything strictly nearer the edge plus that
+   * millisecond's nearest messages by sequence, which within one millisecond
+   * IS the (timestamp, sequence) order — still exact. The newest side is
+   * left open when `toMs` is (clock-skewed future stamps stay visible).
+   */
+  private edgeWindow(opts: {
+    fromMs?: number;
+    toMs?: number;
+    channelId?: string;
+    n: number;
+    side: 'newest' | 'oldest';
+  }): { messages: StoredMessage[]; more: boolean } {
+    const cm = this.cm as ContextManager;
+    const { fromMs, toMs, channelId, n, side } = opts;
+    const newest = side === 'newest';
+    const cmp = (a: StoredMessage, b: StoredMessage) =>
+      a.timestamp.getTime() - b.timestamp.getTime() || a.sequence - b.sequence;
+    const dirSort = (ms: StoredMessage[]) => ms.sort(newest ? (a, b) => cmp(b, a) : cmp);
+
+    if (channelId === undefined) {
+      const r = cm.queryMessagesByTime({ fromMs, toMs, limit: n + 1, reverse: newest });
+      return { messages: r.messages.slice(0, n), more: r.messages.length > n };
+    }
+
+    const count = (f?: number, t?: number) =>
+      cm.queryMessagesByTimeAndChannel({ fromMs: f, toMs: t, channelId, limit: 0 }).matchedCount;
+    const fetch = (f: number | undefined, t: number | undefined, limit: number, offset = 0) =>
+      limit <= 0 ? [] : cm.queryMessagesByTimeAndChannel({ fromMs: f, toMs: t, channelId, limit, offset }).messages;
+    const total = count(fromMs, toMs);
+    if (n === 0) return { messages: [], more: total > 0 };
+    if (total <= n) return { messages: dirSort(fetch(fromMs, toMs, total)), more: false };
+
+    // The window is parameterised by its FAR bound `e`: [e, toMs] for the
+    // newest side, [fromMs, e] for the oldest; its count is monotone in e.
+    const win = (e: number): [number | undefined, number | undefined] => (newest ? [e, toMs] : [fromMs, e]);
+    const cnt = (e: number) => count(...win(e));
+    const lo = fromMs ?? this.earliestMessageMs(toMs) ?? 0;
+    const hi = toMs ?? Date.now(); // growth anchor only — never a bound
+    // `outside`: a far bound whose window holds < n (initially empty).
+    // `inside`: one whose window holds ≥ n (initially the whole range).
+    let outside: number | null = null;
+    let inside = newest ? lo : (toMs ?? MAX_DATE_MS);
+    let inCount = total;
+    for (let width = 10 * 60_000; ; width *= 4) {
+      const e = newest ? hi - width : lo + width;
+      if (newest ? e <= lo : e >= hi) break; // covered: keep the whole range
+      const c = cnt(e);
+      if (c >= n) {
+        inside = e;
+        inCount = c;
+        break;
+      }
+      outside = e;
+    }
+    const fetchCap = Math.max(4 * n, n + 1000);
+    if (inCount <= fetchCap) {
+      return { messages: dirSort(fetch(...win(inside), inCount)).slice(0, n), more: true };
+    }
+    // Overshoot: bisect the far bound. The empty side starts one past the
+    // range's near end (newest: past toMs / any date; oldest: before lo).
+    const emptyOut = newest ? (toMs ?? MAX_DATE_MS) + 1 : lo - 1;
+    let out = outside ?? emptyOut;
+    while (Math.abs(inside - out) > 1) {
+      const mid = Math.floor((inside + out) / 2);
+      const c = cnt(mid);
+      if (c < n) {
+        out = mid;
+      } else {
+        inside = mid;
+        inCount = c;
+        if (c <= fetchCap) {
+          return { messages: dirSort(fetch(...win(mid), c)).slice(0, n), more: true };
+        }
+      }
+    }
+    // Millisecond `inside` alone carries the overflow. Everything nearer the
+    // edge (the `out` window, < n messages) plus the nearest-by-sequence
+    // messages of that millisecond (channel pages are append = sequence
+    // ordered, which is the tie order within one millisecond).
+    const near = out === emptyOut ? [] : fetch(...win(out), cnt(out));
+    const need = n - near.length;
+    const ties = count(inside, inside);
+    const edgeMs = fetch(inside, inside, need, newest ? Math.max(0, ties - need) : 0);
+    return { messages: dirSort([...near, ...edgeMs]).slice(0, n), more: true };
+  }
+
   async start(ctx: ModuleContext): Promise<void> {
     this.ctx = ctx;
+    this.wireIndexer(ctx);
+    this.startSyncTimer();
+  }
+
+  /** Pending edits/removals survive a restart through module state. Called from whichever of start()/bind() runs second. */
+  private wireIndexer(ctx: ModuleContext): void {
+    if (!this.indexer) return;
+    this.indexer.restorePending(ctx.getState<{ semanticPending?: PendingChanges }>()?.semanticPending);
+    this.indexer.onPendingChange = (p) => {
+      const prev = this.ctx?.getState<Record<string, unknown>>() ?? {};
+      this.ctx?.setState({ ...prev, semanticPending: p });
+    };
+    this.indexer.attach();
   }
 
   async stop(): Promise<void> {
     this.ctx = null;
+    if (this.syncTimer) { clearInterval(this.syncTimer); this.syncTimer = null; }
+    if (this.firstSyncTimer) { clearTimeout(this.firstSyncTimer); this.firstSyncTimer = null; }
+    if (this.indexer) this.indexer.onPendingChange = null;
+    this.indexer?.dispose();
+  }
+
+  /**
+   * Background sync into the semantic index: every `syncIntervalMs` (default
+   * 60 s) push up to `maxSyncPerTick` new items. Idempotent to call — starts
+   * once we have both a context-manager (bind) and a config; `unref`'d so it
+   * never keeps a shutting-down process alive. A first tick runs after 5 s so
+   * a fresh store starts backfilling immediately rather than a minute later.
+   */
+  private startSyncTimer(): void {
+    if (this.syncTimer || !this.indexer || !this.semanticCfg) return;
+    const interval = this.semanticCfg.syncIntervalMs ?? 60_000;
+    if (interval <= 0) return;
+    const perTick = this.semanticCfg.maxSyncPerTick ?? 1024;
+    const tick = (): void => { void this.indexer?.catchUp(perTick); };
+    this.firstSyncTimer = setTimeout(() => { this.firstSyncTimer = null; tick(); }, 5_000);
+    this.firstSyncTimer.unref?.();
+    this.syncTimer = setInterval(tick, interval); this.syncTimer.unref?.();
+  }
+
+  /** Exposed for hosts/tests: one sync pass now. */
+  syncSemanticIndex(maxItems = 1024): Promise<SyncReport> | null {
+    return this.indexer ? this.indexer.catchUp(maxItems) : null;
   }
 
   getTools(): ToolDefinition[] {
@@ -291,15 +656,33 @@ export class HistoryModule implements Module {
           'Fetch raw, uncompressed messages for a time range and/or channel, paginated oldest-first. ' +
           'Use after `stats` to pull the actual content. format:"text" flattens each message to a short ' +
           'readable string (tool_use/tool_result/thinking/images rendered as bracketed labels); ' +
-          'format:"raw" returns the content blocks unmodified.',
+          'format:"raw" returns the content blocks unmodified. ' +
+          'Two extra modes: (1) aroundId — pass a message id (e.g. from `search`) to get the conversation ' +
+          'around it: `before` messages before it, the message itself (anchor:true), and `after` messages ' +
+          'after it, in the anchor\'s own channel unless channelId/allChannels says otherwise; from/to/offset/limit ' +
+          'do not apply in this mode (at most before+after+1 messages). (2) author/excludeAuthor — keep only (or drop) messages by these ' +
+          'authors; this is filtered in-process over at most maxScan messages of the window, so a response ' +
+          'may report truncated:true with a `resume` object ({windowOffset, offset, afterId}) — repeat the call with ' +
+          'those fields added to continue exactly where it stopped. If messages were added or removed in the window ' +
+          'meanwhile, the resume re-anchors on afterId and says so (windowChanged), or fails loudly when it can\'t.',
         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: 'Restrict to one channel. Accepts a channel label (e.g. "#general") or the raw internal channel id.' },
+            author: AUTHOR_SCHEMA,
+            excludeAuthor: EXCLUDE_AUTHOR_SCHEMA,
+            aroundId: { type: 'string', description: 'Message id to center on (as returned by search/extract; a "msg:<id>" hit id works too). Returns the surrounding conversation instead of a range.' },
+            before: { type: 'number', description: `With aroundId: messages to include before the anchor (default ${AROUND_DEFAULT}, cap ${AROUND_MAX}).` },
+            after: { type: 'number', description: `With aroundId: messages to include after the anchor (default ${AROUND_DEFAULT}, cap ${AROUND_MAX}).` },
+            allChannels: { type: 'boolean', description: 'With aroundId: interleave every channel around the anchor\'s time instead of staying in its channel (default false).' },
             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.` },
+            maxScan: { type: 'number', description: `With author/excludeAuthor: max window messages to examine (default ${EXTRACT_FILTER_DEFAULT_MAX_SCAN}, hard cap ${EXTRACT_FILTER_MAX_MAX_SCAN}).` },
+            windowOffset: { type: 'number', description: 'With author/excludeAuthor: resume a truncated scan at this position of the window — copy it from the previous response\'s `resume`.' },
+            seqMark: { type: 'number', description: 'With windowOffset and no channelId: copy it from `resume`. Lets a resume find messages added behind it since the previous call.' },
+            afterId: { type: 'string', description: 'With windowOffset: id of the last message the previous call scanned — copy it from `resume`. Lets a resume notice messages added or removed since, instead of silently skipping one.' },
             format: { type: 'string', enum: ['text', 'raw'], description: 'Content rendering (default "text").' },
           },
         },
@@ -311,7 +694,14 @@ export class HistoryModule implements Module {
           'range/channel window. Narrows candidates via the same query as `extract` before matching, up ' +
           'to maxScan candidates — if the narrowed window is larger than maxScan, the response reports ' +
           'truncated:true up front rather than silently missing later matches; narrow the filter or raise ' +
-          'maxScan and retry. regex:true matching runs under a wall-clock deadline and is cleanly failed ' +
+          'maxScan and retry. When the scan stops early (truncated, or `limit` matches reached) the response ' +
+          'carries a `resume` object ({from|to, skipSequences}): repeat the call with its fields to continue ' +
+          '(scannedThrough is the same instant, for reading). ' +
+          'order:"newest" scans the most recent maxScan messages of the window first — usually what you want ' +
+          'for "when did this last come up". author/excludeAuthor narrow by who wrote the message; ' +
+          'wholeWord:true stops "mission" from matching inside "uncommissioned". Each match carries an `id` ' +
+          'you can hand to extract({aroundId}) to read the conversation around it. ' +
+          'regex:true matching runs under a wall-clock deadline and is cleanly failed ' +
           `(not silently empty) if a pattern is too slow — avoid nested-quantifier patterns like (a+)+.`,
         inputSchema: {
           type: 'object' as const,
@@ -319,11 +709,20 @@ export class HistoryModule implements Module {
             query: { type: 'string', description: 'Substring (or regex source, when regex:true) to search for.' },
             regex: { type: 'boolean', description: 'Treat query as a regular expression (default false).' },
             caseSensitive: { type: 'boolean', description: 'Case-sensitive match (default false).' },
+            wholeWord: { type: 'boolean', description: 'Substring mode only: match whole words, not inside longer words (default false). In regex mode use \\b yourself.' },
             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. Accepts a channel label (e.g. "#general") or the raw internal channel id.' },
+            author: AUTHOR_SCHEMA,
+            excludeAuthor: EXCLUDE_AUTHOR_SCHEMA,
+            order: { type: 'string', enum: ['oldest', 'newest'], description: 'Scan and return oldest-first (default) or newest-first.' },
             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.` },
+            skipSequences: {
+              type: 'array',
+              items: { type: 'number' },
+              description: 'Continuation only: copy it from the previous response\'s `resume` together with its from/to. Marks the messages at exactly that instant that were already scanned.',
+            },
           },
           required: ['query'],
         },
@@ -373,9 +772,45 @@ export class HistoryModule implements Module {
           },
         },
       },
+      ...(this.semanticCfg ? [this.semanticSearchTool()] : []),
     ];
   }
 
+  private semanticSearchTool(): ToolDefinition {
+    return {
+      name: 'semantic_search',
+      description:
+        'Search your own history by MEANING, not exact words: an embedding index over your raw messages ' +
+        '(text plus your own think/journal/skip_reply notes) and every compression summary. Use it when you ' +
+        'remember roughly what something was about but not the words — "the night the fluid sim was read ' +
+        'back to me as art" — then narrow with `from`/`to`/`channelId` and drill into the exact span with ' +
+        '`extract` or `overview` (for a message hit, `extract({ aroundId: messageId })` opens the conversation ' +
+        'around it — use the raw `messageId` field, not the `msg:` id). Results are ranked by cosine similarity (score ~0.6+ is a strong match, ' +
+        '~0.3 is thematic, below ~0.2 is noise); each hit carries its id (`msg:<id>` or `sum:<id>`), ' +
+        'timestamp, channel, kind/level and a snippet. The index catches up with recent messages before ' +
+        'searching (bounded, so a huge backlog is reported as `index.behind` rather than blocking; if a ' +
+        'background sync is already running, the search waits for that run to finish instead). ' +
+        'Purely a read: nothing is written to your history. Hits are checked against your current branch ' +
+        'before they come back: a message you undid or a summary from a branch you left is dropped and ' +
+        'counted in index.droppedOffBranch; a message edited down to nothing searchable is dropped and ' +
+        'counted in index.droppedStale. Message snippets always show the current text of the message.',
+      inputSchema: {
+        type: 'object' as const,
+        properties: {
+          query: { type: 'string', description: 'What you are looking for, in natural language. A sentence works better than keywords.' },
+          limit: { type: 'number', description: `Max hits (default ${SEMANTIC_DEFAULT_LIMIT}, cap ${SEMANTIC_MAX_LIMIT}).` },
+          from: { type: 'string', description: 'ISO 8601 inclusive lower bound on the message timestamp / summary span start. Omit for open-ended.' },
+          to: { type: 'string', description: 'ISO 8601 inclusive upper bound. Omit for open-ended.' },
+          channelId: { type: 'string', description: 'Only raw messages from this channel (label like "#general" or the raw internal id). Summaries are not per-channel and are excluded when this is set; combining it with kinds="summaries" or level is an error.' },
+          kinds: { type: 'string', enum: ['messages', 'summaries', 'both'], description: 'What to search: raw messages, compression summaries, or both (default).' },
+          level: { type: 'number', description: 'Only summaries of this exact level (implies kinds=summaries).' },
+          minScore: { type: 'number', description: 'Drop hits below this cosine score (0..1). Default none.' },
+        },
+        required: ['query'],
+      },
+    };
+  }
+
   async handleToolCall(call: ToolCall): Promise<ToolResult> {
     try {
       if (!this.cm) {
@@ -390,6 +825,8 @@ export class HistoryModule implements Module {
           return await this.handleSearch((call.input ?? {}) as SearchInput);
         case 'overview':
           return this.handleOverview((call.input ?? {}) as OverviewInput);
+        case 'semantic_search':
+          return await this.handleSemanticSearch((call.input ?? {}) as SemanticSearchInput);
         default:
           return { success: false, isError: true, error: `Unknown tool: ${call.name}` };
       }
@@ -459,28 +896,320 @@ export class HistoryModule implements Module {
   // ==========================================================================
 
   private handleExtract(input: ExtractInput): ToolResult {
+    if (input.aroundId !== undefined) return this.handleExtractAround(input);
+    if (input.before !== undefined || input.after !== undefined || input.allChannels !== undefined) {
+      throw new Error('"before"/"after"/"allChannels" only apply together with "aroundId".');
+    }
     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');
     const offset = clampCount(input.offset, 0, NATIVE_OFFSET_MAX, 'offset');
     const format = input.format ?? 'text';
+    const authorFilter = buildAuthorFilter(input.author, input.excludeAuthor);
 
     const cm = this.cm as ContextManager;
+    if (!authorFilter && (input.windowOffset !== undefined || input.afterId !== undefined || input.seqMark !== undefined)) {
+      throw new Error('"windowOffset"/"afterId" only apply together with author/excludeAuthor (they resume a filtered scan). Use offset.');
+    }
+
+    if (authorFilter) {
+      // No native author index: page through the time/channel window and
+      // filter here. offset/limit apply to the FILTERED sequence. Stop as
+      // soon as the requested page is full; otherwise scan to maxScan. Only
+      // an exhausted window yields an exact matchedCount — anything else is
+      // reported as truncated with a resume point, never as a total.
+      //
+      // Resume is by WINDOW POSITION (`windowOffset`), never by timestamp: a
+      // channel-scoped window pages in append order, and Discord catch-up
+      // appends old-timestamped messages late, so "continue from the last
+      // timestamp seen" would skip them.
+      const maxScan = clampCount(input.maxScan, EXTRACT_FILTER_DEFAULT_MAX_SCAN, EXTRACT_FILTER_MAX_MAX_SCAN, 'maxScan');
+      if (maxScan === 0) throw new Error('"maxScan" must be at least 1 for an author-filtered extract.');
+      const requestedOffset = clampCount(input.windowOffset, 0, NATIVE_OFFSET_MAX, 'windowOffset');
+      // A position is only meaningful against the window it was taken in:
+      // a removal before it (every discord:delete, host hide, /undo) shifts
+      // later positions left, and a message inserted before it (a
+      // time-ordered window with backfill) shifts them right. Either would
+      // silently skip or repeat a message. afterId pins the position to the
+      // message that was there; relocate it if the window moved.
+      const { windowOffset, shift } = this.relocateWindowOffset(
+        requestedOffset,
+        input.afterId,
+        { fromMs, toMs, channelId },
+      );
+      // A time-ordered window (no channelId) can also take an older-stamped
+      // insertion BEFORE the cursor; paired with a removal there, positions
+      // balance out (shift 0) and afterId alone can't see it. Appends carry
+      // the highest sequences, so everything appended since the previous
+      // call is the store's append tail above its seqMark: check those
+      // directly. (A channel window pages in append order, so an append
+      // always lands after the cursor and is simply scanned.)
+      const seqMarkNow = channelId === undefined ? this.storeSeqMark() : undefined;
+      let missed: StoredMessage[] = [];
+      let unverified = false;
+      if (channelId === undefined && windowOffset > 0) {
+        if (typeof input.seqMark !== 'number') {
+          throw new Error(
+            '"windowOffset" without channelId needs the "seqMark" from the same `resume` object. Pass the whole `resume` object back.',
+          );
+        }
+        const cursor = cm.queryMessagesByTimeAndChannel({ fromMs, toMs, limit: 1, offset: windowOffset - 1 }).messages[0];
+        if (cursor) {
+          const ct = cursor.timestamp.getTime();
+          const r = this.appendedSince(input.seqMark, (m) => {
+            const ts = m.timestamp.getTime();
+            if ((fromMs !== undefined && ts < fromMs) || (toMs !== undefined && ts > toMs)) return false;
+            return ts < ct || (ts === ct && m.sequence < cursor.sequence);
+          });
+          missed = r.messages;
+          unverified = !r.complete;
+        }
+      }
+      const page: StoredMessage[] = [];
+      let kept = 0;
+      let scanned = 0;
+      let lastScanned: StoredMessage | undefined;
+      // Window position just past the last message put on the page, and that message.
+      let afterPage = windowOffset;
+      let lastOnPage: StoredMessage | undefined;
+      let exhausted = false;
+      let pageFull = false;
+      outer: for (;;) {
+        const want = Math.min(FILTER_SCAN_PAGE, maxScan - scanned);
+        if (want <= 0) break;
+        const chunk = cm.queryMessagesByTimeAndChannel({
+          fromMs,
+          toMs,
+          channelId,
+          limit: want,
+          offset: Math.min(windowOffset + scanned, NATIVE_OFFSET_MAX),
+        }).messages;
+        for (const m of chunk) {
+          scanned++;
+          lastScanned = m;
+          if (!authorFilter(m)) continue;
+          if (kept >= offset && page.length < limit) {
+            page.push(m);
+            afterPage = windowOffset + scanned;
+            lastOnPage = m;
+          }
+          kept++;
+          if (limit > 0 && page.length >= limit && kept > offset + limit) {
+            // One filtered match beyond the page proves there is more;
+            // no need to keep scanning.
+            pageFull = true;
+            break outer;
+          }
+        }
+        if (chunk.length < want) {
+          exhausted = true;
+          break;
+        }
+      }
+      if (!exhausted && !pageFull && scanned >= maxScan) {
+        // Probe one past maxScan: a window of exactly maxScan is complete.
+        const next = cm.queryMessagesByTimeAndChannel({
+          fromMs,
+          toMs,
+          channelId,
+          limit: 1,
+          offset: Math.min(windowOffset + scanned, NATIVE_OFFSET_MAX),
+        }).messages;
+        if (next.length === 0) exhausted = true;
+      }
+      return {
+        success: true,
+        data: {
+          // A resumed scan (windowOffset > 0) only saw the window from that
+          // position on, so its count is named for that — never a total. A
+          // page-full stop's lookahead match lies past the resume point and
+          // is left out, so counts add up across a chain of resumes.
+          ...(() => {
+            const n = pageFull ? kept - 1 : kept;
+            const base = windowOffset > 0 ? 'matchedSinceWindowOffset' : 'matchedCount';
+            return { [exhausted ? base : `${base}AtLeast`]: n };
+          })(),
+          returned: page.length,
+          scanned,
+          truncated: !exhausted,
+          ...(shift !== 0 || missed.length > 0 || unverified
+            ? {
+                windowChanged: {
+                  shift,
+                  ...(unverified
+                    ? {
+                        unverified: true,
+                        unverifiedNote:
+                          `More than ${APPENDED_SCAN_CAP} messages were appended since the previous call; only the newest ` +
+                          'were checked, so messages may have been added behind the resume point unseen. Restart without ' +
+                          'windowOffset, or narrow with from/to/channelId, if that matters.',
+                      }
+                    : {}),
+                  ...(channelId === undefined
+                    ? {
+                        addedBefore: missed.length,
+                        // the ones this filter would have kept — fetch them with extract({aroundId})
+                        missedIds: missed.filter(authorFilter).map((m) => String(m.id)),
+                      }
+                    : {}),
+                  note:
+                    missed.length > 0 || shift > 0
+                      ? `${missed.length || shift} message(s) were added to the window before the resume point since the previous call; this scan chain did not see them` +
+                        (channelId === undefined ? ' (matching ones listed in missedIds).' : '.')
+                      : shift < 0
+                        ? `${-shift} message(s) before the resume point were removed since the previous call; the resume was re-anchored, nothing skipped.`
+                        : 'No change found behind the resume point, but the check was incomplete (see unverifiedNote).',
+                },
+              }
+            : {}),
+          ...(!exhausted
+            ? (() => {
+                // pageFull: resume just past the last returned message, no
+                // skip. maxScan: resume past everything scanned, still owing
+                // whatever part of `offset` was not yet consumed.
+                // afterId = the message at position windowOffset-1 (see
+                // relocateWindowOffset). When nothing was scanned (no
+                // chunk came back), carry the incoming anchor forward.
+                const mark = seqMarkNow !== undefined ? { seqMark: seqMarkNow } : {};
+                const resume = pageFull
+                  ? { windowOffset: afterPage, offset: 0, afterId: idOrNull(lastOnPage) ?? input.afterId ?? null, ...mark }
+                  : {
+                      windowOffset: windowOffset + scanned,
+                      offset: Math.max(0, offset - kept),
+                      afterId: idOrNull(lastScanned) ?? input.afterId ?? null,
+                      ...mark,
+                    };
+                return {
+                  resume,
+                  hint:
+                    (pageFull
+                      ? 'More matching messages exist. '
+                      : `Stopped after scanning ${scanned} messages of the window without reaching its end. `) +
+                    `Continue by repeating this call with the same from/to/channelId/author plus ` +
+                    `the fields of \`resume\` (windowOffset:${resume.windowOffset}, offset:${resume.offset}, afterId).`,
+                };
+              })()
+            : {}),
+          messages: page.map((msg) => projectMessage(msg, format)),
+        },
+      };
+    }
+
+    // One extra row answers "is there another page" in every case. The
+    // native matchedCount is a true total only for channel-scoped queries;
+    // for time-only/unfiltered ones it is just the page size (see
+    // edgeWindow), so it is reported only where it means what it says.
     const result = cm.queryMessagesByTimeAndChannel({
       fromMs,
       toMs,
       channelId,
-      limit,
+      limit: limit + 1,
       offset,
     });
+    const page = result.messages.slice(0, limit);
+
+    return {
+      success: true,
+      data: {
+        ...(channelId !== undefined ? { matchedCount: result.matchedCount } : {}),
+        returned: page.length,
+        hasMore: result.messages.length > limit,
+        messages: page.map((msg) => projectMessage(msg, format)),
+      },
+    };
+  }
+
+  /**
+   * `extract({aroundId})` — the conversation around one message, like
+   * Discord's fetch_around. Neighbours are by (timestamp, sequence): first
+   * the anchor's own millisecond in sequence order, then, for whatever a
+   * side still needs, the nearest messages strictly before/after it (both
+   * via edgeWindow, which is exact by timestamp).
+   */
+  private handleExtractAround(input: ExtractInput): ToolResult {
+    if (
+      input.from !== undefined ||
+      input.to !== undefined ||
+      input.offset !== undefined ||
+      input.windowOffset !== undefined ||
+      input.limit !== undefined
+    ) {
+      throw new Error(
+        '"aroundId" cannot be combined with from/to/offset/windowOffset/limit — it picks its own window; size it with before/after.',
+      );
+    }
+    if (input.author !== undefined || input.excludeAuthor !== undefined) {
+      throw new Error('"aroundId" returns the whole conversation around a message; author filters do not apply. Use search/extract with author instead.');
+    }
+    if (input.allChannels && input.channelId !== undefined) {
+      throw new Error('Pass either "channelId" or "allChannels", not both.');
+    }
+    const before = clampCount(input.before, AROUND_DEFAULT, AROUND_MAX, 'before');
+    const after = clampCount(input.after, AROUND_DEFAULT, AROUND_MAX, 'after');
+    const format = input.format ?? 'text';
+    const cm = this.cm as ContextManager;
 
+    // semantic_search (#173) hands out `msg:<id>` / `sum:<id>`; accept the
+    // message form as-is, and say plainly what a summary id is.
+    const rawId = String(input.aroundId);
+    if (/^sum:/.test(rawId)) {
+      throw new Error(
+        `${rawId} is a compression summary, not a message — use overview for summaries, or aroundId with a msg: hit.`,
+      );
+    }
+    const anchor = cm.getMessage(rawId.replace(/^msg:/, ''));
+    if (!anchor) {
+      throw new Error(`No message with id ${JSON.stringify(input.aroundId)} in this history.`);
+    }
+    const anchorId = String(anchor.id);
+    const anchorChannel = getChannelId(anchor);
+    const channelId = input.allChannels ? undefined : (this.resolveChannel(input.channelId) ?? anchorChannel);
+    const t = anchor.timestamp.getTime();
+
+    // The anchor's own millisecond first, whole and in sequence order —
+    // that is the (timestamp, sequence) order the neighbours are defined
+    // by, and it may hold many messages (a backfill burst). Then only if a
+    // side still needs more, the nearest messages strictly before / after
+    // that millisecond (edgeWindow is exact by timestamp).
+    let ties: StoredMessage[];
+    if (channelId !== undefined) {
+      const n = cm.queryMessagesByTimeAndChannel({ fromMs: t, toMs: t, channelId, limit: 0 }).matchedCount;
+      if (n > AROUND_TIE_CAP) throw tieCapError(anchorId, n);
+      ties = cm.queryMessagesByTimeAndChannel({ fromMs: t, toMs: t, channelId, limit: n }).messages;
+    } else {
+      ties = cm.queryMessagesByTime({ fromMs: t, toMs: t, limit: AROUND_TIE_CAP + 1 }).messages;
+      if (ties.length > AROUND_TIE_CAP) throw tieCapError(anchorId, ties.length);
+    }
+    ties = [...ties].sort((x, y) => x.sequence - y.sequence);
+    const idx = ties.findIndex((m) => String(m.id) === anchorId);
+    if (idx === -1) {
+      // The anchor is in the store and every message of its millisecond in
+      // `channelId` was fetched, so only an explicit channelId excludes it.
+      throw new Error(
+        `Message ${anchorId} is not in channel ${JSON.stringify(input.channelId)}` +
+          (anchorChannel ? ` (it is in ${anchorChannel}).` : '.') +
+          ' Omit channelId to use the anchor\'s own channel.',
+      );
+    }
+    const tiesBefore = ties.slice(Math.max(0, idx - before), idx);
+    const tiesAfter = ties.slice(idx + 1, idx + 1 + after);
+    const needBefore = before - tiesBefore.length;
+    const needAfter = after - tiesAfter.length;
+    const earlier =
+      needBefore > 0 ? this.edgeWindow({ toMs: t - 1, channelId, n: needBefore, side: 'newest' }).messages.reverse() : [];
+    const later = needAfter > 0 ? this.edgeWindow({ fromMs: t + 1, channelId, n: needAfter, side: 'oldest' }).messages : [];
+    const window = [...earlier, ...tiesBefore, ties[idx]!, ...tiesAfter, ...later];
     return {
       success: true,
       data: {
-        matchedCount: result.matchedCount,
-        returned: result.messages.length,
-        messages: result.messages.map((msg) => projectMessage(msg, format)),
+        anchorId,
+        channelId: channelId ?? null,
+        returned: window.length,
+        messages: window.map((m) => ({
+          ...projectMessage(m, format),
+          ...(String(m.id) === anchorId ? { anchor: true } : {}),
+        })),
       },
     };
   }
@@ -500,6 +1229,14 @@ export class HistoryModule implements Module {
     const maxScan = clampCount(input.maxScan, SEARCH_DEFAULT_MAX_SCAN, SEARCH_MAX_MAX_SCAN, 'maxScan');
     const caseSensitive = input.caseSensitive ?? false;
     const flags = caseSensitive ? '' : 'i';
+    const order = input.order ?? 'oldest';
+    if (order !== 'oldest' && order !== 'newest') {
+      throw new Error(`"order" must be "oldest" or "newest", got ${JSON.stringify(input.order)}.`);
+    }
+    if (input.wholeWord && input.regex) {
+      throw new Error('"wholeWord" applies to substring search only; in regex mode write \\b around the pattern instead.');
+    }
+    const authorFilter = buildAuthorFilter(input.author, input.excludeAuthor);
 
     // Validate regex SYNTAX up front — an invalid pattern is a clean tool
     // error, not a crash mid-scan. This does NOT bound match TIME (a
@@ -516,19 +1253,92 @@ export class HistoryModule implements Module {
     const needle = caseSensitive ? input.query : input.query.toLowerCase();
 
     const cm = this.cm as ContextManager;
-    // Fetch one more than maxScan so an oversized candidate window is
-    // detected up front (before any matching is attempted), rather than
+    // The candidate window is the oldest (order:"oldest") or newest
+    // (order:"newest", via edgeWindow — see there for why not an offset
+    // tail) maxScan messages of the time/channel range. Oversize is
+    // detected up front rather than
     // silently scanning maxScan candidates and returning as if that were the
     // whole window. See the tool description's `truncated` contract.
-    const probe = cm.queryMessagesByTimeAndChannel({
-      fromMs,
-      toMs,
-      channelId,
-      limit: maxScan + 1,
-      offset: 0,
-    });
-    const truncated = probe.messages.length > maxScan;
-    const candidates = truncated ? probe.messages.slice(0, maxScan) : probe.messages;
+    if (maxScan === 0) throw new Error('"maxScan" must be at least 1 — a zero-message scan can never make progress.');
+    // Continuation: `skipSequences` names what the previous call already
+    // scanned at exactly the resume bound's millisecond (the bound is
+    // inclusive). Identified by sequence range rather than a count, so a
+    // message removed at that millisecond, or appended there (a new
+    // message always gets the highest sequence), between calls neither
+    // shifts the skip onto an unscanned message nor hides the new one.
+    const skipRange = parseSkipSequences(input.skipSequences);
+    const edgeMs = order === 'oldest' ? fromMs : toMs;
+    if (skipRange && edgeMs === undefined) {
+      throw new Error(`"skipSequences" only applies together with "${order === 'oldest' ? 'from' : 'to'}" — pass the whole \`resume\` object back.`);
+    }
+    const isSkipped = (m: StoredMessage) =>
+      !!skipRange && m.timestamp.getTime() === edgeMs && m.sequence >= skipRange[0] && m.sequence <= skipRange[1];
+    let windowMessages: StoredMessage[];
+    let truncated: boolean;
+    {
+      // Over-fetch by the number of messages at the edge millisecond (the
+      // only ones that can be skipped), then drop the skipped ones.
+      const edgeTies = skipRange ? this.countAtMs(edgeMs!, channelId) : 0;
+      const w = this.edgeWindow({ fromMs, toMs, channelId, n: maxScan + edgeTies, side: order });
+      const pool = skipRange ? w.messages.filter((m) => !isSkipped(m)) : w.messages;
+      truncated = w.more || pool.length > maxScan;
+      windowMessages = pool.slice(0, maxScan);
+    }
+    const candidatePoolSize = windowMessages.length;
+    const candidates = authorFilter ? windowMessages.filter(authorFilter) : windowMessages;
+    const poolInfo = {
+      candidatePoolSize,
+      ...(authorFilter ? { afterAuthorFilter: candidates.length } : {}),
+      order,
+    };
+    // Where the scan stopped, when it stopped before the end of the window
+    // the caller asked about: either `limit` matches came first (the rest of
+    // the pool was never looked at) or the pool itself was truncated. The
+    // timestamp is the continuation point — from: (oldest) / to: (newest).
+    // Boundary is inclusive, so a message at exactly that instant may repeat.
+    const resumeInfo = (scanned: number): Record<string, unknown> => {
+      const stoppedEarly = scanned < candidates.length;
+      if (!stoppedEarly && !truncated) return {};
+      // Stopped at limit: the last candidate actually looked at. Scanned the
+      // whole (truncated) pool: the pool's own far edge — which may lie past
+      // the last author-filtered candidate.
+      const last = stoppedEarly ? candidates[scanned - 1] : windowMessages[windowMessages.length - 1];
+      if (!last) return {};
+      const at = last.timestamp.toISOString();
+      const bound = order === 'oldest' ? 'from' : 'to';
+      // The continuation bound is inclusive, so the next window starts with
+      // every message at exactly `at`. Hand back the sequence range already
+      // scanned there: this call's messages at `at` up to the stop, plus —
+      // when `at` is still the incoming bound — the range the previous
+      // call had already covered. Within one millisecond the pool is in
+      // sequence order, so every message at `at` whose sequence lies in the
+      // union was scanned; anything appended later sorts outside it.
+      const atMs = last.timestamp.getTime();
+      const stop = windowMessages.indexOf(last);
+      let lo = Infinity;
+      let hi = -Infinity;
+      for (let i = 0; i <= stop; i++) {
+        const m = windowMessages[i]!;
+        if (m.timestamp.getTime() !== atMs) continue;
+        lo = Math.min(lo, m.sequence);
+        hi = Math.max(hi, m.sequence);
+      }
+      if (skipRange && atMs === edgeMs) {
+        lo = Math.min(lo, skipRange[0]);
+        hi = Math.max(hi, skipRange[1]);
+      }
+      const resume = { [bound]: at, skipSequences: [lo, hi] as [number, number] };
+      return {
+        scannedThrough: at,
+        resume,
+        hint:
+          (stoppedEarly
+            ? 'Stopped at limit; more candidates remain. '
+            : `Only the ${order} ${candidatePoolSize} messages of this range were scanned (maxScan). `) +
+          `Continue by repeating the call with the fields of \`resume\` (${bound}:"${at}" and skipSequences), ` +
+          'or raise limit/maxScan, or narrow with channelId/author/dates.',
+      };
+    };
 
     if (input.regex) {
       // Regex matching against caller-supplied patterns is ReDoS-shaped: a
@@ -541,7 +1351,7 @@ export class HistoryModule implements Module {
       // on a deadline. See search-regex-worker.ts's header for the full
       // rationale.
       const { matches, scanned } = await this.searchWithRegexWorker(candidates, input.query, flags, limit);
-      return { success: true, data: { scanned, candidatePoolSize: candidates.length, truncated, matches } };
+      return { success: true, data: { scanned, ...poolInfo, truncated, ...resumeInfo(scanned), matches } };
     }
 
     // Plain substring search (String.prototype.indexOf) is inherently
@@ -559,12 +1369,13 @@ export class HistoryModule implements Module {
       if (matches.length >= limit) break;
       scanned++;
       const text = flattenContent(msg.content);
-      const hit = matchSubstring(text, needle, caseSensitive);
+      const hit = matchSubstring(text, needle, caseSensitive, input.wholeWord ?? false);
       if (!hit) continue;
       matches.push({
         id: String(msg.id),
         timestamp: msg.timestamp.toISOString(),
         participant: msg.participant,
+        author: authorName(msg),
         channelId: getChannelId(msg) ?? null,
         snippet: snippetAround(text, hit.index, hit.length),
       });
@@ -572,7 +1383,7 @@ export class HistoryModule implements Module {
 
     return {
       success: true,
-      data: { scanned, candidatePoolSize: candidates.length, truncated, matches },
+      data: { scanned, ...poolInfo, truncated, ...resumeInfo(scanned), matches },
     };
   }
 
@@ -632,6 +1443,7 @@ export class HistoryModule implements Module {
           id: String(msg.id),
           timestamp: msg.timestamp.toISOString(),
           participant: msg.participant,
+          author: authorName(msg),
           channelId: getChannelId(msg) ?? null,
           snippet: snippetAround(text, matchIndex, matchLength),
         };
@@ -649,6 +1461,129 @@ export class HistoryModule implements Module {
   // overview
   // ==========================================================================
 
+  private async handleSemanticSearch(input: SemanticSearchInput): Promise<ToolResult> {
+    if (!this.semanticCfg || !this.semanticClient) {
+      throw new Error('semantic_search is not configured for this resident (no embed-service in the recipe).');
+    }
+    if (typeof input.query !== 'string' || !input.query.trim()) throw new Error('query must be a non-empty string');
+    const limit = clampCount(input.limit, SEMANTIC_DEFAULT_LIMIT, SEMANTIC_MAX_LIMIT, 'limit');
+    if (limit < 1) throw new Error('limit must be at least 1');
+    const fromMs = parseIsoDate(input.from, 'from');
+    const toMs = parseIsoDate(input.to, 'to');
+    if (fromMs !== undefined && toMs !== undefined && fromMs > toMs) throw new Error('`from` must not be after `to`');
+    const channelId = this.resolveChannel(input.channelId);
+    // Summaries carry no channel, so a channel filter on a summaries-only
+    // search can only ever match nothing. Say so instead of returning [].
+    const wantsSummariesOnly = input.level !== undefined || input.kinds === 'summaries';
+    if (channelId && wantsSummariesOnly) {
+      throw new Error('channelId cannot be combined with kinds="summaries" or level: summaries are not per-channel. Drop channelId, or search kinds="messages".');
+    }
+    if (input.level !== undefined && input.kinds === 'messages') {
+      throw new Error('level applies to summaries only and cannot be combined with kinds="messages".');
+    }
+    let kinds: string[] | undefined;
+    if (wantsSummariesOnly) kinds = ['summary'];
+    else if (input.kinds === 'messages' || channelId) kinds = ['message'];
+    if (input.level !== undefined && (!Number.isInteger(input.level) || input.level < 0)) throw new Error('level must be a non-negative integer');
+    if (input.minScore !== undefined && (typeof input.minScore !== 'number' || input.minScore < -1 || input.minScore > 1)) {
+      throw new Error('minScore must be a number in -1..1');
+    }
+
+    // Bounded catch-up so the newest messages are searchable; never block on a backlog.
+    let sync: SyncReport | null = null;
+    if (this.indexer) {
+      try { sync = await this.indexer.catchUp(this.semanticCfg.maxSyncBeforeSearch ?? 256); } catch { /* reported via indexer.lastError */ }
+    }
+
+    const runSearch = (k: number) => this.semanticClient!.search({
+      query: input.query, k,
+      ts_from: fromMs === undefined ? undefined : fromMs / 1000,
+      ts_to: toMs === undefined ? undefined : toMs / 1000,
+      channel: channelId, kinds, level: input.level, min_score: input.minScore, snippet: SEMANTIC_SNIPPET_CHARS,
+    });
+    // The remote index is append-only and knows nothing about branches: a
+    // message removed from the agent's reach by /undo, /checkout, /restore or
+    // /newtopic keeps its id (a new message gets a fresh one) and stays
+    // indexed. Check every hit against the CURRENT branch before it goes back
+    // to the model — getMessage/getSummary rebuild on branch switch, so an
+    // undone message or a summary minted on another branch answers null.
+    // k is small, so this is at most `limit` local lookups.
+    // A message hit whose current text has nothing left to index (edited
+    // blank, delete not yet applied) is dropped too, so its stale snippet is
+    // never served. Dropped hits are replaced by over-fetching: when the
+    // top k held droppable entries, re-query with a larger k (service cap
+    // 200) so lower-ranked on-branch matches still fill `limit`.
+    const cm = this.cm as ContextManager;
+    const includePrivate = this.semanticCfg.includePrivateTools ?? true;
+    // A message hit's snippet is rebuilt from the CURRENT local text, never
+    // the remote copy: an edit not yet synced (or one the index never got)
+    // must not leak a passage the edit removed. Only the ranking can be stale.
+    const currentText = new Map<string, string>();
+    const keep = (h: { id: string }): 'ok' | 'offBranch' | 'stale' => {
+      const msgId = /^msg:(.+)$/.exec(h.id)?.[1];
+      const sumId = /^sum:(.+)$/.exec(h.id)?.[1];
+      if (msgId !== undefined) {
+        const m = cm.getMessage(msgId);
+        if (!m) return 'offBranch';
+        const text = messageIndexText(m, includePrivate).slice(0, this.semanticCfg!.maxChars ?? 32_000);
+        if (!text) return 'stale';
+        currentText.set(h.id, text);
+        return 'ok';
+      }
+      if (sumId !== undefined) return cm.getSummary(sumId) !== null ? 'ok' : 'offBranch';
+      return 'ok';
+    };
+    let k = limit;
+    let res = await runSearch(k);
+    let droppedOffBranch = 0;
+    let droppedStale = 0;
+    let onBranch: typeof res.hits = [];
+    for (;;) {
+      droppedOffBranch = 0; droppedStale = 0;
+      onBranch = res.hits.filter((h) => {
+        const v = keep(h);
+        if (v === 'offBranch') droppedOffBranch++;
+        else if (v === 'stale') droppedStale++;
+        return v === 'ok';
+      });
+      if (onBranch.length >= limit || res.hits.length < k || k >= SEMANTIC_MAX_FETCH) break;
+      k = Math.min(SEMANTIC_MAX_FETCH, k * 4);
+      res = await runSearch(k);
+    }
+    onBranch = onBranch.slice(0, limit);
+    const hits = onBranch.map((h) => ({
+      id: h.id,
+      /** Raw message id for a `msg:` hit (null for summaries) — pass it to extract({ aroundId }). */
+      messageId: h.id.startsWith('msg:') ? h.id.slice(4) : null,
+      kind: h.kind,
+      level: h.level,
+      score: h.score,
+      timestamp: h.ts === null ? null : new Date(h.ts * 1000).toISOString(),
+      channelId: h.channel,
+      participant: (h.meta as { participant?: unknown }).participant ?? null,
+      author: (h.meta as { author?: unknown }).author ?? null,
+      snippet: currentText.has(h.id) ? snippetOf(currentText.get(h.id)!) : (h.text ?? ''),
+      chars: currentText.has(h.id) ? currentText.get(h.id)!.length : h.chars,
+    }));
+    return {
+      success: true,
+      data: {
+        hits,
+        index: {
+          indexed: res.count_indexed,
+          behind: sync ? sync.more : this.indexer === null ? null : true,
+          syncedThisCall: sync ? sync.pushed : 0,
+          lastError: this.indexer?.lastError ?? null,
+          /** Hits the index returned for messages/summaries not on the current branch (undone, checked out past). */
+          droppedOffBranch,
+          /** Hits for messages whose current text has nothing indexable (edited blank; the index delete is pending). */
+          droppedStale,
+        },
+        timingMs: res.timing_ms,
+      },
+    };
+  }
+
   private handleOverview(input: OverviewInput): ToolResult {
     const channelId = this.resolveChannel(input.channelId);
     const fromMs = parseIsoDate(input.from, 'from');
@@ -1200,6 +2135,7 @@ function projectMessage(msg: StoredMessage, format: 'text' | 'raw'): Record<stri
     id: String(msg.id),
     timestamp: msg.timestamp.toISOString(),
     participant: msg.participant,
+    author: authorName(msg),
     channelId: getChannelId(msg) ?? null,
     content: format === 'raw' ? msg.content : flattenContent(msg.content),
   };
@@ -1252,15 +2188,144 @@ interface SearchMatch {
   id: string;
   timestamp: string;
   participant: string;
+  /** Display name from metadata.author (null when absent — e.g. the agent's own turns; see participant). */
+  author: string | null;
   channelId: string | null;
   snippet: string;
 }
 
-function matchSubstring(text: string, needle: string, caseSensitive: boolean): MatchHit | null {
+/** Letters, combining marks (NFD accents, Indic vowel signs), digits, underscore. */
+const WORD_CHAR_RE = /[\p{L}\p{M}\p{N}_]/u;
+
+function isWordChar(ch: string | undefined): boolean {
+  return ch !== undefined && WORD_CHAR_RE.test(ch);
+}
+
+/** The whole code point starting at `i` (astral letters are two UTF-16 units). */
+function codePointAt(s: string, i: number): string | undefined {
+  const cp = s.codePointAt(i);
+  return cp === undefined ? undefined : String.fromCodePoint(cp);
+}
+
+/** The whole code point ending just before `i`. */
+function codePointBefore(s: string, i: number): string | undefined {
+  if (i <= 0) return undefined;
+  const lo = s.charCodeAt(i - 1);
+  if (lo >= 0xdc00 && lo <= 0xdfff && i >= 2) {
+    const hi = s.charCodeAt(i - 2);
+    if (hi >= 0xd800 && hi <= 0xdbff) return s.slice(i - 2, i);
+  }
+  return s[i - 1];
+}
+
+/**
+ * First occurrence of `needle` in `text`. With `wholeWord`, an occurrence
+ * only counts when it isn't glued to a letter/digit/underscore on either
+ * side (Unicode-aware, so Cyrillic words work too) — "mission" no longer
+ * hits inside "uncommissioned". Word-ness is checked only on the sides
+ * where the needle itself starts/ends with a word character, so a needle
+ * like "#general" or "v2." still matches the way a person would expect.
+ */
+function matchSubstring(text: string, needle: string, caseSensitive: boolean, wholeWord = false): MatchHit | null {
   const haystack = caseSensitive ? text : text.toLowerCase();
-  const index = haystack.indexOf(needle);
-  if (index === -1) return null;
-  return { index, length: needle.length };
+  if (!wholeWord) {
+    const index = haystack.indexOf(needle);
+    return index === -1 ? null : { index, length: needle.length };
+  }
+  const checkLeft = isWordChar(codePointAt(needle, 0));
+  const checkRight = isWordChar(codePointBefore(needle, needle.length));
+  for (let from = 0; ; ) {
+    const index = haystack.indexOf(needle, from);
+    if (index === -1) return null;
+    const end = index + needle.length;
+    if ((!checkLeft || !isWordChar(codePointBefore(haystack, index))) && (!checkRight || !isWordChar(codePointAt(haystack, end)))) {
+      return { index, length: needle.length };
+    }
+    from = index + 1;
+  }
+}
+
+// ============================================================================
+// author filtering
+// ============================================================================
+
+/** metadata.author as written by MCPL channel ingestion ({id, name}). Every
+ *  incoming channel message is stored with participant "user" — the real
+ *  author lives only here. */
+function authorOf(msg: StoredMessage): { id?: string; name?: string } | undefined {
+  const a = (msg.metadata as { author?: unknown } | undefined)?.author;
+  if (!a || typeof a !== 'object') return undefined;
+  const { id, name } = a as { id?: unknown; name?: unknown };
+  return {
+    ...(typeof id === 'string' || typeof id === 'number' ? { id: String(id) } : {}),
+    ...(typeof name === 'string' ? { name } : {}),
+  };
+}
+
+function parseSkipSequences(v: unknown): [number, number] | null {
+  if (v === undefined || v === null) return null;
+  if (
+    !Array.isArray(v) ||
+    v.length !== 2 ||
+    !v.every((x) => typeof x === 'number' && Number.isInteger(x) && x >= 0) ||
+    v[0] > v[1]
+  ) {
+    throw new Error('"skipSequences" must be [lo, hi], two non-negative integers with lo <= hi — copy it from `resume`.');
+  }
+  return [v[0], v[1]];
+}
+
+function idOrNull(msg: StoredMessage | undefined): string | null {
+  return msg ? String(msg.id) : null;
+}
+
+function authorName(msg: StoredMessage): string | null {
+  return authorOf(msg)?.name ?? null;
+}
+
+/** Normalize one author spec: trim, case-fold, strip a leading "@", unwrap a
+ *  <@id>/<@!id> mention to its id. */
+function normalizeAuthorSpec(spec: string): string {
+  const s = spec.trim();
+  const mention = /^<@!?([^\s<>@]+)>$/.exec(s);
+  if (mention) return mention[1]!.toLowerCase();
+  return s.replace(/^@/, '').toLowerCase();
+}
+
+function toAuthorSet(spec: AuthorSpec | undefined, field: string): Set<string> | null {
+  if (spec === undefined) return null;
+  const list = Array.isArray(spec) ? spec : [spec];
+  if (list.some((s) => typeof s !== 'string')) {
+    throw new Error(`"${field}" must be a string or an array of strings.`);
+  }
+  const set = new Set(list.map(normalizeAuthorSpec).filter((s) => s.length > 0));
+  if (set.size === 0) throw new Error(`"${field}" must name at least one author.`);
+  return set;
+}
+
+/**
+ * Predicate for `author`/`excludeAuthor`, or null when neither is given.
+ * A message's identities are its metadata.author name and id plus its
+ * stored participant — the last is what identifies the agent's own turns
+ * (and anything else ingested without author metadata). Exact match after
+ * normalization, never substring: "ann" must not pull in "joanne".
+ */
+function buildAuthorFilter(include: AuthorSpec | undefined, exclude: AuthorSpec | undefined): ((m: StoredMessage) => boolean) | null {
+  const inc = toAuthorSet(include, 'author');
+  const exc = toAuthorSet(exclude, 'excludeAuthor');
+  if (!inc && !exc) return null;
+  return (m) => {
+    const a = authorOf(m);
+    // participant only for messages WITHOUT author metadata (the agent's own
+    // turns): every MCPL-ingested message has participant "user", which
+    // would otherwise make author:"user" match everyone.
+    const keys = (a ? [a.name?.toLowerCase(), a.id?.toLowerCase()] : [m.participant?.toLowerCase()]).filter(
+      (k): k is string => !!k,
+    );
+    if (inc && !keys.some((k) => inc.has(k))) return false;
+    if (exc && keys.some((k) => exc.has(k))) return false;
+    return true;
+  };
 }
 
 /** ~SNIPPET_CONTEXT_CHARS of surrounding context on each side of a match, or