@animalabs/agent-framework 0.22.3 → 0.23.0

package/src/module-registry.ts

@@ -4,8 +4,6 @@ import type {
   MessageId,
   MessageMetadata,
   MessageQuery,
-  MessageQueryResult,
-  StoredMessage,
   ContextInjection,
 } from '@animalabs/context-manager';
 import type {
@@ -22,10 +20,14 @@ import type {
   SpeechHandlerOptions,
   ProcessEvent,
   TraceEventListener,
+  ModuleMessage,
+  MessageQueryResult,
 } from './types/index.js';
+import { heldWriteId } from './held-writes.js';
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
 import { logValue } from './mcpl/log-value.js';
+import { toolArgsProblems } from './tool-args.js';
 
 /** How the registry queues a module's event: its push names the module. A
  * `ProcessQueue` serves too, ignoring the name. */
@@ -111,7 +113,7 @@ export class ModuleRegistry {
   private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
   private editMessageFn: (id: MessageId, content: ContentBlock[]) => void;
   private removeMessageFn: (id: MessageId) => void;
-  private getMessageFn: (id: MessageId) => StoredMessage | null;
+  private getMessageFn: (id: MessageId) => ModuleMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
 
   private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
@@ -135,7 +137,7 @@ export class ModuleRegistry {
       addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
       editMessage: (id: MessageId, content: ContentBlock[]) => void;
       removeMessage: (id: MessageId) => void;
-      getMessage: (id: MessageId) => StoredMessage | null;
+      getMessage: (id: MessageId) => ModuleMessage | null;
       queryMessages: (filter: MessageQuery) => MessageQueryResult;
       /** Called with the pushing module's name. */
       pushEvent: (event: ProcessEvent, moduleName?: string) => void;
@@ -300,8 +302,8 @@ export class ModuleRegistry {
    * model. The result is checked and read once, in its JSON form
    * ({@link storableToolResult}).
    */
-  async storableToolCall(call: ToolCall): Promise<ToolResult> {
-    return storableToolResult(call, await this.handleToolCall(call));
+  async storableToolCall(call: ToolCall, options: { definition?: ToolDefinition } = {}): Promise<ToolResult> {
+    return storableToolResult(call, await this.handleToolCall(call, options));
   }
 
   /**
@@ -309,8 +311,14 @@ export class ModuleRegistry {
    * result, unchecked, as it returned it, for a caller that uses the result
    * in process (`ModuleContext.callTool`, `executeToolCall`, or a host
    * calling the registry). A module's throw is answered as an error result.
+   * A call whose input isn't an object, or lacks a key the tool's schema
+   * requires, is answered before the module runs, with an error result that
+   * opens "Nothing was done:" and names what to send (toolArgsProblems).
+   * A caller that has already resolved the tool's definition, as the `utils`
+   * tool has a utility's, passes it as `definition`, and it's checked against
+   * that one.
    */
-  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+  async handleToolCall(call: ToolCall, options: { definition?: ToolDefinition } = {}): Promise<ToolResult> {
     // Parse module--tool name
     const sepIndex = call.name.indexOf('--');
     if (sepIndex === -1) {
@@ -343,6 +351,27 @@ export class ModuleRegistry {
     };
 
     try {
+      // The call against the tool's declared schema, before the module runs:
+      // a missing required argument is refused with what to send, where the
+      // handler would otherwise fail deep inside, or run without it. Values
+      // aren't checked here, since a handler may take more than its schema
+      // can say (toolArgsProblems). The module's own listing runs inside the
+      // try, so its throw is answered like any other. Utilities are listed
+      // only for a name the tools don't have, so a utility listing that
+      // throws or is slow reaches only calls to such names: a utility called
+      // by its own name, and a name the module answers without declaring it.
+      // A caller that passes `definition` lists nothing.
+      const definition = options.definition
+        ?? module.getTools().find((tool) => tool.name === toolName)
+        ?? module.getUtilities?.()?.find((tool) => tool.name === toolName);
+      const problems = toolArgsProblems(call.input, definition?.inputSchema);
+      if (problems.length > 0) {
+        return {
+          success: false,
+          error: `Nothing was done: ${call.name} ${problems.join('; ')}.`,
+          isError: true,
+        };
+      }
       return await module.handleToolCall(moduleCall);
     } catch (error) {
       return thrownResult(error);
@@ -583,7 +612,7 @@ class ModuleContextImpl implements ModuleContext {
   private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
   private editMessageFn: (id: MessageId, content: ContentBlock[]) => void;
   private removeMessageFn: (id: MessageId) => void;
-  private getMessageFn: (id: MessageId) => StoredMessage | null;
+  private getMessageFn: (id: MessageId) => ModuleMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
   private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
@@ -603,7 +632,7 @@ class ModuleContextImpl implements ModuleContext {
     addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId,
     editMessage: (id: MessageId, content: ContentBlock[]) => void,
     removeMessage: (id: MessageId) => void,
-    getMessage: (id: MessageId) => StoredMessage | null,
+    getMessage: (id: MessageId) => ModuleMessage | null,
     queryMessages: (filter: MessageQuery) => MessageQueryResult,
     pushEvent: (event: ProcessEvent, moduleName?: string) => void,
     onTrace: (listener: TraceEventListener) => () => void,
@@ -730,10 +759,13 @@ class ModuleContextImpl implements ModuleContext {
   ): MessageId {
     const id = this.addMessageFn(participant, content, metadata);
 
-    // Track external ID if provided
+    // 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
+    // earlier release reads back, and a handle is no id to it.
+    // findMessageByExternalId finds the held write by its external id.
     if (metadata?.external) {
       const key = `${metadata.external.source}:${metadata.external.id}`;
-      this.externalIdMap.set(key, id);
+      this.externalIdMap.set(key, heldWriteId(id) === undefined ? id : '');
       // Persist the mapping
       this.persistExternalIdMap();
     }
@@ -759,10 +791,33 @@ class ModuleContextImpl implements ModuleContext {
 
   findMessageByExternalId(source: string, externalId: string): MessageId | null {
     const key = `${source}:${externalId}`;
-    return this.externalIdMap.get(key) ?? null;
+    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.
+    if (entry !== '') {
+      if (this.getMessageFn(entry)) return entry;
+      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();
+    return row.id;
   }
 
-  getMessage(id: MessageId): StoredMessage | null {
+  getMessage(id: MessageId): ModuleMessage | null {
     return this.getMessageFn(id);
   }
 

package/src/modules/api/index.ts

@@ -5,6 +5,7 @@
  * into conversation messages and inference requests.
  */
 
+import { unknownToolMessage } from '../unknown-tool.js';
 import type {
   Module,
   ModuleContext,
@@ -38,9 +39,9 @@ export class ApiModule implements Module {
     // Nothing to clean up
   }
 
-  async handleToolCall(_call: ToolCall): Promise<ToolResult> {
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
     // API module has no tools
-    return { success: false, error: 'Unknown tool', isError: true };
+    return { success: false, error: unknownToolMessage(this.name, call.name, this.getTools()), isError: true };
   }
 
   async onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {

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

@@ -3,11 +3,18 @@
  */
 
 import {
+  ChannelType,
   Client,
+  DiscordAPIError,
+  DiscordjsError,
+  DiscordjsErrorCodes,
+  DiscordjsTypeError,
   GatewayIntentBits,
   Partials,
+  RESTJSONErrorCodes,
   TextChannel,
   DMChannel,
+  type Channel,
   type Message,
   type Attachment,
   type User,
@@ -22,6 +29,92 @@ import type {
   DiscordChannel,
   HistoryMessage,
 } from './types.js';
+import { DiscordRefusal } from './refusal.js';
+
+/** The ids a tool's call named, for the words of Discord's refusal. */
+interface Named {
+  channelId?: string;
+  messageId?: string;
+  guildId?: string;
+  userId?: string;
+  emoji?: string;
+}
+
+/** What a refused call was about, from the ids it named. */
+function target(named: Named): string {
+  return named.channelId !== undefined ? `channel ${named.channelId}`
+    : named.guildId !== undefined ? `server ${named.guildId}`
+    : `user ${named.userId}`;
+}
+
+/**
+ * Discord's refusal of a request, worded for the agent: what was refused, and
+ * the call that shows the right id, or who can change what Discord refused.
+ * The codes are discord-api-types' RESTJSONErrorCodes, as discord.js 14.27
+ * exports them. A code without a case of its own keeps Discord's own words.
+ * `overrides` words a code as one tool means it.
+ */
+function refusalReason(error: DiscordAPIError, named: Named, overrides: Partial<Record<number, string>> = {}): string {
+  const override = typeof error.code === 'number' ? overrides[error.code] : undefined;
+  if (override !== undefined) return override;
+  switch (error.code) {
+    case RESTJSONErrorCodes.UnknownChannel:
+      return `no ${target(named)} is visible to this bot. The id may be mistyped or remembered rather than copied; discord--list_guilds, then discord--list_channels with a guildId, shows the ids. Threads aren't listed there: a thread started from a message has that message's id, which discord--fetch_history of its channel shows. Nor are direct message channels: one's id is the channelId an earlier discord--dm to that user returned.`;
+    case RESTJSONErrorCodes.UnknownGuild:
+      return `no server ${named.guildId} is visible to this bot. discord--list_guilds shows the servers it is in, with their ids.`;
+    case RESTJSONErrorCodes.UnknownMessage:
+      return `channel ${named.channelId} has no message ${named.messageId} that this bot can see. discord--fetch_history with that channelId shows its recent messages and their ids.`;
+    case RESTJSONErrorCodes.UnknownUser:
+      return `Discord knows no user ${named.userId}. The id may be mistyped or remembered rather than copied; discord--fetch_history of a channel they wrote in shows its messages' authors' ids.`;
+    case RESTJSONErrorCodes.UnknownEmoji:
+      return unknownEmoji(named);
+    case RESTJSONErrorCodes.MissingAccess:
+      return `this bot can't see ${target(named)} (Discord answered "Missing Access"), and calling again won't change that. `
+        + 'Ask whoever runs this host to give it access.';
+    case RESTJSONErrorCodes.MissingPermissions:
+      return `this bot isn't allowed to do that${named.channelId !== undefined || named.guildId !== undefined ? ` in ${target(named)}` : ''} (Discord answered "Missing Permissions"), and calling again won't change that. `
+        + 'Ask whoever runs this host to grant the permission.';
+    case RESTJSONErrorCodes.CannotEditMessageAuthoredByAnotherUser:
+      return `message ${named.messageId} was written by someone else, and this bot can edit only its own messages.`;
+    case RESTJSONErrorCodes.CannotSendMessagesToThisUser:
+      return `Discord won't deliver a direct message from this bot ${named.userId !== undefined ? `to user ${named.userId}` : `in channel ${named.channelId}`}, usually because they share no server or don't accept direct messages, and calling again won't change that.`;
+    default:
+      return `Discord refused the request: ${error.message}`;
+  }
+}
+
+/** Discord starts a thread from a message only in a server's text or announcement channel; a forum's or media channel's threads are its posts. */
+function cantHoldThreads(named: Named): string {
+  return `${target(named)} can't hold threads. A message can start one only in a server's text or announcement channel.`;
+}
+
+/** A message that has a thread: discord.js finds a message's thread by the message's own id (Message#thread). */
+function existingThread(named: Named): string {
+  return `message ${named.messageId} already has a thread, whose id is the message's own: discord--send with channelId ${named.messageId} posts in it.`;
+}
+
+function unknownEmoji(named: Named): string {
+  return `Discord doesn't know the emoji ${JSON.stringify(named.emoji)}. Use a Unicode emoji, such as "👍", or a custom one as name:id from a server this bot is in.`;
+}
+
+/**
+ * discord.js's own refusal of a call, before it sends any request: a message
+ * whose channel can't hold threads, one that already has a thread, or an
+ * emoji it can't read. Any other error has no words here.
+ */
+function localRefusalReason(error: unknown, named: Named): string | undefined {
+  if (!(error instanceof DiscordjsError) && !(error instanceof DiscordjsTypeError)) return undefined;
+  switch ((error as { code?: unknown }).code) {
+    case DiscordjsErrorCodes.MessageThreadParent:
+      return cantHoldThreads(named);
+    case DiscordjsErrorCodes.MessageExistingThread:
+      return existingThread(named);
+    case DiscordjsErrorCodes.EmojiType:
+      return `this bot can't read ${JSON.stringify(named.emoji)} as an emoji, so Discord wasn't asked. Use a Unicode emoji, such as "👍", or a custom one as name:id from a server this bot is in.`;
+    default:
+      return undefined;
+  }
+}
 
 export interface DiscordJsClientConfig {
   token: string;
@@ -47,7 +140,7 @@ export class DiscordJsClient implements DiscordClientInterface {
   private channelIds?: string[];
 
   private messageHandler?: (message: DiscordMessageData) => void;
-  private editHandler?: (messageId: string, newContent: string) => void;
+  private editHandler?: (messageId: string, newContent: string, attachments?: DiscordAttachment[]) => void;
   private deleteHandler?: (messageId: string) => void;
   private readyHandler?: () => void;
 
@@ -78,13 +171,18 @@ export class DiscordJsClient implements DiscordClientInterface {
       }
     });
 
-    this.client.on('messageUpdate', (_oldMessage, newMessage) => {
+    this.client.on('messageUpdate', (oldMessage, newMessage) => {
       // 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);
+      // Its attachments as the edit left them, for a message discord.js had
+      // cached: it takes the update's list when the update carries one and
+      // keeps the cached list when it doesn't. A message it hadn't cached
+      // starts with an empty list, so one whose update carried none would read
+      // as having none; it passes none, and the row's blocks stay.
+      this.editHandler(newMessage.id, newMessage.content, oldMessage.partial ? undefined : newMessage.attachments?.map(toAttachment));
     });
 
     this.client.on('messageDelete', (message) => {
@@ -169,35 +267,69 @@ export class DiscordJsClient implements DiscordClientInterface {
     channelId: string,
     content: string,
     options?: { replyTo?: string; createThread?: { name: 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`);
-    }
-
-    const textChannel = channel as TextChannel | DMChannel;
-    const message = await textChannel.send({
-      content,
-      reply: options?.replyTo ? { messageReference: options.replyTo } : undefined,
+  ): Promise<{ messageId: string; threadFailure?: string; note?: string }> {
+    const lead = 'Nothing was sent';
+    const { textChannel, message } = await this.asked(lead, { channelId }, async () => {
+      const textChannel = await this.lookup(lead, `channel ${channelId}`, () => this.messageChannel(channelId, lead, 'send')) as TextChannel | DMChannel;
+      const message = await textChannel.send({
+        content,
+        reply: options?.replyTo ? { messageReference: options.replyTo } : undefined,
+      });
+      return { textChannel, message };
     });
 
-    if (options?.createThread && 'threads' in textChannel) {
-      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) };
-      }
+    if (!options?.createThread) return { messageId: message.id };
+    // A channel without threads, such as a DM, gets none, and the send
+    // succeeds, as it did; its note says so.
+    if (!('threads' in textChannel)) {
+      return { messageId: message.id, note: `No thread was started: ${cantHoldThreads({ channelId })}` };
     }
+    const threadFailure = await this.threadAfterSend(message, channelId, options.createThread.name);
+    return threadFailure === undefined ? { messageId: message.id } : { messageId: message.id, threadFailure };
+  }
 
-    return { messageId: message.id };
+  /**
+   * Starts the thread a send asked for. The message is out by then, so when
+   * the thread isn't started, why is returned rather than thrown, in words
+   * that say the message was sent, lest the agent send it again.
+   */
+  private async threadAfterSend(message: Message, channelId: string, name: string): Promise<string | undefined> {
+    const sent = `The message was sent (id ${message.id}), so don't send it again`;
+    const named = { channelId, messageId: message.id };
+    const startOne = `discord--create_thread with channelId ${channelId}, messageId ${message.id} and a name`;
+    try {
+      await message.startThread({ name });
+      return undefined;
+    } catch (error) {
+      if (error instanceof 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}.`;
+        // 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.`;
+      }
+      // The thread refusals localRefusalReason words, a message outside a
+      // text or announcement channel and one that has a thread, can't come
+      // for a message just sent in a channel that holds threads.
+      return `${sent}, but starting its thread stopped on an unexpected error: ${error instanceof Error ? error.message : String(error)}. ` +
+        `Whether the thread exists is unknown: discord--fetch_history with channelId ${message.id} reads the thread if it exists and is refused if it doesn't, and then ${startOne} starts one.`;
+    }
   }
 
-  async sendDM(userId: string, content: string): Promise<{ messageId: string }> {
-    const user = await this.client.users.fetch(userId);
-    const message = await user.send(content);
-    return { messageId: message.id };
+  async sendDM(userId: string, content: string): Promise<{ messageId: string; channelId: string }> {
+    const lead = 'Nothing was sent';
+    return this.asked(lead, { userId }, async () => {
+      const user = await this.lookup(lead, `user ${userId}`, () => this.client.users.fetch(userId));
+      // User#send opens the direct message channel first, which sends nothing.
+      const channel = await this.lookup(lead, `the direct message channel with user ${userId}`, () => user.createDM());
+      const message = await channel.send(content);
+      return { messageId: message.id, channelId: message.channelId };
+    });
   }
 
   async fetchMessage(channelId: string, messageId: string): Promise<string> {
@@ -210,30 +342,36 @@ export class DiscordJsClient implements DiscordClientInterface {
   }
 
   async editMessage(channelId: string, messageId: string, content: string): Promise<void> {
-    const channel = await this.client.channels.fetch(channelId);
-    if (!channel || !('messages' in channel)) {
-      throw new Error(`Channel ${channelId} not found`);
-    }
-    const message = await (channel as TextChannel).messages.fetch(messageId);
-    await message.edit(content);
+    const lead = 'Nothing was edited';
+    await this.asked(lead, { channelId, messageId }, async () => {
+      const message = await this.findMessage(channelId, messageId, lead);
+      await message.edit(content);
+    });
   }
 
   async deleteMessage(channelId: string, messageId: string): Promise<void> {
-    const channel = await this.client.channels.fetch(channelId);
-    if (!channel || !('messages' in channel)) {
-      throw new Error(`Channel ${channelId} not found`);
+    const lead = 'Nothing was deleted';
+    try {
+      await this.asked(lead, { channelId, messageId }, async () => {
+        const message = await this.findMessage(channelId, messageId, lead);
+        await message.delete();
+      });
+    } 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) {
+        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;
     }
-    const message = await (channel as TextChannel).messages.fetch(messageId);
-    await message.delete();
   }
 
   async addReaction(channelId: string, messageId: string, emoji: string): Promise<void> {
-    const channel = await this.client.channels.fetch(channelId);
-    if (!channel || !('messages' in channel)) {
-      throw new Error(`Channel ${channelId} not found`);
-    }
-    const message = await (channel as TextChannel).messages.fetch(messageId);
-    await message.react(emoji);
+    const lead = 'No reaction was added';
+    await this.asked(lead, { channelId, messageId, emoji }, async () => {
+      const message = await this.findMessage(channelId, messageId, lead);
+      await message.react(emoji);
+    });
   }
 
   async createThread(
@@ -242,23 +380,108 @@ export class DiscordJsClient implements DiscordClientInterface {
     name: string,
     autoArchiveDuration?: number
   ): Promise<{ threadId: string }> {
+    const lead = 'No thread was started';
+    try {
+      return await this.asked(lead, { channelId, messageId }, async () => {
+        const message = await this.findMessage(channelId, messageId, lead);
+        const thread = await message.startThread({
+          name,
+          autoArchiveDuration: (autoArchiveDuration as 60 | 1440 | 4320 | 10080) ?? 1440,
+        });
+        return { threadId: thread.id };
+      });
+    } 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) {
+        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;
+    }
+  }
+
+  /**
+   * The message a tool acts on, looked up in its channel. An empty id is
+   * refused before any request: discord.js fetches a channel's recent
+   * messages for one, not a message.
+   */
+  private findMessage(channelId: string, messageId: string, lead: string): Promise<Message> {
+    if (!messageId) {
+      return Promise.reject(new DiscordRefusal(`${lead}: the call gave no message id. discord--fetch_history with channelId ${channelId} shows its recent messages and their ids.`));
+    }
+    return this.lookup(lead, `message ${messageId} in channel ${channelId}`,
+      async () => (await this.messageChannel(channelId, lead, 'messages')).messages.fetch(messageId));
+  }
+
+  /**
+   * Runs a lookup a tool makes before its change. A lookup sends, edits and
+   * removes nothing, so one that stops on an unexpected error, such as a
+   * network failure, means the tool did nothing, which a refusal led by
+   * `lead` says, and calling it again is safe: opening a direct message
+   * channel, the one lookup that can make something on Discord, opens the
+   * same channel again. Discord refusing it, or a refusal of this module's
+   * own, passes on as it is; anything else, discord.js's own errors
+   * included, is the unexpected stop.
+   */
+  private async lookup<T>(lead: string, what: string, run: () => Promise<T>): Promise<T> {
+    try {
+      return await run();
+    } catch (error) {
+      if (error instanceof 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 });
+    }
+  }
+
+  /**
+   * Runs one tool's requests. Discord refusing any of them, which discord.js
+   * reports as a DiscordAPIError, becomes a DiscordRefusal led by `lead`, with
+   * Discord's error as its cause: a tool's change is its last request, so it
+   * wasn't made. So does discord.js refusing a call before it sends one
+   * (localRefusalReason). Anything else passes through as an unexpected error.
+   */
+  private async asked<T>(lead: string, named: Named, run: () => Promise<T>): Promise<T> {
+    try {
+      return await run();
+    } catch (error) {
+      if (error instanceof 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;
+    }
+  }
+
+  /**
+   * The channel `channelId` names, when it holds messages (and, with 'send',
+   * takes them). A channel Discord knows but that holds none, such as a
+   * category, is refused with what it is.
+   */
+  private async messageChannel(channelId: string, lead: string, need: 'messages' | 'send'): Promise<TextChannel> {
     const channel = await this.client.channels.fetch(channelId);
-    if (!channel || !('messages' in channel)) {
-      throw new Error(`Channel ${channelId} not found`);
+    if (!channel || !(need in channel)) {
+      throw new DiscordRefusal(`${lead}: ${this.holdsNoMessages(channelId, channel)}`);
     }
-    const message = await (channel as TextChannel).messages.fetch(messageId);
-    const thread = await message.startThread({
-      name,
-      autoArchiveDuration: (autoArchiveDuration as 60 | 1440 | 4320 | 10080) ?? 1440,
-    });
-    return { threadId: thread.id };
+    return channel as TextChannel;
+  }
+
+  private holdsNoMessages(channelId: string, channel: Channel | null): string {
+    if (!channel) {
+      return `this bot can't use channel ${channelId}: Discord answered for it, but it's a kind of channel this bot doesn't handle, or its server isn't loaded here, and calling again won't change that. Ask whoever runs this host if you need it.`;
+    }
+    const type = this.mapChannelType(channel.type);
+    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')
+      : 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.`;
   }
 
   onMessage(handler: (message: DiscordMessageData) => void): void {
     this.messageHandler = handler;
   }
 
-  onMessageEdit(handler: (messageId: string, newContent: string) => void): void {
+  onMessageEdit(handler: (messageId: string, newContent: string, attachments?: DiscordAttachment[]) => void): void {
     this.editHandler = handler;
   }
 
@@ -293,17 +516,12 @@ export class DiscordJsClient implements DiscordClientInterface {
   }
 
   async listChannels(guildId: string): Promise<DiscordChannel[]> {
-    const guild = await this.client.guilds.fetch(guildId);
-    if (!guild) {
-      throw new Error(`Guild ${guildId} not found`);
-    }
-
-    // guild.channels might be undefined if the guild was fetched without full data
-    if (!guild.channels) {
-      throw new Error(`Guild ${guildId} channels not available - may need to re-fetch with force`);
-    }
-
-    const channels = await guild.channels.fetch();
+    // An unknown or unreachable server is Discord's refusal (fetch throws);
+    // a fetched Guild always carries its channel manager.
+    const channels = await this.asked('Nothing was listed', { guildId }, async () => {
+      const guild = await this.client.guilds.fetch(guildId);
+      return guild.channels.fetch();
+    });
     const result: DiscordChannel[] = [];
     
     channels.forEach((c: GuildBasedChannel | null) => {
@@ -339,15 +557,13 @@ export class DiscordJsClient implements DiscordClientInterface {
     channelId: string,
     options?: { limit?: number; before?: string }
   ): Promise<HistoryMessage[]> {
-    const channel = await this.client.channels.fetch(channelId);
-    if (!channel || !('messages' in channel)) {
-      throw new Error(`Channel ${channelId} not found or not a text channel`);
-    }
-
-    const textChannel = channel as TextChannel;
-    const messages = await textChannel.messages.fetch({
-      limit: options?.limit ?? 50,
-      before: options?.before,
+    const lead = 'No history was read';
+    const messages = await this.asked(lead, { channelId, messageId: options?.before }, async () => {
+      const textChannel = await this.messageChannel(channelId, lead, 'messages');
+      return textChannel.messages.fetch({
+        limit: options?.limit ?? 50,
+        before: options?.before,
+      });
     });
 
     return messages.map((m: Message) => ({