@animalabs/agent-framework 0.15.0 → 0.17.0

package/dist/src/modules/history/index.d.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,18 +42,81 @@ import type { ContextManager } from '@animalabs/context-manager';
 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';
 export declare class HistoryModule implements Module {
     readonly name = "history";
     private ctx;
     private cm;
+    private channelRegistry;
+    /**
+     * 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, channelRegistry?: ChannelRegistry): void;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
-     * 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.
+     * 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.
      */
-    bind(contextManager: ContextManager): void;
+    private boundaryMessagesAt;
     start(ctx: ModuleContext): Promise<void>;
     stop(): Promise<void>;
     getTools(): ToolDefinition[];
@@ -65,5 +140,6 @@ export declare class HistoryModule implements Module {
      * must never be indistinguishable from a clean "no matches" result.
      */
     private searchWithRegexWorker;
+    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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAkD,MAAM,4BAA4B,CAAC;AAEjH,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;AAgFzE,qBAAa,aAAc,YAAW,MAAM;IAC1C,QAAQ,CAAC,IAAI,aAAa;IAE1B,OAAO,CAAC,GAAG,CAA8B;IACzC,OAAO,CAAC,EAAE,CAA+B;IAEzC;;;;;;OAMG;IACH,IAAI,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI;IAIpC,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,QAAQ,IAAI,cAAc,EAAE;IAiEtB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;IAmCnD,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAQnF,OAAO,CAAC,WAAW;IAoCnB,OAAO,CAAC,aAAa;YA8BP,YAAY;IAsF1B;;;;;;;;;;;;;OAaG;YACW,qBAAqB;CAsDpC"}
+{"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"}