@animalabs/agent-framework 0.30.0 → 0.32.0

package/src/module-registry.ts

@@ -19,12 +19,14 @@ import type {
   SpeechContext,
   SpeechHandlerOptions,
   ProcessEvent,
+  ToolResultEvent,
   TraceEventListener,
   ModuleMessage,
   ModuleContextInjection,
   MessageQueryResult,
 } from './types/index.js';
 import { heldWriteId } from './held-writes.js';
+import { boundedErrorMessage } from './error-message.js';
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
 import { logValue } from './mcpl/log-value.js';
@@ -38,6 +40,19 @@ export interface ModuleQueue {
 
 const MODULE_STATE_PREFIX = 'modules/';
 
+export function droppedToolResultLine(event: ToolResultEvent, when: string): string {
+  const outcome = event.result.success && !event.result.isError
+    ? 'succeeded'
+    : `failed${event.result.error ? `: ${boundedErrorMessage(event.result.error)}` : ''}`;
+  return `[framework] ${event.agentName}: result of tool call ${event.callId} (${event.toolName ? `${event.toolName}, ` : ''}${event.moduleName}) arrived ${when} — dropped; the tool ${outcome}`;
+}
+
+export function retiredPushLine(event: ProcessEvent, moduleName: string): string {
+  return event.type === 'tool-result'
+    ? droppedToolResultLine(event, `after module ${moduleName} stopped`)
+    : `[framework] a '${event.type}' event from module ${moduleName} arrived after that module stopped — dropped`;
+}
+
 /**
  * True when a registerState failure means "this state id already exists" —
  * the one failure that is safe to swallow on an idempotent re-registration.
@@ -104,6 +119,7 @@ export class ModuleRegistry {
 
   private modules: Map<string, Module> = new Map();
   private stopping = new Map<Module, Promise<void>>();
+  private starting = 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();
@@ -120,6 +136,11 @@ export class ModuleRegistry {
   private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
+  /**
+   * The constructor's `dropRetiredPush` option.
+   * @internal For the framework's drop lines; not a host API.
+   */
+  readonly dropRetiredPushFn?: (event: ProcessEvent, moduleName: string) => void;
   /** Framework ops-alert channel, surfaced to modules via
    *  ModuleContext.notifyOps. Readonly-public so ModuleContextImpl can
    *  delegate without another positional constructor parameter. */
@@ -142,6 +163,10 @@ export class ModuleRegistry {
       queryMessages: (filter: MessageQuery, opts?: { forAgent?: string }) => MessageQueryResult;
       /** Called with the pushing module's name. */
       pushEvent: (event: ProcessEvent, moduleName?: string) => void;
+      /** Logs a push a module made after its stop() completed, which is
+       *  dropped, not queued. Without it, the registry logs a line of its own.
+       *  @internal For the framework's drop lines; not a host API. */
+      dropRetiredPush?: (event: ProcessEvent, moduleName: string) => void;
       onTrace: (listener: TraceEventListener) => () => void;
       callTool: (call: ToolCall) => Promise<ToolResult>;
       notifyOps?: (kind: string, agentName: string, message: string, data?: Record<string, unknown>) => void;
@@ -159,6 +184,7 @@ export class ModuleRegistry {
     this.onTraceFn = options.onTrace;
     this.callToolFn = options.callTool;
     this.notifyOpsFn = options.notifyOps;
+    this.dropRetiredPushFn = options.dropRetiredPush;
   }
 
   /**
@@ -200,7 +226,21 @@ export class ModuleRegistry {
     this.moduleContexts.set(module.name, context);
 
     // Start the module
-    await module.start(context);
+    let release!: (start: Promise<void>) => void;
+    const settled = new Promise<void>((resolve) => { release = resolve; }).then(() => undefined, () => undefined);
+    this.starting.set(module, settled);
+    let started: Promise<void>;
+    try {
+      started = Promise.resolve(module.start(context));
+    } catch (error) {
+      started = Promise.reject(error);
+    }
+    release(started);
+    try {
+      await started;
+    } finally {
+      if (this.starting.get(module) === settled) this.starting.delete(module);
+    }
   }
 
   /**
@@ -229,6 +269,17 @@ export class ModuleRegistry {
     return Array.from(this.modules.values());
   }
 
+  /**
+   * The current registration of the module of this name: a value that
+   * changes each time a module of that name is added, the same module object
+   * included, and that stays the same until its stop() completes;
+   * `undefined` while none is registered.
+   * @internal For the framework's registration checks; not a host API.
+   */
+  registrationOf(moduleName: string): object | undefined {
+    return this.moduleContexts.get(moduleName);
+  }
+
   /**
    * Set state for a module by name.
    * Used by the framework to apply stateUpdate from EventResponse after its
@@ -385,7 +436,9 @@ export class ModuleRegistry {
 
   /**
    * Stop all modules. A caller may bound its wait without cancelling cleanup.
-   * The default waits for each module's own shutdown contract.
+   * The default waits for each module's own shutdown contract. A module whose
+   * start() is still running is stopped once its start() has settled, within
+   * the same wait.
    */
   async stopAll(timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS): Promise<void> {
     validateShutdownTimeout(timeoutMs);
@@ -397,11 +450,16 @@ export class ModuleRegistry {
   private stopModule(module: Module): Promise<void> {
     const existing = this.stopping.get(module);
     if (existing) return existing;
-    const attempt = Promise.resolve().then(() => module.stop()).then(() => {
+    const attempt = (this.starting.get(module) ?? Promise.resolve()).then(() => module.stop()).then(() => {
       if (this.modules.get(module.name) === module) {
+        const context = this.moduleContexts.get(module.name);
         this.modules.delete(module.name);
         this.moduleContexts.delete(module.name);
         this.speechHandlers = this.speechHandlers.filter(handler => handler.moduleName !== module.name);
+        this.batchHooksRunning.delete(module.name);
+        this.stopping.delete(module);
+        context?.retire();
+        return;
       }
       this.stopping.delete(module);
     }, error => {
@@ -453,7 +511,12 @@ export class ModuleRegistry {
    * 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
+   * nothing. Once every answer is in, the answers are merged, and an answer
+   * from a module whose registration has ended by then (its stop()
+   * completed, whether or not a module of its name has been added since) is
+   * left out, with a line if it held injections; a stop that completes after
+   * the merge doesn't change what this returned. 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
@@ -473,6 +536,7 @@ export class ModuleRegistry {
     // that answers after its timeout adds nothing (it's skipped, fail-open).
     const results: ModuleContextInjection[][] = [];
     const promises: Promise<void>[] = [];
+    const asked: { slot: number; moduleName: string; registration: object | undefined }[] = [];
 
     for (const module of this.modules.values()) {
       const gather = module.gatherContext;
@@ -491,6 +555,7 @@ export class ModuleRegistry {
       let timedOut = false;
       const slot = results.length;
       results.push([]);
+      asked.push({ slot, moduleName: module.name, registration: this.moduleContexts.get(module.name) });
       // 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[]>;
@@ -516,7 +581,6 @@ export class ModuleRegistry {
           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) => {
@@ -536,6 +600,19 @@ export class ModuleRegistry {
     }
 
     await Promise.all(promises);
+    for (const { slot, moduleName, registration } of asked) {
+      if (this.moduleContexts.get(moduleName) === registration) {
+        this.noteBlocksNotShown(moduleName, results[slot]);
+        continue;
+      }
+      if (results[slot].length > 0) {
+        console.error(
+          `[framework] module ${moduleName} stopped before its gatherContext answer for ${agentName} was used, ` +
+          `so its ${results[slot].length} injection(s) were left out`,
+        );
+      }
+      results[slot] = [];
+    }
     return results.flat();
   }
 
@@ -565,7 +642,8 @@ export class ModuleRegistry {
    * Tell modules an agent's tool batch completed (see
    * Module.onToolBatchComplete). Hooks run in parallel, each awaited up to
    * `timeoutMs`; a hook that throws or times out is logged and skipped, so a
-   * wedged module can't hold the round. Returns the modules that didn't
+   * wedged module can't hold the round. A module whose `stop()` completes
+   * before its hook is called isn't called. Returns the modules that didn't
    * finish, for the caller's trace.
    */
   async notifyToolBatchComplete(
@@ -583,10 +661,14 @@ export class ModuleRegistry {
         failures.push({ module: module.name, error: 'still running from an earlier batch' });
         continue;
       }
+      const registration = this.moduleContexts.get(module.name);
       // Called from a promise, so a hook that throws synchronously, before
       // returning its promise, is caught below like any other failure
       // instead of escaping the round (the result would never be provided).
-      const call = Promise.resolve().then(() => module.onToolBatchComplete!(agentName));
+      const call = Promise.resolve().then(() => {
+        if (this.moduleContexts.get(module.name) !== registration) return;
+        return module.onToolBatchComplete!(agentName);
+      });
       this.batchHooksRunning.set(module.name, call);
       const settled = (): void => {
         if (this.batchHooksRunning.get(module.name) === call) this.batchHooksRunning.delete(module.name);
@@ -623,10 +705,11 @@ export class ModuleRegistry {
     // Find handlers that match this agent
     const handlers = this.speechHandlers.filter(
       (h) => h.agents === '*' || h.agents.includes(agentName)
-    );
+    ).map((handler) => ({ handler, registration: this.moduleContexts.get(handler.moduleName) }));
 
     // Call each handler
-    for (const handler of handlers) {
+    for (const { handler, registration } of handlers) {
+      if (this.moduleContexts.get(handler.moduleName) !== registration) continue;
       const module = this.modules.get(handler.moduleName);
       if (module?.onAgentSpeech) {
         try {
@@ -669,6 +752,10 @@ class ModuleContextImpl implements ModuleContext {
   // External ID mapping stored in module state
   private externalIdMap: Map<string, MessageId> = new Map();
 
+  private retired = false;
+  private readonly saidRetired = new Set<string>();
+  private readonly traceSubscriptions = new Set<() => void>();
+
   constructor(
     moduleName: string,
     store: JsStore,
@@ -690,7 +777,12 @@ class ModuleContextImpl implements ModuleContext {
     this.store = store;
     this.stateId = stateId;
     // The deprecated handle: a push names this module, as pushEvent() does.
-    this.queue = { push: (event) => queue.push(event, moduleName) };
+    this.queue = {
+      push: (event) => {
+        if (this.retired) this.dropPush(event);
+        else queue.push(event, moduleName);
+      },
+    };
     this.registry = registry;
     this.isRestart = isRestart;
     this.getAgentsFn = getAgents;
@@ -710,12 +802,38 @@ class ModuleContextImpl implements ModuleContext {
     }
   }
 
+  retire(): void {
+    this.retired = true;
+    const subscriptions = [...this.traceSubscriptions];
+    this.traceSubscriptions.clear();
+    for (const unsubscribe of subscriptions) {
+      try {
+        unsubscribe();
+      } catch (error) {
+        console.error(`[framework] module ${JSON.stringify(this.moduleName)} has stopped, and ending one of its trace subscriptions threw: ${boundedErrorMessage(error)}`);
+      }
+    }
+  }
+
+  private refused(method: string): boolean {
+    if (!this.retired) return false;
+    if (!this.saidRetired.has(method)) {
+      this.saidRetired.add(method);
+      console.error(
+        `[framework] module ${JSON.stringify(this.moduleName)} has stopped, so its ${method}() call had no effect; ` +
+        `later ${method}() calls from it aren't logged`,
+      );
+    }
+    return true;
+  }
+
   getState<T>(): T | null {
     const state = this.store.getStateJson(this.stateId);
     return state as T | null;
   }
 
   setState<T>(state: T): void {
+    if (this.refused('setState')) return;
     // Merge external ID map into state
     const fullState = {
       ...(state as object),
@@ -758,6 +876,7 @@ class ModuleContextImpl implements ModuleContext {
     name: string,
     opts?: { deltaSnapshotEvery?: number; fullSnapshotEvery?: number }
   ): void {
+    if (this.refused('registerLogState')) return;
     ensureStateRegistered(this.store, {
       id: this.logStateId(name),
       strategy: 'append_log',
@@ -768,10 +887,12 @@ class ModuleContextImpl implements ModuleContext {
   }
 
   appendToLog<T>(name: string, item: T): void {
+    if (this.refused('appendToLog')) return;
     this.store.appendToStateJson(this.registeredLogStateId(name), item);
   }
 
   editLogItem<T>(name: string, index: number, item: T): void {
+    if (this.refused('editLogItem')) return;
     this.store.editStateItem(this.registeredLogStateId(name), index, Buffer.from(JSON.stringify(item)));
   }
 
@@ -785,18 +906,34 @@ class ModuleContextImpl implements ModuleContext {
   }
 
   getModule<T extends Module>(name: string): T | null {
+    if (this.refused('getModule')) return null;
     return this.registry.getModule<T>(name);
   }
 
   onTrace(listener: TraceEventListener): () => void {
-    return this.onTraceFn(listener);
+    if (this.refused('onTrace')) return () => {};
+    const unsubscribe = this.onTraceFn((event) => {
+      if (!this.retired) listener(event);
+    });
+    this.traceSubscriptions.add(unsubscribe);
+    return () => {
+      if (this.traceSubscriptions.delete(unsubscribe)) unsubscribe();
+    };
   }
 
   callTool(call: ToolCall): Promise<ToolResult> {
+    if (this.refused('callTool')) {
+      return Promise.resolve({
+        success: false,
+        isError: true,
+        error: `module ${JSON.stringify(this.moduleName)} has stopped, so its call of ${call.name} wasn't made`,
+      });
+    }
     return this.callToolFn(call);
   }
 
   notifyOps(kind: string, agentName: string, message: string, data?: Record<string, unknown>): void {
+    if (this.refused('notifyOps')) return;
     this.registry.notifyOpsFn?.(kind, agentName, message, data);
   }
 
@@ -806,6 +943,7 @@ class ModuleContextImpl implements ModuleContext {
     metadata?: MessageMetadata & { external?: ExternalIdRef },
     opts?: { forAgent?: string },
   ): MessageId {
+    if (this.refused('addMessage')) return '';
     // The external id map is read in the primary's store
     // (findMessageByExternalId), so a mapping into another window would
     // answer wrong.
@@ -830,10 +968,12 @@ class ModuleContextImpl implements ModuleContext {
   }
 
   editMessage(id: MessageId, content: ContentBlock[]): void {
+    if (this.refused('editMessage')) return;
     this.editMessageFn(id, content);
   }
 
   removeMessage(id: MessageId): void {
+    if (this.refused('removeMessage')) return;
     this.removeMessageFn(id);
     // Clean up external ID mapping
     for (const [key, msgId] of this.externalIdMap) {
@@ -850,26 +990,31 @@ class ModuleContextImpl implements ModuleContext {
     const entry = this.externalIdMap.get(key);
     if (entry === undefined) return null;
     // A stored id answers while the store holds its row, and once the row is
-    // gone the entry goes, as removeMessage drops it. The '' a held write
-    // keeps here (addMessage) names no row, so the message is looked up in
-    // the store by its external id, held rows included, and the first row
-    // found is taken, as context-manager's findByExternalId takes it: a held
-    // row answers by its handle and leaves the entry as it is, and a stored
-    // row's id becomes the entry. With nothing found, '' stays, as earlier
-    // releases kept it: in a module's start(), the writes the last process
-    // held don't show yet, since create() restores them after the modules
-    // start, and a write that shows later finds its entry.
+    // gone the entry goes, as removeMessage drops it, except from a context
+    // whose module has stopped, which keeps its mapping as it was. The '' a held
+    // write keeps here (addMessage) names no row, so the message is looked up in
+    // the store by its external id, held rows included, and the first row found
+    // is taken, as context-manager's findByExternalId takes it: a held row
+    // answers by its handle and leaves the entry as it is, and a stored row's id
+    // becomes the entry. With nothing found, '' stays, as earlier releases kept
+    // it: in a module's start(), the writes the last process held don't show
+    // yet, since create() restores them after the modules start, and a write
+    // that shows later finds its entry.
     if (entry !== '') {
       if (this.getMessageFn(entry)) return entry;
-      this.externalIdMap.delete(key);
-      this.persistExternalIdMap();
+      if (!this.retired) {
+        this.externalIdMap.delete(key);
+        this.persistExternalIdMap();
+      }
       return null;
     }
     const row = this.queryMessagesFn({ source, externalIds: [externalId] }).messages[0];
     if (row?.held) return row.id;
     if (!row) return null;
-    this.externalIdMap.set(key, row.id);
-    this.persistExternalIdMap();
+    if (!this.retired) {
+      this.externalIdMap.set(key, row.id);
+      this.persistExternalIdMap();
+    }
     return row.id;
   }
 
@@ -893,15 +1038,23 @@ class ModuleContextImpl implements ModuleContext {
     agents: '*' | string[],
     options?: SpeechHandlerOptions
   ): void {
+    if (this.refused('registerSpeechHandler')) return;
     this.registry.registerSpeechHandler(this.moduleName, agents, options);
   }
 
   unregisterSpeechHandler(): void {
+    if (this.refused('unregisterSpeechHandler')) return;
     this.registry.unregisterSpeechHandler(this.moduleName);
   }
 
   pushEvent(event: ProcessEvent): void {
-    this.pushEventFn(event, this.moduleName);
+    if (this.retired) this.dropPush(event);
+    else this.pushEventFn(event, this.moduleName);
+  }
+
+  private dropPush(event: ProcessEvent): void {
+    if (this.registry.dropRetiredPushFn) this.registry.dropRetiredPushFn(event, this.moduleName);
+    else console.error(retiredPushLine(event, this.moduleName));
   }
 
   private persistExternalIdMap(): void {

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

@@ -2,24 +2,18 @@
  * Discord.js client adapter implementing DiscordClientInterface
  */
 
-import {
-  ChannelType,
+import { createRequire } from 'node:module';
+import type {
   Client,
   DiscordAPIError,
-  DiscordjsError,
-  DiscordjsErrorCodes,
-  DiscordjsTypeError,
-  GatewayIntentBits,
-  Partials,
-  RESTJSONErrorCodes,
   TextChannel,
   DMChannel,
-  type Channel,
-  type Message,
-  type Attachment,
-  type User,
-  type Guild,
-  type GuildBasedChannel,
+  Channel,
+  Message,
+  Attachment,
+  User,
+  Guild,
+  GuildBasedChannel,
 } from 'discord.js';
 import type {
   DiscordClientInterface,
@@ -31,6 +25,12 @@ import type {
 } from './types.js';
 import { DiscordRefusal } from './refusal.js';
 
+const requireHere = createRequire(import.meta.url);
+
+function discordJs(): typeof import('discord.js') {
+  return requireHere('discord.js') as typeof import('discord.js');
+}
+
 /** The ids a tool's call named, for the words of Discord's refusal. */
 interface Named {
   channelId?: string;
@@ -55,6 +55,7 @@ function target(named: Named): string {
  * `overrides` words a code as one tool means it.
  */
 function refusalReason(error: DiscordAPIError, named: Named, overrides: Partial<Record<number, string>> = {}): string {
+  const { RESTJSONErrorCodes } = discordJs();
   const override = typeof error.code === 'number' ? overrides[error.code] : undefined;
   if (override !== undefined) return override;
   switch (error.code) {
@@ -103,6 +104,7 @@ function unknownEmoji(named: Named): string {
  * emoji it can't read. Any other error has no words here.
  */
 function localRefusalReason(error: unknown, named: Named): string | undefined {
+  const { DiscordjsError, DiscordjsTypeError, DiscordjsErrorCodes } = discordJs();
   if (!(error instanceof DiscordjsError) && !(error instanceof DiscordjsTypeError)) return undefined;
   switch ((error as { code?: unknown }).code) {
     case DiscordjsErrorCodes.MessageThreadParent:
@@ -149,15 +151,16 @@ export class DiscordJsClient implements DiscordClientInterface {
     this.guildIds = config.guildIds;
     this.channelIds = config.channelIds;
 
-    this.client = new Client({
+    const djs = discordJs();
+    this.client = new djs.Client({
       intents: [
-        GatewayIntentBits.Guilds,
-        GatewayIntentBits.GuildMessages,
-        GatewayIntentBits.MessageContent,
-        GatewayIntentBits.DirectMessages,
-        GatewayIntentBits.GuildMessageReactions,
+        djs.GatewayIntentBits.Guilds,
+        djs.GatewayIntentBits.GuildMessages,
+        djs.GatewayIntentBits.MessageContent,
+        djs.GatewayIntentBits.DirectMessages,
+        djs.GatewayIntentBits.GuildMessageReactions,
       ],
-      partials: [Partials.Channel, Partials.Message],
+      partials: [djs.Partials.Channel, djs.Partials.Message],
     });
 
     this.setupEventHandlers();
@@ -301,17 +304,18 @@ export class DiscordJsClient implements DiscordClientInterface {
       await message.startThread({ name });
       return undefined;
     } catch (error) {
-      if (error instanceof DiscordAPIError) {
+      const djs = discordJs();
+      if (error instanceof djs.DiscordAPIError) {
         // Discord answers a retried start that it had already carried out as
         // a thread that exists: say it's there.
-        if (error.code === RESTJSONErrorCodes.ThreadAlreadyCreatedForMessage) return `${sent}, and its thread exists already, with the message's own id, ${message.id}.`;
+        if (error.code === djs.RESTJSONErrorCodes.ThreadAlreadyCreatedForMessage) return `${sent}, and its thread exists already, with the message's own id, ${message.id}.`;
         // The message is out, and `named` holds it, so no sentence points
         // elsewhere, where posting it again would post it twice.
         // The bot has just posted in the channel, so Missing Access is about
         // its threads, not about seeing it.
         const permission = `this bot isn't allowed to start threads in channel ${channelId} (Discord answered "Missing Permissions"), and calling again won't change that. Ask whoever runs this host to grant the permission.`;
         const access = `this bot can't start threads in channel ${channelId} (Discord answered "Missing Access"), and calling again won't change that. Ask whoever runs this host to give it access.`;
-        return `${sent}, but no thread was started: ${refusalReason(error, named, { [RESTJSONErrorCodes.MissingPermissions]: permission, [RESTJSONErrorCodes.MissingAccess]: access })} Once that's settled, ${startOne} starts one.`;
+        return `${sent}, but no thread was started: ${refusalReason(error, named, { [djs.RESTJSONErrorCodes.MissingPermissions]: permission, [djs.RESTJSONErrorCodes.MissingAccess]: access })} Once that's settled, ${startOne} starts one.`;
       }
       // The thread refusals localRefusalReason words, a message outside a
       // text or announcement channel and one that has a thread, can't come
@@ -359,7 +363,7 @@ export class DiscordJsClient implements DiscordClientInterface {
     } catch (error) {
       // A message that isn't there may be one an earlier call deleted, or a
       // retried request of this one, so its sentence has no lead.
-      if (error instanceof DiscordRefusal && error.cause instanceof DiscordAPIError && error.cause.code === RESTJSONErrorCodes.UnknownMessage) {
+      if (error instanceof DiscordRefusal && error.cause instanceof discordJs().DiscordAPIError && error.cause.code === discordJs().RESTJSONErrorCodes.UnknownMessage) {
         throw new DiscordRefusal(`Channel ${channelId} has no message ${messageId} now: it's deleted, or the id is wrong. discord--fetch_history with that channelId shows its recent messages and their ids.`, { cause: error.cause });
       }
       throw error;
@@ -393,7 +397,7 @@ export class DiscordJsClient implements DiscordClientInterface {
     } catch (error) {
       // Discord's answer for a message that has a thread, whether an earlier
       // call started it or a retried request of this one did.
-      if (error instanceof DiscordRefusal && error.cause instanceof DiscordAPIError && error.cause.code === RESTJSONErrorCodes.ThreadAlreadyCreatedForMessage) {
+      if (error instanceof DiscordRefusal && error.cause instanceof discordJs().DiscordAPIError && error.cause.code === discordJs().RESTJSONErrorCodes.ThreadAlreadyCreatedForMessage) {
         throw new DiscordRefusal(`Message ${messageId} has a thread already, whose id is the message's own: discord--send with channelId ${messageId} posts in it.`, { cause: error.cause });
       }
       throw error;
@@ -427,7 +431,7 @@ export class DiscordJsClient implements DiscordClientInterface {
     try {
       return await run();
     } catch (error) {
-      if (error instanceof DiscordAPIError || error instanceof DiscordRefusal) throw error;
+      if (error instanceof discordJs().DiscordAPIError || error instanceof DiscordRefusal) throw error;
       throw new DiscordRefusal(`${lead}: looking up ${what} stopped on an unexpected error: ${error instanceof Error ? error.message : String(error)}. Calling it again is safe.`, { cause: error });
     }
   }
@@ -443,7 +447,7 @@ export class DiscordJsClient implements DiscordClientInterface {
     try {
       return await run();
     } catch (error) {
-      if (error instanceof DiscordAPIError) throw new DiscordRefusal(`${lead}: ${refusalReason(error, named)}`, { cause: error });
+      if (error instanceof discordJs().DiscordAPIError) throw new DiscordRefusal(`${lead}: ${refusalReason(error, named)}`, { cause: error });
       const local = localRefusalReason(error, named);
       if (local !== undefined) throw new DiscordRefusal(`${lead}: ${local}`, { cause: error });
       throw error;
@@ -471,7 +475,7 @@ export class DiscordJsClient implements DiscordClientInterface {
     const inPosts = (kind: string) => `${kind}, whose messages are in its posts, each a thread with its own id, which this module has no tool to list`;
     const is = type === 'category' ? 'a category, which holds channels, not messages'
       : type === 'forum' ? inPosts('a forum')
-      : channel.type === ChannelType.GuildMedia ? inPosts('a media channel')
+      : channel.type === discordJs().ChannelType.GuildMedia ? inPosts('a media channel')
       : type === 'unknown' ? 'a kind of channel that holds no messages'
       : `a ${type} channel, which holds no messages`;
     return `channel ${channelId} is ${is}. discord--list_channels with a guildId shows the server's channels and their ids.`;

package/src/modules/sender-name.ts

@@ -1,9 +1,12 @@
+import { markedText } from '../supplied-text.js';
+
 /** The participant a module stores for a sender's name from outside the
- *  framework: on one line, and marked with its source, so it isn't an
- *  agent's name unless a host names an agent in that form. The generic
- *  `user` stays as given, since context-manager places injections by the
- *  last message whose participant is `user`, in any capitalization. */
+ *  framework: on one line, with each listed notice opening marked as in
+ *  supplied text, and marked with its source, so it isn't an agent's name
+ *  unless a host names an agent in that form. The generic `user` stays as
+ *  given, since context-manager places injections by the last message whose
+ *  participant is `user`, in any capitalization. */
 export function outsideSenderName(name: string, source: string): string {
-  const line = name.replace(/[\p{Cc}\u2028\u2029]+/gu, ' ');
+  const line = markedText(name.replace(/[\p{Cc}\u2028\u2029]+/gu, ' '));
   return line.toLowerCase() === 'user' ? line : `${line} (${source})`;
 }