@animalabs/agent-framework 0.19.0 → 0.21.0

package/dist/src/modules/history/index.d.ts

@@ -43,11 +43,22 @@ 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 { ChannelRegistry } from '../../mcpl/channel-registry.js';
+import { type SemanticIndexConfig, type SyncReport } from './semantic.js';
+export interface HistoryModuleOptions {
+    /** Enable `semantic_search` against a shared embed-service (see ./semantic.ts). Absent = tool not offered. */
+    semantic?: SemanticIndexConfig;
+}
 export declare class HistoryModule implements Module {
     readonly name = "history";
     private ctx;
     private cm;
     private channelRegistry;
+    private readonly semanticCfg;
+    private semanticClient;
+    private indexer;
+    private syncTimer;
+    private firstSyncTimer;
+    constructor(options?: HistoryModuleOptions);
     /**
      * Wire the context-manager instance, and optionally the host's
      * ChannelRegistry. Host calls this after ContextManager.open() so the
@@ -117,13 +128,86 @@ export declare class HistoryModule implements Module {
      * practice.
      */
     private boundaryMessagesAt;
+    /** 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;
+    /** Highest sequence in the store right now (the last append), or -1 when empty. */
+    private storeSeqMark;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
     start(ctx: ModuleContext): Promise<void>;
+    /** Pending edits/removals survive a restart through module state. Called from whichever of start()/bind() runs second. */
+    private wireIndexer;
     stop(): Promise<void>;
+    /**
+     * 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;
+    /** Exposed for hosts/tests: one sync pass now. */
+    syncSemanticIndex(maxItems?: number): Promise<SyncReport> | null;
     getTools(): ToolDefinition[];
+    private semanticSearchTool;
     handleToolCall(call: ToolCall): Promise<ToolResult>;
     onProcess(_event: ProcessEvent, _state: ProcessState): Promise<EventResponse>;
     private handleStats;
     private handleExtract;
+    /**
+     * `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;
     private handleSearch;
     /**
      * Run regex matching for `search` on a worker thread with a hard
@@ -140,6 +224,7 @@ export declare class HistoryModule implements Module {
      * must never be indistinguishable from a clean "no matches" result.
      */
     private searchWithRegexWorker;
+    private handleSemanticSearch;
     private handleOverview;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/src/modules/history/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/history/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAyE,MAAM,4BAA4B,CAAC;AAExI,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AA6GtE,qBAAa,aAAc,YAAW,MAAM;IAC1C,QAAQ,CAAC,IAAI,aAAa;IAE1B,OAAO,CAAC,GAAG,CAA8B;IACzC,OAAO,CAAC,EAAE,CAA+B;IACzC,OAAO,CAAC,eAAe,CAAgC;IAEvD;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,cAAc,EAAE,cAAc,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI;IAK7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,CAAC,cAAc;IAatB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAKpB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,QAAQ,IAAI,cAAc,EAAE;IA8GtB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;IAqCnD,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAQnF,OAAO,CAAC,WAAW;IAqCnB,OAAO,CAAC,aAAa;YA+BP,YAAY;IAuF1B;;;;;;;;;;;;;OAaG;YACW,qBAAqB;IA2DnC,OAAO,CAAC,cAAc;CAiXvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/history/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAyE,MAAM,4BAA4B,CAAC;AAExI,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAA0D,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAuB,MAAM,eAAe,CAAC;AA4EvJ,MAAM,WAAW,oBAAoB;IACnC,8GAA8G;IAC9G,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAoID,qBAAa,aAAc,YAAW,MAAM;IAC1C,QAAQ,CAAC,IAAI,aAAa;IAE1B,OAAO,CAAC,GAAG,CAA8B;IACzC,OAAO,CAAC,EAAE,CAA+B;IACzC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,cAAc,CAA8C;gBAExD,OAAO,GAAE,oBAAyB;IAK9C;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,cAAc,EAAE,cAAc,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI;IAc7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,OAAO,CAAC,cAAc;IAatB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAK1B;;qEAEiE;IACjE,OAAO,CAAC,SAAS;IAejB,mFAAmF;IACnF,OAAO,CAAC,YAAY;IAOpB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAqBrB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,UAAU;IAiFZ,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C,0HAA0H;IAC1H,OAAO,CAAC,WAAW;IAUb,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAWtB,kDAAkD;IAClD,iBAAiB,CAAC,QAAQ,SAAO,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAI9D,QAAQ,IAAI,cAAc,EAAE;IAiJ5B,OAAO,CAAC,kBAAkB;IAmCpB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;IAuCnD,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAQnF,OAAO,CAAC,WAAW;IAqCnB,OAAO,CAAC,aAAa;IAiOrB;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;YA2Fb,YAAY;IAyK1B;;;;;;;;;;;;;OAaG;YACW,qBAAqB;YA4DrB,oBAAoB;IA2HlC,OAAO,CAAC,cAAc;CAiXvB"}