discoclaw 0.1.0

package/dist/discord/reaction-handler.js

@@ -0,0 +1,691 @@
+import { ensureGroupDir } from '../discord.js';
+import { isAllowlisted } from './allowlist.js';
+import { discordSessionKey } from './session-key.js';
+import { ensureIndexedDiscordChannelContext, resolveDiscordChannelContext } from './channel-context.js';
+import { parseDiscordActions, executeDiscordActions, discordActionsPromptSection, buildDisplayResultLines, buildAllResultLines } from './actions.js';
+import { hasQueryAction, QUERY_ACTION_TYPES } from './action-categories.js';
+import { tryResolveReactionPrompt } from './reaction-prompts.js';
+import { tryAbortAll } from './abort-registry.js';
+import { getActiveOrchestrator } from './forge-plan-registry.js';
+import { buildContextFiles, inlineContextFiles, buildDurableMemorySection, buildTaskThreadSection, loadWorkspacePaFiles, resolveEffectiveTools, buildPromptPreamble } from './prompt-common.js';
+import { editThenSendChunks, appendUnavailableActionTypesNotice } from './output-common.js';
+import { formatBoldLabel, thinkingLabel, selectStreamingOutput } from './output-utils.js';
+import { NO_MENTIONS } from './allowed-mentions.js';
+import { registerInFlightReply, isShuttingDown } from './inflight-replies.js';
+import { downloadMessageImages, resolveMediaType } from './image-download.js';
+import { downloadTextAttachments } from './file-download.js';
+import { mapRuntimeErrorToUserMessage } from './user-errors.js';
+import { globalMetrics } from '../observability/metrics.js';
+import { resolveModel } from '../runtime/model-tiers.js';
+export function reactionPromptText(mode) {
+    if (mode === 'add') {
+        return {
+            eventLine: (reactingUser, userId, emoji, channelLabel) => `${reactingUser} (ID: ${userId}) reacted with ${emoji} to a message in ${channelLabel}.`,
+            guidanceLine: 'Respond based on your identity and context. The reaction signals the user wants you to engage with this message. Your response will be posted as a reply.',
+        };
+    }
+    return {
+        eventLine: (reactingUser, userId, emoji, channelLabel) => `${reactingUser} (ID: ${userId}) removed their ${emoji} reaction from a message in ${channelLabel}.`,
+        guidanceLine: 'Respond based on your identity and context. The user removed a reaction, which may signal a change of intent or retraction. Your response will be posted as a reply.',
+    };
+}
+function createReactionHandler(mode, params, queue, statusRef) {
+    const promptText = reactionPromptText(mode);
+    const logPrefix = mode === 'add' ? 'reaction' : 'reaction-remove';
+    const receivedMetric = mode === 'add' ? 'discord.reaction.received' : 'discord.reaction_remove.received';
+    const handlerErrorMetric = mode === 'add' ? 'discord.reaction.handler_error' : 'discord.reaction_remove.handler_error';
+    const wrapperErrorMetric = mode === 'add' ? 'discord.reaction.handler_wrapper_error' : 'discord.reaction_remove.handler_wrapper_error';
+    const eventLabel = mode === 'add' ? 'messageReactionAdd' : 'messageReactionRemove';
+    return async (reaction, user) => {
+        try {
+            const metrics = params.metrics ?? globalMetrics;
+            metrics.increment(receivedMetric);
+            // 1. Self-reaction guard — prevent infinite loops from bot's own reactions.
+            if (user.id === reaction.message.client.user?.id)
+                return;
+            // 2. Fetch partials.
+            try {
+                if (reaction.partial)
+                    await reaction.fetch();
+            }
+            catch (err) {
+                params.log?.warn({ err }, `${logPrefix}:partial fetch failed (reaction)`);
+                return;
+            }
+            try {
+                if (reaction.message.partial)
+                    await reaction.message.fetch();
+            }
+            catch (err) {
+                params.log?.warn({ err }, `${logPrefix}:partial fetch failed (message)`);
+                return;
+            }
+            // 3. Guild-only — skip DM reactions.
+            if (reaction.message.guildId == null)
+                return;
+            // 4. Allowlist check.
+            if (!isAllowlisted(params.allowUserIds, user.id))
+                return;
+            // 5. Reaction prompt interception — if this reaction resolves a pending prompt, capture
+            // the result and continue into the normal AI invocation flow with prompt-specific text.
+            // IMPORTANT: This check intentionally precedes the staleness guard (step 6) so that
+            // reactionPrompt resolution works even when reactionMaxAgeMs is configured short.
+            // The allowlist check above ensures only authorized users can resolve pending prompts.
+            let resolvedPrompt = null;
+            if (mode === 'add') {
+                // For custom emojis, build the full <:name:id> identifier so it matches the choice
+                // strings stored in the pending prompt. Unicode emojis use name directly.
+                const emojiForPrompt = reaction.emoji.id
+                    ? `<:${reaction.emoji.name ?? ''}:${reaction.emoji.id}>`
+                    : (reaction.emoji.name ?? '');
+                if (emojiForPrompt) {
+                    resolvedPrompt = tryResolveReactionPrompt(reaction.message.id, emojiForPrompt);
+                }
+            }
+            // 4a. Abort intercept — 🛑 on a bot reply kills all active streams and any running forge.
+            // Placed after reaction prompt resolution (step 5) so pending prompts using 🛑 as a
+            // choice are resolved normally before this check. When resolvedPrompt is non-null, the
+            // entire block is skipped so the resolved choice flows through to AI invocation.
+            // On remove mode it silently consumes the event; on add mode with no resolved prompt
+            // it fires forge-aware cancellation and always consumes the event.
+            if (reaction.emoji.name === '🛑' &&
+                reaction.message.author?.id === reaction.message.client.user?.id &&
+                !resolvedPrompt) {
+                if (mode === 'remove')
+                    return;
+                // add mode: abort all active streams and cancel any running forge.
+                const abortedCount = tryAbortAll();
+                if (abortedCount > 0)
+                    metrics.increment('discord.reaction.abort');
+                const orch = getActiveOrchestrator();
+                if (orch?.isRunning)
+                    orch.requestCancel();
+                return;
+            }
+            // 6. Staleness guard — skipped when a pending prompt was resolved (the prompt message
+            // may be old but the user's choice is still valid).
+            if (!resolvedPrompt) {
+                const msgTimestamp = reaction.message.createdTimestamp;
+                if (msgTimestamp && params.reactionMaxAgeMs > 0) {
+                    const age = Date.now() - msgTimestamp;
+                    if (age > params.reactionMaxAgeMs)
+                        return;
+                }
+            }
+            // Resolve channel/thread info once, used by guards and the queue callback.
+            const ch = reaction.message.channel;
+            const isThread = typeof ch?.isThread === 'function' ? ch.isThread() : false;
+            const threadId = isThread ? String(ch.id ?? '') : null;
+            const threadParentId = isThread ? String(ch.parentId ?? '') : null;
+            // 7. Channel restriction.
+            if (params.allowChannelIds) {
+                const parentId = isThread ? String(ch.parentId ?? '') : '';
+                const allowed = params.allowChannelIds.has(reaction.message.channelId) ||
+                    (parentId && params.allowChannelIds.has(parentId));
+                if (!allowed)
+                    return;
+            }
+            // 8. Session key.
+            const sessionKey = discordSessionKey({
+                channelId: reaction.message.channelId,
+                authorId: user.id,
+                isDm: false,
+                threadId: threadId || null,
+            });
+            // 9. Queue.
+            await queue.run(sessionKey, async () => {
+                const msg = reaction.message;
+                let reply = null;
+                try {
+                    // Join thread if needed.
+                    if (params.autoJoinThreads && isThread) {
+                        const joinable = typeof ch?.joinable === 'boolean' ? ch.joinable : true;
+                        const joined = typeof ch?.joined === 'boolean' ? ch.joined : false;
+                        if (joinable && !joined && typeof ch?.join === 'function') {
+                            try {
+                                await ch.join();
+                                params.log?.info({ threadId: String(ch.id ?? ''), parentId: String(ch.parentId ?? '') }, `${logPrefix}:thread joined`);
+                            }
+                            catch (err) {
+                                params.log?.warn({ err, threadId: String(ch?.id ?? '') }, `${logPrefix}:thread failed to join`);
+                            }
+                        }
+                    }
+                    reply = await msg.reply({
+                        content: formatBoldLabel(thinkingLabel(0)),
+                        allowedMentions: NO_MENTIONS,
+                    });
+                    const cwd = params.useGroupDirCwd
+                        ? await ensureGroupDir(params.groupsDir, sessionKey, params.botDisplayName)
+                        : params.workspaceCwd;
+                    // Auto-index channel context.
+                    if (params.discordChannelContext && params.autoIndexChannelContext) {
+                        const id = (threadParentId && threadParentId.trim()) ? threadParentId : reaction.message.channelId;
+                        const chName = String(ch?.name ?? ch?.parent?.name ?? '').trim();
+                        try {
+                            await ensureIndexedDiscordChannelContext({
+                                ctx: params.discordChannelContext,
+                                channelId: id,
+                                channelName: chName || undefined,
+                                log: params.log,
+                            });
+                        }
+                        catch (err) {
+                            params.log?.error({ err, channelId: id }, `${logPrefix}:context failed to ensure channel context`);
+                        }
+                    }
+                    const channelCtx = resolveDiscordChannelContext({
+                        ctx: params.discordChannelContext,
+                        isDm: false,
+                        channelId: reaction.message.channelId,
+                        threadParentId,
+                    });
+                    if (params.requireChannelContext && !channelCtx.contextPath) {
+                        params.log?.warn({ channelId: channelCtx.channelId }, `${logPrefix}:missing required channel context`);
+                        await reply.edit({
+                            content: mapRuntimeErrorToUserMessage('Configuration error: missing required channel context file for this channel ID.'),
+                            allowedMentions: NO_MENTIONS,
+                        });
+                        return;
+                    }
+                    const paFiles = await loadWorkspacePaFiles(params.workspaceCwd, { skip: !!params.appendSystemPrompt });
+                    const contextFiles = buildContextFiles(paFiles, params.discordChannelContext, channelCtx.contextPath);
+                    const [durableSection, taskSection] = await Promise.all([
+                        buildDurableMemorySection({
+                            enabled: params.durableMemoryEnabled,
+                            durableDataDir: params.durableDataDir,
+                            userId: user.id,
+                            durableInjectMaxChars: params.durableInjectMaxChars,
+                            log: params.log,
+                        }),
+                        buildTaskThreadSection({
+                            isThread,
+                            threadId,
+                            threadParentId,
+                            taskCtx: params.taskCtx,
+                            log: params.log,
+                        }),
+                    ]);
+                    // Build prompt.
+                    const emoji = reaction.emoji.name ?? '(unknown)';
+                    const messageContent = String(msg.content ?? '').slice(0, 1500);
+                    const messageAuthor = msg.author?.displayName || msg.author?.username || 'Unknown';
+                    const messageAuthorId = msg.author?.id ?? 'unknown';
+                    const reactingUser = user.displayName || user.username || 'Unknown';
+                    // Channel label.
+                    let channelLabel;
+                    if (isThread) {
+                        const threadName = String(ch?.name ?? 'unknown');
+                        const parentName = String(ch?.parent?.name ?? 'unknown');
+                        channelLabel = `thread ${threadName} in #${parentName}`;
+                    }
+                    else {
+                        channelLabel = `#${channelCtx.channelName ?? 'unknown'}`;
+                    }
+                    const inlinedContext = await inlineContextFiles(contextFiles, { required: new Set(params.discordChannelContext?.paContextFiles ?? []) });
+                    const eventLine = resolvedPrompt
+                        ? `User chose ${resolvedPrompt.chosenEmoji} in response to: ${resolvedPrompt.question}`
+                        : promptText.eventLine(reactingUser, user.id, emoji, channelLabel);
+                    const guidanceLine = resolvedPrompt
+                        ? 'Act on the user\'s choice. Do not re-ask the question.'
+                        : promptText.guidanceLine;
+                    let prompt = buildPromptPreamble(inlinedContext) + '\n\n' +
+                        (taskSection
+                            ? `---\n${taskSection}\n\n`
+                            : '') +
+                        (durableSection
+                            ? `---\nDurable memory (user-specific notes):\n${durableSection}\n\n`
+                            : '') +
+                        `---\nThe sections above are internal system context. Never quote, reference, or explain them in your response. Respond only to the event below.\n\n` +
+                        `---\nReaction event:\n` +
+                        eventLine + `\n\n` +
+                        `Original message by ${messageAuthor} (ID: ${messageAuthorId}):\n` +
+                        messageContent;
+                    // Download image attachments and non-image text attachments.
+                    let inputImages;
+                    if (msg.attachments && msg.attachments.size > 0) {
+                        try {
+                            const dlResult = await downloadMessageImages([...msg.attachments.values()]);
+                            if (dlResult.images.length > 0) {
+                                inputImages = dlResult.images;
+                                params.log?.info({ imageCount: dlResult.images.length }, `${logPrefix}:images downloaded`);
+                            }
+                            if (dlResult.errors.length > 0) {
+                                params.log?.warn({ errors: dlResult.errors }, `${logPrefix}:image download errors`);
+                                metrics.increment('discord.image_download.errors', dlResult.errors.length);
+                                prompt += `\n(Note: ${dlResult.errors.length} image(s) could not be loaded: ${dlResult.errors.join('; ')})`;
+                            }
+                        }
+                        catch (err) {
+                            params.log?.warn({ err }, `${logPrefix}:image download failed`);
+                        }
+                        // Download non-image text attachments.
+                        try {
+                            const nonImageAtts = [...msg.attachments.values()].filter(a => !resolveMediaType(a));
+                            if (nonImageAtts.length > 0) {
+                                const textResult = await downloadTextAttachments(nonImageAtts);
+                                if (textResult.texts.length > 0) {
+                                    const sections = textResult.texts.map(t => `[Attached file: ${t.name}]\n\`\`\`\n${t.content}\n\`\`\``);
+                                    prompt += '\n\n' + sections.join('\n\n');
+                                    params.log?.info({ fileCount: textResult.texts.length }, `${logPrefix}:text attachments downloaded`);
+                                }
+                                if (textResult.errors.length > 0) {
+                                    prompt += '\n(' + textResult.errors.join('; ') + ')';
+                                    params.log?.info({ errors: textResult.errors }, `${logPrefix}:text attachment notes`);
+                                }
+                            }
+                        }
+                        catch (err) {
+                            params.log?.warn({ err }, `${logPrefix}:text attachment download failed`);
+                        }
+                    }
+                    // Embeds.
+                    if (msg.embeds && msg.embeds.length > 0) {
+                        const embedInfos = msg.embeds.map((e) => {
+                            const parts = [];
+                            if (e.title)
+                                parts.push(e.title);
+                            if (e.url)
+                                parts.push(e.url);
+                            return parts.join(' ') || '(embed)';
+                        });
+                        prompt += `\nEmbeds: ${embedInfos.join(', ')}`;
+                    }
+                    prompt += `\n\n${guidanceLine}`;
+                    const isDm = reaction.message.guildId == null;
+                    const actionFlags = {
+                        channels: params.discordActionsChannels,
+                        messaging: params.discordActionsMessaging,
+                        guild: params.discordActionsGuild,
+                        moderation: params.discordActionsModeration,
+                        polls: params.discordActionsPolls,
+                        tasks: params.discordActionsTasks ?? false,
+                        crons: params.discordActionsCrons ?? false,
+                        botProfile: params.discordActionsBotProfile ?? false,
+                        forge: params.discordActionsForge ?? false,
+                        plan: params.discordActionsPlan ?? false,
+                        memory: params.discordActionsMemory ?? false,
+                        config: params.discordActionsConfig ?? false,
+                        defer: !isDm && (params.discordActionsDefer ?? false),
+                    };
+                    if (params.discordActionsEnabled && !isDm) {
+                        prompt += '\n\n---\n' + discordActionsPromptSection(actionFlags, params.botDisplayName);
+                    }
+                    const addDirs = [];
+                    if (params.useGroupDirCwd)
+                        addDirs.push(params.workspaceCwd);
+                    if (params.discordChannelContext)
+                        addDirs.push(params.discordChannelContext.contentDir);
+                    const tools = await resolveEffectiveTools({
+                        workspaceCwd: params.workspaceCwd,
+                        runtimeTools: params.runtimeTools,
+                        runtimeCapabilities: params.runtime.capabilities,
+                        runtimeId: params.runtime.id,
+                        log: params.log,
+                    });
+                    const effectiveTools = tools.effectiveTools;
+                    if (tools.permissionNote || tools.runtimeCapabilityNote) {
+                        const noteLines = [
+                            tools.permissionNote ? `Permission note: ${tools.permissionNote}` : null,
+                            tools.runtimeCapabilityNote ? `Runtime capability note: ${tools.runtimeCapabilityNote}` : null,
+                        ].filter((line) => Boolean(line));
+                        prompt += `\n\n---\n${noteLines.join('\n')}\n`;
+                    }
+                    // Session continuity.
+                    const sessionId = params.useRuntimeSessions
+                        ? await params.sessionManager.getOrCreate(sessionKey)
+                        : null;
+                    params.log?.info({
+                        sessionKey,
+                        sessionId,
+                        cwd,
+                        emoji,
+                        userId: user.id,
+                        messageId: msg.id,
+                        model: params.runtimeModel,
+                        toolsCount: effectiveTools.length,
+                        channelId: channelCtx.channelId,
+                        channelName: channelCtx.channelName,
+                        hasChannelContext: Boolean(channelCtx.contextPath),
+                        permissionTier: tools.permissionTier,
+                    }, `${logPrefix}:invoke:start`);
+                    // Track this reply for graceful shutdown cleanup.
+                    let dispose = registerInFlightReply(reply, reaction.message.channelId, reply.id, `${logPrefix}:${reaction.message.channelId}`);
+                    // Tracks whether the reply was successfully replaced with real content (or deleted).
+                    // If false when the finally block runs, the reply still shows thinking-format content
+                    // and must be deleted to prevent a stale "Thinking..." message from persisting.
+                    let replyFinalized = false;
+                    let followUpDepth = 0;
+                    let currentPrompt = prompt;
+                    try {
+                        // -- auto-follow-up loop --
+                        while (true) {
+                            if (followUpDepth > 0) {
+                                dispose();
+                                reply = await msg.reply({
+                                    content: formatBoldLabel('(following up...)'),
+                                    allowedMentions: NO_MENTIONS,
+                                });
+                                dispose = registerInFlightReply(reply, reaction.message.channelId, reply.id, `${logPrefix}:${reaction.message.channelId}:followup-${followUpDepth}`);
+                                replyFinalized = false;
+                            }
+                            // Streaming pattern (matches discord.ts flat mode).
+                            // Both add and remove handlers record under the 'reaction' invoke flow so
+                            // latency lands in MetricsRegistry.latencies.reaction (avoids InvokeFlow
+                            // type change). Volume is split by the separate received/error counters.
+                            let hadTextFinal = false;
+                            let finalText = '';
+                            let deltaText = '';
+                            const collectedImages = [];
+                            let statusTick = 1;
+                            const t0 = Date.now();
+                            metrics.recordInvokeStart('reaction');
+                            params.log?.info({ flow: 'reaction', sessionKey }, 'obs.invoke.start');
+                            let invokeError = null;
+                            let lastEditAt = 0;
+                            const minEditIntervalMs = 1250;
+                            let streamEditQueue = Promise.resolve();
+                            const maybeEdit = async (force = false) => {
+                                if (!reply)
+                                    return;
+                                if (isShuttingDown())
+                                    return;
+                                const currentReply = reply;
+                                const now = Date.now();
+                                if (!force && now - lastEditAt < minEditIntervalMs)
+                                    return;
+                                lastEditAt = now;
+                                const out = selectStreamingOutput({
+                                    deltaText, activityLabel: '', finalText,
+                                    statusTick: statusTick++,
+                                    showPreview: Date.now() - t0 >= 7000,
+                                    elapsedMs: Date.now() - t0,
+                                });
+                                streamEditQueue = streamEditQueue
+                                    .catch(() => undefined)
+                                    .then(async () => {
+                                    try {
+                                        await currentReply.edit({ content: out, allowedMentions: NO_MENTIONS });
+                                    }
+                                    catch {
+                                        // Ignore Discord edit errors during streaming.
+                                    }
+                                });
+                                await streamEditQueue;
+                            };
+                            // Stream stall warning state.
+                            let lastEventAt = Date.now();
+                            let activeToolCount = 0;
+                            let stallWarned = false;
+                            const keepalive = setInterval(() => {
+                                // Stall warning: append to deltaText when events stop arriving.
+                                if (params.streamStallWarningMs > 0) {
+                                    const stallElapsed = Date.now() - lastEventAt;
+                                    if (stallElapsed > params.streamStallWarningMs && activeToolCount === 0 && !stallWarned) {
+                                        stallWarned = true;
+                                        deltaText += (deltaText ? '\n' : '') + `\n*Stream may be stalled (${Math.round(stallElapsed / 1000)}s no activity)...*`;
+                                    }
+                                }
+                                // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                                maybeEdit(true);
+                            }, 5000);
+                            try {
+                                for await (const evt of params.runtime.invoke({
+                                    prompt: currentPrompt,
+                                    model: resolveModel(params.runtimeModel, params.runtime.id),
+                                    cwd,
+                                    addDirs: addDirs.length > 0 ? Array.from(new Set(addDirs)) : undefined,
+                                    sessionId,
+                                    sessionKey,
+                                    tools: effectiveTools,
+                                    timeoutMs: params.runtimeTimeoutMs,
+                                    images: inputImages,
+                                })) {
+                                    // Track event flow for stall warning.
+                                    lastEventAt = Date.now();
+                                    stallWarned = false;
+                                    if (evt.type === 'tool_start')
+                                        activeToolCount++;
+                                    else if (evt.type === 'tool_end')
+                                        activeToolCount = Math.max(0, activeToolCount - 1);
+                                    if (evt.type === 'text_final') {
+                                        hadTextFinal = true;
+                                        finalText = evt.text;
+                                        await maybeEdit(true);
+                                    }
+                                    else if (evt.type === 'text_delta') {
+                                        deltaText += evt.text;
+                                        await maybeEdit(false);
+                                    }
+                                    else if (evt.type === 'log_line') {
+                                        const prefix = evt.stream === 'stderr' ? '[stderr] ' : '[stdout] ';
+                                        deltaText += (deltaText && !deltaText.endsWith('\n') ? '\n' : '') + prefix + evt.line + '\n';
+                                        await maybeEdit(false);
+                                    }
+                                    else if (evt.type === 'image_data') {
+                                        collectedImages.push(evt.image);
+                                    }
+                                    else if (evt.type === 'error') {
+                                        invokeError = evt.message;
+                                        metrics.recordInvokeResult('reaction', Date.now() - t0, false, evt.message);
+                                        params.log?.error({ sessionKey, error: evt.message }, `${logPrefix}:runtime error`);
+                                        params.log?.warn({ flow: 'reaction', sessionKey, error: evt.message }, 'obs.invoke.error');
+                                        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                                        statusRef?.current?.runtimeError({ sessionKey, channelName: channelCtx.channelName }, evt.message);
+                                        finalText = mapRuntimeErrorToUserMessage(evt.message);
+                                        await maybeEdit(true);
+                                        replyFinalized = true;
+                                        return;
+                                    }
+                                }
+                            }
+                            finally {
+                                clearInterval(keepalive);
+                                try {
+                                    await streamEditQueue;
+                                }
+                                catch { /* ignore */ }
+                                streamEditQueue = Promise.resolve();
+                            }
+                            metrics.recordInvokeResult('reaction', Date.now() - t0, true);
+                            params.log?.info({ flow: 'reaction', sessionKey, ms: Date.now() - t0, ok: true }, 'obs.invoke.end');
+                            let processedText = finalText || deltaText || (collectedImages.length > 0 ? '' : '(no output)');
+                            params.log?.info({ sessionKey, sessionId, ms: Date.now() - t0, hadError: Boolean(invokeError) }, `${logPrefix}:invoke:end`);
+                            // Parse and execute Discord actions.
+                            // Relax hadTextFinal requirement when stream completed without error
+                            // but text contains action markers (same fix as message-coordinator).
+                            if (!hadTextFinal && !invokeError && processedText.includes('<discord-action>')) {
+                                params.log?.warn({ sessionKey, textLen: processedText.length }, 'discord:action fallback — hadTextFinal=false but text contains action markers');
+                            }
+                            const canParseActions = hadTextFinal || (!invokeError && processedText.includes('<discord-action>'));
+                            let parsedActionCount = 0;
+                            let parsedActions = [];
+                            let actionResults = [];
+                            let strippedUnrecognizedTypes = [];
+                            if (params.discordActionsEnabled && msg.guild && canParseActions && !invokeError) {
+                                const parsed = parseDiscordActions(processedText, actionFlags);
+                                parsedActionCount = parsed.actions.length;
+                                parsedActions = parsed.actions;
+                                strippedUnrecognizedTypes = parsed.strippedUnrecognizedTypes;
+                                if (parsed.actions.length > 0) {
+                                    const actCtx = {
+                                        guild: msg.guild,
+                                        client: msg.client,
+                                        channelId: msg.channelId,
+                                        messageId: msg.id,
+                                        threadParentId,
+                                        deferScheduler: params.deferScheduler,
+                                        confirmation: {
+                                            mode: 'automated',
+                                        },
+                                    };
+                                    // Construct per-event memoryCtx with the reacting user's ID and Discord metadata.
+                                    const perEventMemoryCtx = params.memoryCtx ? {
+                                        ...params.memoryCtx,
+                                        userId: user.id,
+                                        channelId: msg.channelId,
+                                        messageId: msg.id,
+                                        guildId: msg.guildId ?? undefined,
+                                        channelName: msg.channel?.name ?? undefined,
+                                    } : undefined;
+                                    const results = await executeDiscordActions(parsed.actions, actCtx, params.log, {
+                                        taskCtx: params.taskCtx,
+                                        cronCtx: params.cronCtx,
+                                        forgeCtx: params.forgeCtx,
+                                        planCtx: params.planCtx,
+                                        memoryCtx: perEventMemoryCtx,
+                                        configCtx: params.configCtx,
+                                    });
+                                    actionResults = results;
+                                    for (const result of results) {
+                                        metrics.recordActionResult(result.ok);
+                                        params.log?.info({ flow: 'reaction', sessionKey, ok: result.ok }, 'obs.action.result');
+                                    }
+                                    const displayLines = buildDisplayResultLines(parsed.actions, results);
+                                    const anyActionSucceeded = results.some((r) => r.ok);
+                                    processedText = displayLines.length > 0
+                                        ? parsed.cleanText.trimEnd() + '\n\n' + displayLines.join('\n')
+                                        : parsed.cleanText.trimEnd();
+                                    // When all display lines were suppressed (e.g. sendMessage-only) and there's
+                                    // no prose, delete the placeholder instead of posting "(no output)".
+                                    if (!processedText.trim()
+                                        && anyActionSucceeded
+                                        && collectedImages.length === 0
+                                        && strippedUnrecognizedTypes.length === 0) {
+                                        try {
+                                            await reply?.delete();
+                                        }
+                                        catch { /* ignore */ }
+                                        replyFinalized = true;
+                                        params.log?.info({ sessionKey }, `${logPrefix}:reply suppressed (actions-only, no display text)`);
+                                        return;
+                                    }
+                                    if (statusRef?.current) {
+                                        for (let i = 0; i < results.length; i++) {
+                                            if (!results[i].ok) {
+                                                // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                                                statusRef.current.actionFailed(parsed.actions[i].type, results[i].error);
+                                            }
+                                        }
+                                    }
+                                }
+                                else {
+                                    processedText = parsed.cleanText;
+                                }
+                            }
+                            processedText = appendUnavailableActionTypesNotice(processedText, strippedUnrecognizedTypes);
+                            // Suppress empty responses and the HEARTBEAT_OK sentinel — delete placeholder and bail.
+                            const strippedText = processedText.replace(/\s+/g, ' ').trim();
+                            const isSuppressible = strippedText.length === 0 || strippedText === 'HEARTBEAT_OK' || strippedText === '(no output)';
+                            if (parsedActionCount === 0 && collectedImages.length === 0 && isSuppressible) {
+                                params.log?.info({ sessionKey, chars: strippedText.length }, `${logPrefix}:trivial response suppressed`);
+                                try {
+                                    await reply?.delete();
+                                    replyFinalized = true;
+                                }
+                                catch (delErr) {
+                                    params.log?.warn({ sessionKey, err: delErr }, `${logPrefix}:placeholder delete failed`);
+                                }
+                                return;
+                            }
+                            if (!isShuttingDown()) {
+                                try {
+                                    await editThenSendChunks(reply, msg.channel, processedText, collectedImages);
+                                    replyFinalized = true;
+                                }
+                                catch (editErr) {
+                                    if (editErr?.code === 50083) {
+                                        params.log?.info({ sessionKey }, `${logPrefix}:reply skipped (thread archived by action)`);
+                                        try {
+                                            await reply?.delete();
+                                        }
+                                        catch { /* best-effort cleanup */ }
+                                        replyFinalized = true;
+                                    }
+                                    else {
+                                        throw editErr;
+                                    }
+                                }
+                            }
+                            else {
+                                replyFinalized = true;
+                            }
+                            // -- auto-follow-up check --
+                            if (followUpDepth >= params.actionFollowupDepth)
+                                break;
+                            if (parsedActions.length === 0)
+                                break;
+                            if (!hasQueryAction(parsedActions.map((a) => a.type)))
+                                break;
+                            const anyQuerySucceeded = parsedActions.some((a, i) => QUERY_ACTION_TYPES.has(a.type) && actionResults[i]?.ok);
+                            if (!anyQuerySucceeded)
+                                break;
+                            // Build follow-up prompt with action results.
+                            const followUpLines = buildAllResultLines(actionResults);
+                            currentPrompt =
+                                `[Auto-follow-up] Your previous response included Discord actions. Here are the results:\n\n` +
+                                    followUpLines.join('\n') +
+                                    `\n\nContinue your analysis based on these results. If you need additional information, you may emit further query actions.`;
+                            followUpDepth++;
+                        } // end while (true)
+                    }
+                    catch (innerErr) {
+                        // Inner catch: attempt to show the error in the reply before the finally
+                        // block runs dispose(). Setting replyFinalized = true on success prevents
+                        // the finally's safety-net delete from removing the error message.
+                        try {
+                            if (reply && !isShuttingDown()) {
+                                await reply.edit({
+                                    content: mapRuntimeErrorToUserMessage(String(innerErr)),
+                                    allowedMentions: NO_MENTIONS,
+                                });
+                                replyFinalized = true;
+                            }
+                        }
+                        catch {
+                            // Ignore secondary errors; outer catch will handle logging.
+                        }
+                        throw innerErr;
+                    }
+                    finally {
+                        // Safety net runs before dispose() so cold-start recovery can still see
+                        // the in-flight entry if the delete fails.
+                        if (!replyFinalized && reply && !isShuttingDown()) {
+                            try {
+                                await reply.delete();
+                            }
+                            catch { /* best-effort */ }
+                        }
+                        dispose();
+                    }
+                }
+                catch (err) {
+                    metrics.increment(handlerErrorMetric);
+                    params.log?.error({ err, sessionKey }, `${logPrefix}:handler failed`);
+                    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                    statusRef?.current?.handlerError({ sessionKey }, err);
+                    try {
+                        if (reply && !isShuttingDown()) {
+                            await reply.edit({
+                                content: mapRuntimeErrorToUserMessage(String(err)),
+                                allowedMentions: NO_MENTIONS,
+                            });
+                        }
+                    }
+                    catch { /* ignore secondary Discord errors */ }
+                }
+            });
+        }
+        catch (err) {
+            const metrics = params.metrics ?? globalMetrics;
+            metrics.increment(wrapperErrorMetric);
+            params.log?.error({ err }, `${logPrefix}:${eventLabel} failed`);
+        }
+    };
+}
+export function createReactionAddHandler(params, queue, statusRef) {
+    return createReactionHandler('add', params, queue, statusRef);
+}
+export function createReactionRemoveHandler(params, queue, statusRef) {
+    return createReactionHandler('remove', params, queue, statusRef);
+}