@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/module-registry.ts

@@ -1,4 +1,4 @@
-import type { JsStore } from '@animalabs/chronicle';
+import type { JsStateRegistration, JsStore } from '@animalabs/chronicle';
 import type { ContentBlock } from '@animalabs/membrane';
 import type {
   MessageId,
@@ -25,6 +25,7 @@ import type {
 } from './types/index.js';
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
+import { logValue } from './mcpl/log-value.js';
 
 /** How the registry queues a module's event: its push names the module. A
  * `ProcessQueue` serves too, ignoring the name. */
@@ -44,6 +45,25 @@ export function isStateExistsError(err: unknown): boolean {
   return err instanceof Error && err.message.includes('State already exists');
 }
 
+/**
+ * Register a state, treating "already exists" as done: a store reopened after
+ * a restart already holds it. Every other failure is thrown here, where it
+ * happened, naming the state, with the store's own error as its cause. Each
+ * state the framework registers goes through this.
+ */
+export function ensureStateRegistered(
+  store: Pick<JsStore, 'registerState'>,
+  registration: JsStateRegistration,
+): void {
+  try {
+    store.registerState(registration);
+  } catch (error) {
+    if (isStateExistsError(error)) return;
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Registering state '${registration.id}' failed: ${reason}`, { cause: error });
+  }
+}
+
 /**
  * Hard ceiling for a single module's gatherContext budget, regardless of the
  * `contextTimeoutMs` it declares. gatherContext runs on the critical path of
@@ -81,6 +101,8 @@ export class ModuleRegistry {
 
   private modules: Map<string, Module> = new Map();
   private stopping = new Map<Module, Promise<void>>();
+  /** Module and namespace pairs already told that a system injection held a block that isn't text. */
+  private notShownWarned = new Set<string>();
   private moduleContexts: Map<string, ModuleContextImpl> = new Map();
   private speechHandlers: SpeechHandler[] = [];
   private store: JsStore;
@@ -146,14 +168,7 @@ export class ModuleRegistry {
 
     // Register module state in store
     const stateId = this.getStateId(module.name);
-    try {
-      this.store.registerState({
-        id: stateId,
-        strategy: 'snapshot',
-      });
-    } catch {
-      // State already registered (from previous run)
-    }
+    ensureStateRegistered(this.store, { id: stateId, strategy: 'snapshot' });
 
     // Check if this is a restart (state exists)
     const existingState = this.store.getStateJson(stateId);
@@ -318,12 +333,13 @@ export class ModuleRegistry {
       };
     }
 
-    // Create a call with the un-prefixed name (preserving caller identity)
+    // Create a call with the un-prefixed name (preserving caller identity and turn)
     const moduleCall: ToolCall = {
       id: call.id,
       name: toolName,
       input: call.input,
       callerAgentName: call.callerAgentName,
+      ...(call.callerTurnId !== undefined ? { callerTurnId: call.callerTurnId } : {}),
     };
 
     try {
@@ -425,7 +441,10 @@ export class ModuleRegistry {
       );
       let timer: ReturnType<typeof setTimeout> | undefined;
       const promise = Promise.race([
-        module.gatherContext(agentName).then(r => injections.push(...r)),
+        module.gatherContext(agentName).then(r => {
+          injections.push(...r);
+          this.noteBlocksNotShown(module.name, r);
+        }),
         new Promise<void>((_, rej) => {
           timer = setTimeout(
             () => rej(new Error(`gatherContext timed out after ${budgetMs}ms`)),
@@ -443,6 +462,28 @@ export class ModuleRegistry {
     return injections;
   }
 
+  /**
+   * The system prompt is text, so an agent given a `system` injection reads
+   * a line in place of each of its blocks that isn't text (the agent's
+   * buildSystemPrompt), though `ContextInjection`'s content may be any
+   * block. The module meant those blocks for the model, so its operator is
+   * told, once per module and namespace, as the module's injections are
+   * gathered, whichever agents are given them.
+   */
+  private noteBlocksNotShown(moduleName: string, injections: ContextInjection[]): void {
+    for (const injection of injections) {
+      if (injection.position !== 'system' || !injection.content.some((block) => block.type !== 'text')) continue;
+      const key = `${moduleName}\u0000${injection.namespace}`;
+      if (this.notShownWarned.has(key)) continue;
+      this.notShownWarned.add(key);
+      console.error(
+        `[${moduleName}] gatherContext: a system injection in namespace ${logValue(injection.namespace)} holds a block that ` +
+          "isn't text, which the system prompt can't carry, so an agent given the injection reads a line in place of each such block; " +
+          'this line prints once per module and namespace while the host runs',
+      );
+    }
+  }
+
   /**
    * Tell modules an agent's tool batch completed (see
    * Module.onToolBatchComplete). Hooks run in parallel, each awaited up to
@@ -640,18 +681,12 @@ class ModuleContextImpl implements ModuleContext {
     name: string,
     opts?: { deltaSnapshotEvery?: number; fullSnapshotEvery?: number }
   ): void {
-    const id = this.logStateId(name);
-    try {
-      this.store.registerState({
-        id,
-        strategy: 'append_log',
-        deltaSnapshotEvery: opts?.deltaSnapshotEvery ?? 100,
-        fullSnapshotEvery: opts?.fullSnapshotEvery ?? 20,
-      });
-    } catch (err) {
-      if (!isStateExistsError(err)) throw err;
-      // Already registered (previous run) — idempotent path.
-    }
+    ensureStateRegistered(this.store, {
+      id: this.logStateId(name),
+      strategy: 'append_log',
+      deltaSnapshotEvery: opts?.deltaSnapshotEvery ?? 100,
+      fullSnapshotEvery: opts?.fullSnapshotEvery ?? 20,
+    });
     this.registeredLogStates.add(name);
   }
 

package/src/modules/api/index.ts

@@ -40,7 +40,7 @@ export class ApiModule implements Module {
 
   async handleToolCall(_call: ToolCall): Promise<ToolResult> {
     // API module has no tools
-    return { success: false, error: 'Unknown tool' };
+    return { success: false, error: 'Unknown tool', isError: true };
   }
 
   async onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {

package/src/modules/discord/discord-js-client.ts

@@ -29,6 +29,17 @@ export interface DiscordJsClientConfig {
   channelIds?: string[];
 }
 
+/** An attachment as both a live message and history carry it. */
+function toAttachment(a: Attachment): DiscordAttachment {
+  return {
+    id: a.id,
+    filename: a.name ?? 'unknown',
+    url: a.url,
+    contentType: a.contentType ?? undefined,
+    size: a.size,
+  };
+}
+
 export class DiscordJsClient implements DiscordClientInterface {
   private client: Client;
   private token: string;
@@ -68,7 +79,11 @@ export class DiscordJsClient implements DiscordClientInterface {
     });
 
     this.client.on('messageUpdate', (_oldMessage, newMessage) => {
-      if (!newMessage.content || !this.editHandler) return;
+      // content is null for a partial message, one discord.js hadn't cached
+      // and whose update carried no text, so there's no text to compare; a
+      // cached message keeps the text it had. An edit that leaves no text,
+      // beside an attachment, is '' and is still an edit.
+      if (typeof newMessage.content !== 'string' || !this.editHandler) return;
       this.editHandler(newMessage.id, newMessage.content);
     });
 
@@ -114,13 +129,7 @@ export class DiscordJsClient implements DiscordClientInterface {
   }
 
   private convertMessage(message: Message): DiscordMessageData {
-    const attachments: DiscordAttachment[] = message.attachments.map((a: Attachment) => ({
-      id: a.id,
-      filename: a.name ?? 'unknown',
-      url: a.url,
-      contentType: a.contentType ?? undefined,
-      size: a.size,
-    }));
+    const attachments = message.attachments.map(toAttachment);
 
     // Extract mentioned user IDs
     const mentionedUserIds = message.mentions.users.map((u: User) => u.id);
@@ -160,7 +169,7 @@ export class DiscordJsClient implements DiscordClientInterface {
     channelId: string,
     content: string,
     options?: { replyTo?: string; createThread?: { name: string } }
-  ): Promise<{ messageId: string }> {
+  ): Promise<{ messageId: string; threadFailure?: string }> {
     const channel = await this.client.channels.fetch(channelId);
     if (!channel || !('send' in channel)) {
       throw new Error(`Channel ${channelId} not found or not a text channel`);
@@ -173,7 +182,13 @@ export class DiscordJsClient implements DiscordClientInterface {
     });
 
     if (options?.createThread && 'threads' in textChannel) {
-      await message.startThread({ name: options.createThread.name });
+      try {
+        await message.startThread({ name: options.createThread.name });
+      } catch (error) {
+        // The message is out, so the caller counts it as sent before it
+        // reports why its thread wasn't started.
+        return { messageId: message.id, threadFailure: error instanceof Error ? error.message : String(error) };
+      }
     }
 
     return { messageId: message.id };
@@ -341,6 +356,7 @@ export class DiscordJsClient implements DiscordClientInterface {
       authorName: m.author.username,
       isBot: m.author.bot,
       content: m.content,
+      attachments: m.attachments.map(toAttachment),
       timestamp: m.createdAt,
       replyTo: m.reference
         ? {