@animalabs/agent-framework 0.26.2 → 0.27.0

package/src/module-registry.ts

@@ -21,6 +21,7 @@ import type {
   ProcessEvent,
   TraceEventListener,
   ModuleMessage,
+  ModuleContextInjection,
   MessageQueryResult,
 } from './types/index.js';
 import { heldWriteId } from './held-writes.js';
@@ -110,11 +111,11 @@ export class ModuleRegistry {
   private store: JsStore;
   private queue: ModuleQueue;
   private getAgents: () => Agent[];
-  private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
+  private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata, opts?: { forAgent?: string }) => MessageId;
   private editMessageFn: (id: MessageId, content: ContentBlock[]) => void;
   private removeMessageFn: (id: MessageId) => void;
   private getMessageFn: (id: MessageId) => ModuleMessage | null;
-  private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
+  private queryMessagesFn: (filter: MessageQuery, opts?: { forAgent?: string }) => MessageQueryResult;
 
   private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
@@ -134,11 +135,11 @@ export class ModuleRegistry {
     queue: ModuleQueue,
     options: {
       getAgents: () => Agent[];
-      addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
+      addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata, opts?: { forAgent?: string }) => MessageId;
       editMessage: (id: MessageId, content: ContentBlock[]) => void;
       removeMessage: (id: MessageId) => void;
       getMessage: (id: MessageId) => ModuleMessage | null;
-      queryMessages: (filter: MessageQuery) => MessageQueryResult;
+      queryMessages: (filter: MessageQuery, opts?: { forAgent?: string }) => MessageQueryResult;
       /** Called with the pushing module's name. */
       pushEvent: (event: ProcessEvent, moduleName?: string) => void;
       onTrace: (listener: TraceEventListener) => () => void;
@@ -230,7 +231,8 @@ export class ModuleRegistry {
 
   /**
    * Set state for a module by name.
-   * Used by the framework to apply stateUpdate from EventResponse atomically.
+   * Used by the framework to apply stateUpdate from EventResponse after its
+   * message changes.
    */
   setModuleState(moduleName: string, state: unknown): void {
     const ctx = this.moduleContexts.get(moduleName);
@@ -439,8 +441,18 @@ export class ModuleRegistry {
 
   /**
    * Gather context injections from all modules before inference.
-   * Calls each module's gatherContext() in parallel with a per-module timeout.
-   * Fail-open: timed-out or erroring modules are skipped (with a stderr line).
+   * Calls each module's gatherContext() in parallel with a per-module timeout,
+   * and returns their injections in the modules' registration order, whatever
+   * order they finish in. Fail-open: timed-out or erroring modules are skipped
+   * (with a stderr line), whether the call throws, rejects, or answers with
+   * something that isn't an array of objects, or with a `system` entry whose
+   * content isn't an array of objects, every block of which the agent's
+   * buildSystemPrompt reads, and one that answers after its timeout adds
+   * nothing. An array returned without a promise is taken as the module's
+   * answer. An entry's other fields are the module's to get right. Each
+   * module's budget starts once its call returns, after its own synchronous
+   * work and every earlier module's; a later module's synchronous work still
+   * counts against it.
    *
    * The per-module budget is `module.contextTimeoutMs` when declared, else the
    * `timeoutMs` default (15s). Modules whose gatherContext does real work —
@@ -450,12 +462,16 @@ export class ModuleRegistry {
    * to MAX_CONTEXT_TIMEOUT_MS so no single module can hold every turn hostage.
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
    */
-  async gatherContext(agentName: string, timeoutMs = 15_000): Promise<ContextInjection[]> {
-    const injections: ContextInjection[] = [];
+  async gatherContext(agentName: string, timeoutMs = 15_000): Promise<ModuleContextInjection[]> {
+    // Each module's result in registration order, whatever order they finish
+    // in: a stored injection's content hash follows that order, and a module
+    // that answers after its timeout adds nothing (it's skipped, fail-open).
+    const results: ModuleContextInjection[][] = [];
     const promises: Promise<void>[] = [];
 
     for (const module of this.modules.values()) {
-      if (!module.gatherContext) continue;
+      const gather = module.gatherContext;
+      if (!gather) continue;
 
       // Clamp the per-module budget. A module declaring `contextTimeoutMs`
       // legitimately needs more than the shared default (e.g. a retrieval
@@ -467,14 +483,43 @@ export class ModuleRegistry {
         MAX_CONTEXT_TIMEOUT_MS,
       );
       let timer: ReturnType<typeof setTimeout> | undefined;
+      let timedOut = false;
+      const slot = results.length;
+      results.push([]);
+      // Called here, before its timer is set, so its budget starts after its
+      // synchronous work; a call that throws is skipped as a rejection is.
+      let call: Promise<ModuleContextInjection[]>;
+      try {
+        call = Promise.resolve(gather.call(module, agentName));
+      } catch (err) {
+        call = Promise.reject(err);
+      }
       const promise = Promise.race([
-        module.gatherContext(agentName).then(r => {
-          injections.push(...r);
+        call.then(r => {
+          if (timedOut) return;
+          // Checked before it's kept, so an answer that isn't an array of
+          // objects skips the module, as does a system entry whose content
+          // isn't an array of objects: buildSystemPrompt reads every block
+          // of it, and one it can't read would fail the turn. Each array is
+          // read through Array.from, which reads a hole as `undefined`, as
+          // context-manager's compile does when it spreads the content.
+          if (!Array.isArray(r) || Array.from(r).some((entry) => entry === null || typeof entry !== 'object')) {
+            throw new TypeError(`gatherContext answered with ${Array.isArray(r) ? 'an array holding an entry that is not an object' : r === null ? 'null' : typeof r}, not an array of objects`);
+          }
+          const unreadable = r.find((entry) => entry.position === 'system'
+            && !(Array.isArray(entry.content) && Array.from(entry.content).every((block) => block !== null && typeof block === 'object')));
+          if (unreadable) {
+            throw new TypeError(`gatherContext answered with a system injection in namespace ${logValue(unreadable.namespace)} whose content isn't an array of objects`);
+          }
           this.noteBlocksNotShown(module.name, r);
+          results[slot] = [...r];
         }),
         new Promise<void>((_, rej) => {
           timer = setTimeout(
-            () => rej(new Error(`gatherContext timed out after ${budgetMs}ms`)),
+            () => {
+              timedOut = true;
+              rej(new Error(`gatherContext timed out after ${budgetMs}ms`));
+            },
             budgetMs,
           );
         }),
@@ -486,7 +531,7 @@ export class ModuleRegistry {
     }
 
     await Promise.all(promises);
-    return injections;
+    return results.flat();
   }
 
   /**
@@ -607,11 +652,11 @@ class ModuleContextImpl implements ModuleContext {
   private registry: ModuleRegistry;
   readonly isRestart: boolean;
   private getAgentsFn: () => Agent[];
-  private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
+  private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata, opts?: { forAgent?: string }) => MessageId;
   private editMessageFn: (id: MessageId, content: ContentBlock[]) => void;
   private removeMessageFn: (id: MessageId) => void;
   private getMessageFn: (id: MessageId) => ModuleMessage | null;
-  private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
+  private queryMessagesFn: (filter: MessageQuery, opts?: { forAgent?: string }) => MessageQueryResult;
   private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
@@ -627,11 +672,11 @@ class ModuleContextImpl implements ModuleContext {
     registry: ModuleRegistry,
     isRestart: boolean,
     getAgents: () => Agent[],
-    addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId,
+    addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata, opts?: { forAgent?: string }) => MessageId,
     editMessage: (id: MessageId, content: ContentBlock[]) => void,
     removeMessage: (id: MessageId) => void,
     getMessage: (id: MessageId) => ModuleMessage | null,
-    queryMessages: (filter: MessageQuery) => MessageQueryResult,
+    queryMessages: (filter: MessageQuery, opts?: { forAgent?: string }) => MessageQueryResult,
     pushEvent: (event: ProcessEvent, moduleName?: string) => void,
     onTrace: (listener: TraceEventListener) => () => void,
     callTool: (call: ToolCall) => Promise<ToolResult>
@@ -753,9 +798,17 @@ class ModuleContextImpl implements ModuleContext {
   addMessage(
     participant: string,
     content: ContentBlock[],
-    metadata?: MessageMetadata & { external?: ExternalIdRef }
+    metadata?: MessageMetadata & { external?: ExternalIdRef },
+    opts?: { forAgent?: string },
   ): MessageId {
-    const id = this.addMessageFn(participant, content, metadata);
+    // The external id map is read in the primary's store
+    // (findMessageByExternalId), so a mapping into another window would
+    // answer wrong.
+    if (metadata?.external && opts?.forAgent !== undefined) {
+      throw new Error(`A message for agent ${JSON.stringify(opts.forAgent)} can't carry metadata.external: `
+        + "its external id would be looked up in the primary's window. Leave forAgent out, or the external id.");
+    }
+    const id = this.addMessageFn(participant, content, metadata, opts);
 
     // Track external ID if provided. A write the framework holds keeps '',
     // as it did before held writes had handles: the map is module state an
@@ -819,8 +872,8 @@ class ModuleContextImpl implements ModuleContext {
     return this.getMessageFn(id);
   }
 
-  queryMessages(filter: MessageQuery): MessageQueryResult {
-    return this.queryMessagesFn(filter);
+  queryMessages(filter: MessageQuery, opts?: { forAgent?: string }): MessageQueryResult {
+    return this.queryMessagesFn(filter, opts);
   }
 
   getAgents(): AgentInfo[] {
@@ -976,7 +1029,7 @@ function withoutRefusal(call: ToolCall, result: ToolResult): ToolResult {
 }
 
 /** A result's flags, which consumers read for their truth: booleans here. */
-const RESULT_FLAGS = ['success', 'isError', 'endTurn'] as const;
+const RESULT_FLAGS = ['success', 'isError', 'endTurn', 'dataIsContent'] as const;
 
 /**
  * A module's tool result as the framework can store, send and trace it. A
@@ -1047,7 +1100,7 @@ export function checkedToolResult(call: ToolCall, result: unknown): { result: To
     endTurn = Boolean(fields.endTurn);
     read('error');
     ownText = errorText(fields.error);
-    for (const key of ['success', 'isError', 'data']) read(key);
+    for (const key of ['success', 'isError', 'data', 'dataIsContent']) read(key);
     for (const key of Object.keys(candidate)) {
       if (key !== 'toJSON' && !(key in fields)) fields[key] = candidate[key];
     }

package/src/modules/discord/index.ts

@@ -828,7 +828,7 @@ export class DiscordModule implements Module {
       const stored = this.storedRow(msg.discordMessageId);
       if (live) live.phase = 'writing';
 
-      // Return declarative response - framework applies all writes atomically
+      // Return declarative response - the framework applies its writes
       return {
         ...(stored ? {} : {
           addMessages: [

package/src/modules/history/index.ts

@@ -49,7 +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 { EmbedServiceError, SemanticIndexClient, SemanticIndexer, messageIndexText, summaryIndexText, type SearchResponse, type SemanticIndexConfig, type SyncReport, type PendingChanges } from './semantic.js';
+import { EmbedServiceError, SemanticIndexClient, SemanticIndexer, messageIndexText, parseSummaryKey, summaryIndexText, type SearchResponse, type SemanticIndexConfig, type SyncReport, type PendingChanges, type SyncCursors } from './semantic.js';
 import { unknownToolMessage } from '../unknown-tool.js';
 import { safeSlice } from '../../safe-slice.js';
 
@@ -624,6 +624,16 @@ export class HistoryModule implements Module {
       const prev = this.ctx?.getState<Record<string, unknown>>() ?? {};
       this.ctx?.setState({ ...prev, semanticPending: p });
     };
+    // Module state follows the store's branches, so each branch keeps its
+    // own sync cursors, and a branch made at an earlier point inherits them
+    // as they were there.
+    this.indexer.cursorStore = {
+      read: () => this.ctx?.getState<{ semanticCursors?: SyncCursors }>()?.semanticCursors ?? null,
+      write: (cursors) => {
+        const prev = this.ctx?.getState<Record<string, unknown>>() ?? {};
+        this.ctx?.setState({ ...prev, semanticCursors: cursors });
+      },
+    };
     this.indexer.attach();
   }
 
@@ -631,13 +641,16 @@ export class HistoryModule implements Module {
     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;
+    // Unwired from the state it can no longer reach, the indexer goes on
+    // from the cursors it last wrote for each branch, kept in memory.
+    if (this.indexer) { this.indexer.onPendingChange = null; this.indexer.cursorStore = 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
+   * 60 s) write at most `maxSyncPerTick` items to the index, counted as its
+   * doc says. 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.
@@ -1608,7 +1621,10 @@ export class HistoryModule implements Module {
       );
     }
 
-    // Bounded catch-up so the newest messages are searchable; never block on a backlog.
+    // A catch-up bounded in what it writes, so the newest messages are
+    // searchable without waiting on a backlog. It can re-send many items the
+    // index holds unchanged, as on a branch's first pass (maxSyncPerTick's
+    // doc), which costs a request per batch and no embedding.
     let sync: SyncReport | null = null;
     if (this.indexer) {
       try { sync = await this.indexer.catchUp(this.semanticCfg.maxSyncBeforeSearch ?? 256); } catch { /* reported via indexer.lastError */ }
@@ -1672,9 +1688,10 @@ export class HistoryModule implements Module {
     // to the model — getMessage/getSummary rebuild on branch switch, so an
     // undone message, or a summary this branch doesn't hold, answers null.
     // A branch made from an earlier point, as an undo makes one, can mint a
-    // summary id another branch already used, so a summary hit's score,
-    // timestamp and date filtering can still be that other summary's.
-    // k is small, so this is at most `limit` local lookups.
+    // summary id another branch already used, so a summary's key carries its
+    // creation time too, and a hit whose time isn't this branch's summary's
+    // is another branch's. 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
@@ -1685,14 +1702,12 @@ export class HistoryModule implements Module {
     // 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.
-    // A summary hit's snippet is rebuilt from the local summary too: a
-    // service that keeps only vectors and ids (no text) still yields one, and
-    // a summary whose id another branch also minted shows this branch's text
-    // in its snippet and chars.
+    // A summary hit's snippet is rebuilt from the local summary too, so a
+    // service that keeps only vectors and ids (no text) still yields one.
     const currentText = new Map<string, string>();
-    const keep = (h: { id: string }): 'ok' | 'offBranch' | 'stale' => {
+    const keep = (h: { id: string }): 'ok' | 'offBranch' | 'stale' | 'superseded' => {
       const msgId = /^msg:(.+)$/.exec(h.id)?.[1];
-      const sumId = /^sum:(.+)$/.exec(h.id)?.[1];
+      const sum = parseSummaryKey(h.id);
       if (msgId !== undefined) {
         const m = cm.getMessage(msgId);
         if (!m) return 'offBranch';
@@ -1701,9 +1716,18 @@ export class HistoryModule implements Module {
         currentText.set(h.id, text);
         return 'ok';
       }
-      if (sumId !== undefined) {
-        const s = cm.getSummary(sumId);
+      if (sum !== null) {
+        // An item from before keys carried the creation time is never a hit.
+        // One whose id names no summary on this branch is another branch's,
+        // and is counted as such. One whose id this branch has can hold this
+        // branch's summary or another's under the same id, and isn't counted.
+        // Until this branch's passes send the summary under its own key, as
+        // the search's catch-up does within its budget after any queued
+        // edits, a search can miss it.
+        const s = cm.getSummary(sum.id);
         if (!s) return 'offBranch';
+        if (sum.createdMs === null) return 'superseded';
+        if (s.created !== sum.createdMs) return 'offBranch';
         const text = summaryIndexText(s, this.semanticCfg!);
         // An empty text here is mostly defensive: context-manager drops a
         // summary that's empty after trimming when it loads, and refuses to
@@ -1771,10 +1795,13 @@ export class HistoryModule implements Module {
       const meta = typeof h.meta === 'object' && h.meta !== null && !Array.isArray(h.meta)
         ? h.meta as { participant?: unknown; author?: unknown }
         : null;
+      // A summary is shown as `sum:<id>`, as it was before its key carried its creation time.
+      const sum = parseSummaryKey(h.id);
+      const id = sum ? `sum:${sum.id}` : h.id;
       const missing = [...(h.ts !== null && timestamp === null ? ['ts'] : []), ...(meta === null ? ['meta'] : [])];
-      if (missing.length > 0) unread.push(`${shown(h.id)} (${missing.join(' and ')})`);
+      if (missing.length > 0) unread.push(`${shown(id)} (${missing.join(' and ')})`);
       return {
-        id: h.id,
+        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,
@@ -1797,7 +1824,10 @@ export class HistoryModule implements Module {
         hits,
         index: {
           indexed: res.count_indexed,
-          behind: sync ? sync.more : this.indexer === null ? null : true,
+          // The pass may have read another branch: one the search joined
+          // that started before a switch, or one the search left while it
+          // waited.
+          behind: this.indexer === null ? null : sync && this.indexer.passedOn(sync) === this.indexer.branchId() ? sync.more : 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). */