@animalabs/agent-framework 0.22.3 → 0.23.0

package/dist/src/modules/discord/index.js

@@ -8,8 +8,11 @@
  */
 import { formatZonedDateTime, resolveTimeZone } from '../../timezone.js';
 import { logValue } from '../../mcpl/log-value.js';
+import { unknownToolMessage } from '../unknown-tool.js';
+import { DiscordRefusal } from './refusal.js';
 export * from './types.js';
 export { DiscordJsClient } from './discord-js-client.js';
+export { DiscordRefusal } from './refusal.js';
 const DEFAULT_CONFIG = {
     handleDMs: true,
     ignoreBots: true,
@@ -56,10 +59,52 @@ const TEXT_FILE_EXTENSIONS = [
     '.html', '.css', '.xml', '.csv', '.log', '.sh', '.bash',
 ];
 const CONVERSATION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/** A text attachment this many bytes or larger isn't read into the agent's context. */
+const TEXT_FILE_LIMIT_BYTES = 100_000;
+/** activate's and deactivate's answer before the module has started, or once it has stopped. */
+const NOT_RUNNING = "Speech handling wasn't changed: the Discord module hasn't started on this host, or has stopped. Calling it again won't change that until it runs; ask whoever runs this host if you need Discord.";
 /** What the agent reads for a text attachment whose contents couldn't be
  *  fetched: by an error, or by an answer that wasn't OK. */
 function attachmentNotFetched(filename) {
-    return { type: 'text', text: `[Attachment: ${filename} (failed to fetch)]` };
+    return {
+        type: 'text',
+        text: `[Attachment: ${filename} couldn't be fetched, so its text isn't in your context. If you need it, ask the sender in the channel to paste it.]`,
+    };
+}
+/**
+ * What the agent reads when a tool stops on an error that isn't a refusal
+ * (DiscordRefusal), such as a network failure: its outcome is unknown. A send
+ * repeated blindly can post twice, so those say how to check; the other tools
+ * are safe to repeat, since a second call changes nothing more.
+ */
+function unexpectedFailure(call, error) {
+    const stopped = `discord--${call.name} stopped on an unexpected error: ${errorText(error)}.`;
+    const channelId = call.input?.channelId;
+    switch (call.name) {
+        case 'send':
+            return `${stopped} Whether the message was sent is unknown: discord--fetch_history with channelId ${String(channelId)} shows it, so check before you send it again.`;
+        case 'dm':
+            return `${stopped} Whether the message was sent is unknown. If an earlier discord--dm to this user gave you its channelId, discord--fetch_history with it shows whether this one went; without it, sending it again may send it twice.`;
+        case 'edit':
+        case 'react':
+        case 'delete':
+        case 'create_thread':
+            return `${stopped} Whether it took effect is unknown. Calling it again is safe: if it did, the second call changes nothing more.`;
+        case 'list_guilds':
+        case 'list_channels':
+        case 'fetch_history':
+            return `${stopped} It changes nothing on Discord, so you can call it again.`;
+        default:
+            return `${stopped} Calling it again is safe.`;
+    }
+}
+/** An error's own words, for a sentence about it. */
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** A count of seconds, for the agent's eyes. */
+function seconds(n) {
+    return `${n} second${n === 1 ? '' : 's'}`;
 }
 /** What a stored message reads when it has no text of its own and nothing the
  *  host added, so the agent still sees that a message was there. */
@@ -172,6 +217,65 @@ function holdsNotFetched(content, message) {
     const notes = new Set((message.attachments ?? []).map((attachment) => attachmentNotFetched(attachment.filename).text));
     return content.slice(1).some((block) => block.type === 'text' && notes.has(block.text));
 }
+/** A URL without its query or fragment: Discord's CDN signs an attachment's
+ *  URL afresh in each payload, so only its path names the attachment. */
+function urlPath(url) {
+    return url.split(/[?#]/)[0] ?? url;
+}
+/**
+ * Whether a block the host added for an attachment stands for none of
+ * `attachments`, matched as the live conversion writes it: an image by its
+ * URL, a file's text by its header, and a note by the filename it opens
+ * with, as every note for an attachment does, whatever its words after it.
+ * A block that stands for no attachment, such as EMPTY_MESSAGE, never does.
+ */
+function forGoneAttachment(block, attachments) {
+    if (block.type === 'image') {
+        const source = block.source;
+        if (source?.type !== 'url' || typeof source.url !== 'string')
+            return false;
+        const path = urlPath(source.url);
+        return !attachments.some((attachment) => urlPath(attachment.url) === path);
+    }
+    if (block.type !== 'text')
+        return false;
+    const { text } = block;
+    const opening = text.startsWith('\n--- File: ') ? (filename) => `\n--- File: ${filename} ---\n`
+        : text.startsWith('[Attachment: ') ? (filename) => `[Attachment: ${filename} `
+            : null;
+    return opening !== null && !attachments.some((attachment) => text.startsWith(opening(attachment.filename)));
+}
+/**
+ * A text-first row's content without the blocks the host added for
+ * attachments its message no longer has, or `content` itself when none is
+ * gone. A block stays while an attachment it may stand for remains, so of two
+ * files of one name, removing one keeps both blocks, and a block that names
+ * no attachment stays. EMPTY_MESSAGE comes back once nothing is left.
+ */
+function withoutGoneAttachments(content, attachments) {
+    const [first, ...rest] = content;
+    if (first?.type !== 'text')
+        return content;
+    const kept = rest.filter((block) => !forGoneAttachment(block, attachments));
+    if (kept.length === rest.length)
+        return content;
+    return textFirst(first.text, kept);
+}
+/** The ids to remove for a message's rows: each row once, and a body stored
+ *  in shards once, since removing one shard takes out its whole body. */
+function oncePerBody(rows) {
+    const bodies = new Set();
+    const ids = [];
+    for (const row of rows) {
+        if (row.bodyGroupId) {
+            if (bodies.has(row.bodyGroupId))
+                continue;
+            bodies.add(row.bodyGroupId);
+        }
+        ids.push(row.id);
+    }
+    return ids;
+}
 /**
  * Discord module for the agent framework.
  */
@@ -207,6 +311,21 @@ export class DiscordModule {
     // live path saw is newer than what the sync fetched, so the sync leaves
     // those messages alone.
     liveDuringSync = new Set();
+    // The Discord messages whose live create is on its way to the store: from
+    // the moment the live path takes one up, through its conversion and the
+    // event queue, until a query shows the row onProcess answered with, stored
+    // or held. The framework holds a module's writes while the agent's turn is
+    // alive or the host is quiesced, and queryMessages shows a held write's
+    // row, marked held, so the next Discord event finds it either way and ends
+    // its entry. A history sync stores none of these messages, so no message is
+    // stored twice. A delete before the create is handled drops it: nothing is
+    // stored and nobody is woken. Any message's entry ends when its delete is
+    // handled, since a sync running then skips the message (noteLive) and a
+    // later one doesn't fetch it. An edit while it converts is folded into it.
+    // A create whose answer the framework fails to write or hold shows no row,
+    // and keeps its entry, and the sync off its message, until its delete is
+    // handled or the module stops.
+    creating = new Map();
     // Typing keepalive: agentName -> { interval, deadline }. Started on
     // inference:started, stopped on the turn's terminal trace event. Discord's
     // typing indicator auto-expires after ~10s, so we re-trigger on an interval
@@ -249,7 +368,7 @@ export class DiscordModule {
         }
         // Set up Discord event handlers
         this.client.onMessage((message) => this.handleDiscordMessage(message));
-        this.client.onMessageEdit((id, content) => this.handleDiscordMessageEdit(id, content));
+        this.client.onMessageEdit((id, content, attachments) => this.handleDiscordMessageEdit(id, content, attachments));
         this.client.onMessageDelete((id) => this.handleDiscordMessageDelete(id));
         // Set up ready handler for history sync on (re)connect
         if (this.client.onReady) {
@@ -283,8 +402,13 @@ export class DiscordModule {
             clearInterval(interval);
         }
         this.typingLoops.clear();
-        await this.client.disconnect();
+        // From here the module writes nothing, though the framework may dispatch
+        // to it until stop() resolves: the live path takes nothing up, a create
+        // still converting finds the context gone, and onProcess answers nothing.
+        // The record of creates on their way goes with the context.
         this.ctx = null;
+        this.creating.clear();
+        await this.client.disconnect();
     }
     /**
      * Start (or refresh) the typing keepalive for an agent's reply channel.
@@ -468,7 +592,7 @@ export class DiscordModule {
             },
             {
                 name: 'list_channels',
-                description: 'List all channels in a Discord server',
+                description: 'List the channels in a Discord server, with their ids. Threads aren\'t listed.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -512,7 +636,8 @@ export class DiscordModule {
                 case 'set_reply_context':
                     return await this.handleSetReplyContext(call.input);
                 case 'activate':
-                    return await this.handleActivate(call.input);
+                    // A call with no input at all activates with the defaults.
+                    return await this.handleActivate((call.input ?? {}));
                 case 'deactivate':
                     return await this.handleDeactivate();
                 case 'list_guilds':
@@ -522,21 +647,38 @@ export class DiscordModule {
                 case 'fetch_history':
                     return await this.handleFetchHistory(call.input);
                 default:
-                    return { success: false, error: `Unknown tool: ${call.name}`, isError: true };
+                    return { success: false, error: unknownToolMessage(this.name, call.name, this.getTools()), isError: true };
             }
         }
         catch (error) {
+            // A refusal says what was refused and what to do instead; anything else
+            // is unexpected, and its outcome is worded by the tool.
             return {
                 success: false,
-                error: error instanceof Error ? error.message : String(error),
+                error: error instanceof DiscordRefusal ? error.message : unexpectedFailure(call, error),
                 isError: true,
             };
         }
     }
     async onProcess(event, state) {
+        // A stopped module answers nothing (stop()).
+        if (!this.ctx)
+            return {};
+        // Each Discord event ends the entries whose row a query shows now, stored
+        // or held.
+        if (event.type.startsWith('discord:')) {
+            for (const [id, live] of this.creating)
+                if (live.phase === 'writing' && this.storedRow(id))
+                    this.creating.delete(id);
+        }
         // Handle new Discord message
         if (event.type === 'discord:message') {
             const msg = event;
+            const live = this.creating.get(msg.discordMessageId);
+            // Deleted while its create waited in the queue: nothing is stored, and
+            // nobody is woken by a message its author took back.
+            if (live?.deleted)
+                return {};
             const currentState = state.getState() ?? {
                 connectedGuilds: [],
                 conversations: {},
@@ -579,20 +721,29 @@ export class DiscordModule {
             // when an event carries no blocks; text first, as TEXT_FIRST marks.
             const contentBlocks = msg.contentBlocks ?? textFirst(ownText(msg.content));
             this.noteLive(msg.discordMessageId);
+            // A message a history sync wrote first, stored or held, keeps that row:
+            // the create adds none, and still sets the reply context and asks for
+            // inference, since the message arrived live. Either way the entry waits
+            // until a Discord event finds the message's row.
+            const stored = this.storedRow(msg.discordMessageId);
+            if (live)
+                live.phase = 'writing';
             // Return declarative response - framework applies all writes atomically
             return {
-                addMessages: [
-                    {
-                        participant: msg.authorName,
-                        content: contentBlocks,
-                        metadata: {
-                            external: { source: 'discord', id: msg.discordMessageId },
-                            channelId: msg.channelId,
-                            timestamp: msg.timestamp,
-                            [TEXT_FIRST]: true,
+                ...(stored ? {} : {
+                    addMessages: [
+                        {
+                            participant: msg.authorName,
+                            content: contentBlocks,
+                            metadata: {
+                                external: { source: 'discord', id: msg.discordMessageId },
+                                channelId: msg.channelId,
+                                timestamp: msg.timestamp,
+                                [TEXT_FIRST]: true,
+                            },
                         },
-                    },
-                ],
+                    ],
+                }),
                 stateUpdate: newState,
                 requestInference: msg.shouldTriggerInference ?? true,
             };
@@ -600,15 +751,18 @@ export class DiscordModule {
         // Handle Discord message edit
         if (event.type === 'discord:edit') {
             const edit = event;
-            // The stored row, not only its id: an edit changes the message's own
-            // text and keeps what the host added beside it.
-            // An edit to a message nobody has stored yet is dropped: whatever
-            // stores the message, its live add or a history sync running now,
-            // stores the text it got, and the next sync's text rule changes it.
-            // A row stored in shards can't be edited one shard at a time, so it
-            // keeps its text, and the host's log says so. Only an edit that writes
-            // marks the message live, so an update that changes nothing leaves a
-            // running sync free to rewrite the row.
+            // The message's row, not only its id: an edit changes the message's own
+            // text and keeps what the host added beside it, but for the blocks of
+            // attachments the edit took away, when the client passed the edit's
+            // attachments and the row is text-first.
+            // An edit that comes while the live path converts the message's create
+            // is folded into that create (handleDiscordMessageEdit). Any other edit
+            // to a message with no row, stored or held, is dropped: a history sync
+            // running now stores the text it fetched, and the next sync's text rule
+            // changes it. A row stored in shards can't be edited one shard at a
+            // time, so it keeps its text, and the host's log says so. Only an edit
+            // that writes marks the message live, so an update that changes nothing
+            // leaves a running sync free to rewrite the row.
             const stored = this.storedRow(edit.discordMessageId);
             if (!stored)
                 return {};
@@ -616,8 +770,11 @@ export class DiscordModule {
                 console.warn(`Discord: An update to message ${edit.discordMessageId} wasn't applied: it's stored in shards, which can't be edited, so if its text changed, the agent still has the earlier text`);
                 return {};
             }
-            const content = contentForText(stored, edit.newContent);
-            if (!content)
+            const texted = contentForText(stored, edit.newContent);
+            const content = edit.attachments && stored.metadata?.[TEXT_FIRST] === true
+                ? withoutGoneAttachments(texted ?? stored.content, edit.attachments)
+                : texted;
+            if (!content || content === stored.content)
                 return {};
             this.noteLive(edit.discordMessageId);
             return { editMessages: [{ messageId: stored.id, content }] };
@@ -625,17 +782,19 @@ export class DiscordModule {
         // Handle Discord message delete
         if (event.type === 'discord:delete') {
             const del = event;
-            // A row stored in shards is removed whole: the framework takes out the
-            // body a shard belongs to. The message is the live path's even when no
-            // row is found, so a running sync doesn't store what its fetch may
-            // still hold.
+            // Every row of the message goes, so one stored twice doesn't outlive
+            // its delete as a copy. A row stored in shards is removed whole: the
+            // framework takes out the body a shard belongs to. The message is the
+            // live path's even when no row is found, so a running sync doesn't
+            // store what its fetch may still hold, and that ends its entry.
             this.noteLive(del.discordMessageId);
-            const stored = this.storedRow(del.discordMessageId);
-            if (!stored) {
+            this.creating.delete(del.discordMessageId);
+            const rows = this.storedRows(del.discordMessageId);
+            if (rows.length === 0) {
                 return {};
             }
             return {
-                removeMessages: [stored.id],
+                removeMessages: oncePerBody(rows),
             };
         }
         return {};
@@ -679,7 +838,7 @@ export class DiscordModule {
             return;
         }
         // Check rate limit
-        if (!this.checkRateLimit(replyCtx.channelId)) {
+        if (this.rateLimitWait(replyCtx.channelId) > 0) {
             console.warn(`Discord: Rate limited for channel ${replyCtx.channelId}`);
             return;
         }
@@ -770,7 +929,8 @@ export class DiscordModule {
     }
     /**
      * Sync history for a specific channel - compare with Context Manager and update.
-     * Uses queryMessages() to enumerate stored messages for proper edit/delete detection.
+     * Uses queryMessages() to enumerate the channel's rows, a held write's among
+     * them, for proper edit/delete detection.
      *
      * The live path can store, edit or remove a row whenever the sync awaits.
      * So the sync fetches history and runs the live conversion it needs first,
@@ -813,7 +973,7 @@ export class DiscordModule {
             // edited one shard at a time, so it's left as it is.
             const converted = new Map();
             for (const discordMsg of chronologicalMessages) {
-                const stored = before.get(discordMsg.id);
+                const stored = before.get(discordMsg.id)?.[0];
                 if (stored && (stored.bodyGroupId || !needsRebuild(stored, discordMsg)))
                     continue;
                 const content = await this.convertMessageToContent(discordMsg);
@@ -834,13 +994,14 @@ export class DiscordModule {
             for (const discordMsg of chronologicalMessages) {
                 if (live.has(discordMsg.id))
                     continue;
-                const stored = storedMessageMap.get(discordMsg.id);
+                const stored = storedMessageMap.get(discordMsg.id)?.[0];
                 if (!stored) {
                     // A message we haven't stored. One that was stored when the sync
                     // began, and isn't now, was removed meanwhile: not the sync's to
-                    // bring back.
+                    // bring back. One the live path is storing (creating) is the live
+                    // path's, so it isn't stored twice.
                     const content = converted.get(discordMsg.id);
-                    if (!content || before.has(discordMsg.id))
+                    if (!content || before.has(discordMsg.id) || this.creating.has(discordMsg.id))
                         continue;
                     // For bot's own messages (from previous sessions), use the agent name
                     // This ensures continuity of conversation history
@@ -876,7 +1037,8 @@ export class DiscordModule {
             const oldestFetchedTimestamp = discordMessages.length > 0
                 ? Math.min(...discordMessages.map((msg) => msg.timestamp.getTime()))
                 : undefined;
-            for (const [externalId, stored] of storedMessageMap) {
+            for (const [externalId, rows] of storedMessageMap) {
+                const stored = rows[0];
                 const sourceTimestamp = typeof stored.metadata?.timestamp === 'number'
                     ? stored.metadata.timestamp
                     : undefined;
@@ -890,8 +1052,10 @@ export class DiscordModule {
                     // Message exists in our store but not in Discord - it was deleted
                     // Note: This only catches deletes within the scrollback window.
                     // A message the live path wrote while the sync ran is newer than
-                    // the fetch, so it stays. One shard's id takes out a body whole.
-                    ctx.removeMessage(stored.id);
+                    // the fetch, so it stays. Every row of the message goes, and one
+                    // shard's id takes out a body whole.
+                    for (const id of oncePerBody(rows))
+                        ctx.removeMessage(id);
                     deletedMessages++;
                 }
             }
@@ -908,22 +1072,38 @@ export class DiscordModule {
         }
     }
     /** A channel's stored Discord rows by their Discord message id, whole: an
-     *  edit replaces a row's own text and keeps what the host added beside it. */
+     *  edit replaces a row's own text and keeps what the host added beside it.
+     *  Each id's rows are in store order. A message stored twice holds two,
+     *  of which a sync acts on the first, as the live path does (storedRow),
+     *  and a delete takes both. A write the framework holds is a row too
+     *  (storedRows). */
     storedByDiscordId(ctx, channelId) {
         const rows = new Map();
         for (const msg of ctx.queryMessages({ source: 'discord', metadata: { channelId } }).messages) {
             const external = msg.metadata?.external;
-            if (external?.id)
-                rows.set(external.id, msg);
+            if (!external?.id)
+                continue;
+            const held = rows.get(external.id);
+            if (held)
+                held.push(msg);
+            else
+                rows.set(external.id, [msg]);
         }
         return rows;
     }
-    /** The stored row of a Discord message, by its id in the row's metadata.
-     *  The module context's findMessageByExternalId holds only rows the module
+    /** The stored rows of a Discord message, by its id in the row's metadata,
+     *  in store order. A write the framework holds comes after them as a held
+     *  row, which an edit or removal reaches as it does a stored one. The
+     *  module context's findMessageByExternalId holds only rows the module
      *  stored through its context, not those a process response added, so it
      *  misses what the live path stored. */
+    storedRows(discordMessageId) {
+        return this.ctx?.queryMessages({ source: 'discord', externalIds: [discordMessageId] }).messages ?? [];
+    }
+    /** The row an edit or a create acts on: a message's first row, a stored
+     *  one before a held one (storedRows). */
     storedRow(discordMessageId) {
-        return this.ctx?.queryMessages({ source: 'discord', externalIds: [discordMessageId] }).messages[0];
+        return this.storedRows(discordMessageId)[0];
     }
     /** Marks a Discord message as the live path's for every history sync running now. */
     noteLive(discordMessageId) {
@@ -931,7 +1111,8 @@ export class DiscordModule {
             live.add(discordMessageId);
     }
     async handleDiscordMessage(message) {
-        if (!this.ctx)
+        const ctx = this.ctx;
+        if (!ctx)
             return;
         // ALWAYS ignore our own messages to prevent feedback loops
         if (this.state.botUserId && message.authorId === this.state.botUserId) {
@@ -958,20 +1139,52 @@ export class DiscordModule {
         }
         // Determine if this message should trigger inference
         const shouldTrigger = this.shouldTriggerInference(message, isDM);
+        // From here the message is the live path's to store (creating). A second
+        // delivery of a message whose create is already on its way is ignored.
+        if (this.creating.has(message.id))
+            return;
+        const live = { phase: 'converting', deleted: false };
+        this.creating.set(message.id, live);
+        const drop = () => { if (this.creating.get(message.id) === live)
+            this.creating.delete(message.id); };
         // Convert message content including attachments
-        const contentBlocks = await this.convertMessageToContent(message);
+        let contentBlocks;
+        try {
+            contentBlocks = await this.convertMessageToContent(message);
+        }
+        catch (error) {
+            drop();
+            throw error;
+        }
+        // A module stopped or started again meanwhile writes nothing.
+        if (this.ctx !== ctx) {
+            drop();
+            return;
+        }
+        // A delete that came meanwhile drops the create: nothing is stored,
+        // nobody is woken. Its entry stays until that delete is handled, so no
+        // sync stores the message before then.
+        if (live.deleted)
+            return;
+        // An edit that came meanwhile: its text, and the blocks of the
+        // attachments it left.
+        if (live.text !== undefined)
+            contentBlocks = withOwnText(contentBlocks, live.text);
+        if (live.attachments)
+            contentBlocks = withoutGoneAttachments(contentBlocks, live.attachments);
+        live.phase = 'queued';
         // Only queue the event - all state writes happen in onProcess()
-        this.ctx.pushEvent({
+        ctx.pushEvent({
             type: 'discord:message',
             discordMessageId: message.id,
             channelId: message.channelId,
             guildId: message.guildId,
             authorId: message.authorId,
             authorName: message.authorName,
-            content: message.content,
+            content: live.text ?? message.content,
             contentBlocks,
             timestamp: message.timestamp.getTime(),
-            attachments: message.attachments,
+            attachments: live.attachments ?? message.attachments,
             shouldTriggerInference: shouldTrigger,
         });
     }
@@ -1000,7 +1213,15 @@ export class DiscordModule {
             }
             // Check for text files - fetch and include content
             const isTextFile = TEXT_FILE_EXTENSIONS.some(ext => filename.endsWith(ext));
-            if (isTextFile && attachment.size && attachment.size < 100_000) { // < 100KB
+            if (isTextFile && attachment.size >= TEXT_FILE_LIMIT_BYTES) {
+                blocks.push({
+                    type: 'text',
+                    text: `[Attachment: ${attachment.filename} (${attachment.size.toLocaleString('en-US')} bytes): this host reads text files under ${TEXT_FILE_LIMIT_BYTES.toLocaleString('en-US')} bytes into your context, so its text isn't here. If you need it, ask the sender to paste the part that matters.]`,
+                });
+                continue;
+            }
+            // A text file of size 0 gets the note below, as before.
+            if (isTextFile && attachment.size) {
                 try {
                     const response = await fetch(attachment.url);
                     if (response.ok) {
@@ -1026,7 +1247,7 @@ export class DiscordModule {
             // For unsupported attachments, add a note
             blocks.push({
                 type: 'text',
-                text: `[Attachment: ${attachment.filename} (${contentType || 'unknown type'})]`,
+                text: `[Attachment: ${attachment.filename} (${contentType || 'unknown type'}): this host didn't read its contents in, so they aren't in your context. If you need them, ask the sender for them in a form you can read, such as pasted text.]`,
             });
         }
         return textFirst(ownText(message.content), blocks);
@@ -1063,19 +1284,35 @@ export class DiscordModule {
                 return isMentioned || isReplyToBot;
         }
     }
-    handleDiscordMessageEdit(messageId, newContent) {
+    handleDiscordMessageEdit(messageId, newContent, attachments) {
         if (!this.ctx)
             return;
+        // An edit while the message's create converts is folded into that
+        // create, which would otherwise store the text it was sent with; one that
+        // comes after follows the create through the queue. Its event still goes,
+        // for a row a history sync stored first.
+        const live = this.creating.get(messageId);
+        if (live) {
+            live.text = newContent;
+            if (attachments)
+                live.attachments = attachments;
+        }
         // Only queue the event - state writes happen in onProcess()
         this.ctx.pushEvent({
             type: 'discord:edit',
             discordMessageId: messageId,
             newContent,
+            ...(attachments ? { attachments } : {}),
         });
     }
     handleDiscordMessageDelete(messageId) {
         if (!this.ctx)
             return;
+        // A delete before the message's create is handled drops that create.
+        // Its event still goes, for a row a history sync stored first.
+        const live = this.creating.get(messageId);
+        if (live)
+            live.deleted = true;
         // Only queue the event - state writes happen in onProcess()
         this.ctx.pushEvent({
             type: 'discord:delete',
@@ -1104,8 +1341,13 @@ export class DiscordModule {
         }
     }
     async handleSend(input, call) {
-        if (!this.checkRateLimit(input.channelId)) {
-            return { success: false, error: 'Rate limited', isError: true };
+        const wait = this.rateLimitWait(input.channelId);
+        if (wait > 0) {
+            return {
+                success: false,
+                error: `Nothing was sent: channel ${input.channelId} has reached ${this.rateLimitRule()}. Send it again in ${seconds(wait)}; other channels have their own limit.`,
+                isError: true,
+            };
         }
         const result = await this.client.sendMessage(input.channelId, input.content, {
             replyTo: input.replyTo,
@@ -1117,28 +1359,61 @@ export class DiscordModule {
         if (result.threadFailure !== undefined) {
             return { success: false, error: result.threadFailure, isError: true };
         }
-        return { success: true, data: { messageId: result.messageId } };
+        return { success: true, data: { messageId: result.messageId, ...(result.note !== undefined ? { note: result.note } : {}) } };
     }
     async handleDM(input) {
         const result = await this.client.sendDM(input.userId, input.content);
-        return { success: true, data: { messageId: result.messageId } };
+        // The direct message channel's id is what fetch_history reads it by, should a later dm need checking.
+        return { success: true, data: { messageId: result.messageId, ...(result.channelId !== undefined ? { channelId: result.channelId } : {}) } };
     }
     async handleReply(input, call) {
         const replyCtx = this.replyContexts.get('default');
         if (!replyCtx) {
-            return { success: false, error: 'No conversation context', isError: true };
+            return {
+                success: false,
+                error: 'Nothing was sent: there\'s no conversation to reply in. Use discord--send with a channelId to post somewhere, or discord--set_reply_context with a channelId to choose where replies go, then reply again.',
+                isError: true,
+            };
         }
-        if (!this.checkRateLimit(replyCtx.channelId)) {
-            return { success: false, error: 'Rate limited', isError: true };
+        // The reply goes to the context's thread when it names one, an empty id
+        // as well, as it always has; the words name an empty id as what it is.
+        const thread = replyCtx.threadId;
+        const wait = this.rateLimitWait(replyCtx.channelId);
+        if (wait > 0) {
+            return {
+                success: false,
+                error: `Nothing was sent: this conversation's channel (${replyCtx.channelId}) has reached ${this.rateLimitRule()}`
+                    + `${thread ? `, which counts its replies in thread ${thread} too` : ''}. Reply again in ${seconds(wait)}.`,
+                isError: true,
+            };
         }
         let content = input.content;
         if (input.mention && replyCtx.userId) {
             content = `<@${replyCtx.userId}> ${content}`;
         }
-        const targetChannel = replyCtx.threadId ?? replyCtx.channelId;
-        const result = await this.client.sendMessage(targetChannel, content, {
-            replyTo: replyCtx.replyToMessageId,
-        });
+        // reply's call names no channel or message: its reply context does, as it
+        // stands now, before the send, which an incoming message can change.
+        const targetChannel = thread ?? replyCtx.channelId;
+        const pointsAt = thread === undefined ? `channel ${targetChannel}` : thread === '' ? 'an empty thread id' : `thread ${targetChannel}`;
+        const check = thread === ''
+            ? `, and its reply context names an empty thread id: discord--set_reply_context with a threadId, or without one to reply in channel ${replyCtx.channelId}, puts that right`
+            : `: discord--fetch_history with channelId ${targetChannel}, its reply context's ${thread !== undefined ? 'thread' : 'channel'}, shows it, so check before you reply again`;
+        const replyTo = replyCtx.replyToMessageId;
+        let result;
+        try {
+            result = await this.client.sendMessage(targetChannel, content, { replyTo });
+        }
+        catch (error) {
+            if (error instanceof DiscordRefusal) {
+                throw new DiscordRefusal(`${error.message} A reply goes where its reply context points: ${pointsAt}`
+                    + `${replyTo ? `, answering message ${replyTo}` : ''}. discord--set_reply_context changes that.`, { cause: error });
+            }
+            return {
+                success: false,
+                error: `discord--reply stopped on an unexpected error: ${errorText(error)}. Whether the reply was sent is unknown${check}.`,
+                isError: true,
+            };
+        }
         // Track for thought-editing
         this.notePost(call.callerAgentName, call.callerTurnId, targetChannel, result.messageId);
         // Clear reply-to after sending
@@ -1188,14 +1463,14 @@ export class DiscordModule {
     }
     async handleActivate(input) {
         if (!this.ctx) {
-            return { success: false, error: 'Module not started', isError: true };
+            return { success: false, error: NOT_RUNNING, isError: true };
         }
         this.ctx.registerSpeechHandler('*', { additive: input.additive });
         return { success: true, data: { message: 'Discord is now handling speech' } };
     }
     async handleDeactivate() {
         if (!this.ctx) {
-            return { success: false, error: 'Module not started', isError: true };
+            return { success: false, error: NOT_RUNNING, isError: true };
         }
         this.ctx.unregisterSpeechHandler();
         return { success: true, data: { message: 'Discord is no longer handling speech' } };
@@ -1271,8 +1546,23 @@ export class DiscordModule {
             .map((block) => block.text)
             .join('\n');
     }
-    checkRateLimit(channelId) {
-        const limit = this.config.rateLimitPerMinute ?? 30;
+    rateLimitPerMinute() {
+        return this.config.rateLimitPerMinute ?? 30;
+    }
+    /** The limit, as the rate-limit refusals word it. */
+    rateLimitRule() {
+        const limit = this.rateLimitPerMinute();
+        return `this host's limit of ${limit} send${limit === 1 ? '' : 's'} a minute from the bot`;
+    }
+    /**
+     * Counts a send to `channelId` against its limit and returns 0, or, when
+     * the channel has had its sends for this window, returns the whole seconds
+     * until the window ends, at least 1. A window is the minute from the first
+     * send this lets through, and each send it lets through counts, whether or
+     * not Discord then takes it.
+     */
+    rateLimitWait(channelId) {
+        const limit = this.rateLimitPerMinute();
         const now = Date.now();
         const windowMs = 60 * 1000;
         let info = this.state.rateLimits[channelId];
@@ -1282,10 +1572,10 @@ export class DiscordModule {
             this.state.rateLimits[channelId] = info;
         }
         if (info.count >= limit) {
-            return false;
+            return Math.max(1, Math.ceil((info.windowStart + windowMs - now) / 1000));
         }
         info.count++;
-        return true;
+        return 0;
     }
     cleanupOldConversations() {
         const now = Date.now();