@friendlyrobot/discord-pi-agent 0.21.3 → 0.22.0

package/dist/agent-turn-runner.d.ts

@@ -1,7 +1,14 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { ImageContent } from "@earendil-works/pi-ai";
+type ToolLifecycleEvent = {
+    toolName: string;
+    toolCallId: string;
+    isError?: boolean;
+};
 type CollectReplyOptions = {
     images?: ImageContent[];
+    onToolStart?: (event: ToolLifecycleEvent) => void | Promise<void>;
+    onToolEnd?: (event: ToolLifecycleEvent) => void | Promise<void>;
 };
 export declare function runAgentTurn(session: AgentSession, prompt: string, options?: CollectReplyOptions): Promise<string>;
 export {};

package/dist/agent-turn-runner.js

@@ -33,6 +33,10 @@ export async function runAgentTurn(session, prompt, options = {}) {
             toolCount += 1;
             const input = event.toolName === "bash" ? event.args.command : event.args;
             toolInputsByCallId.set(event.toolCallId, input);
+            void options.onToolStart?.({
+                toolName: event.toolName,
+                toolCallId: event.toolCallId,
+            });
             if (event.toolName === "bash") {
                 debugPrint(input, "CMD");
                 // logger.debug(
@@ -52,6 +56,11 @@ export async function runAgentTurn(session, prompt, options = {}) {
         if (event.type === "tool_execution_end") {
             const input = toolInputsByCallId.get(event.toolCallId);
             toolInputsByCallId.delete(event.toolCallId);
+            void options.onToolEnd?.({
+                toolName: event.toolName,
+                toolCallId: event.toolCallId,
+                isError: event.isError,
+            });
             if (event.toolName === "bash") {
                 debugPrint(extractToolOutput(event.result), event.isError ? "BASH TOOL ERROR OUTPUT" : "BASH TOOL OUTPUT");
                 // logger.debug(
@@ -138,10 +147,10 @@ function getLatestAssistantText(messages) {
     }
     return latestAssistantMessage.content
         .filter((item) => {
-        return item.type === "text";
+        return item.type === "text" && typeof item.text === "string";
     })
         .map((item) => {
-        return item.text ?? "";
+        return item.text;
     })
         .join("\n")
         .trim();

package/dist/discord-auth.d.ts

@@ -1,9 +1,10 @@
 import { type Message } from "discord.js";
+import type { SessionScope } from "./session-registry";
 import type { GatewayAccessConfig } from "./types";
 export declare function getAuthorDisplayName(message: Message): string;
 /**
  * Determine the session scope from an incoming message.
  * Returns null for unsupported channel types (silently ignored).
  */
-export declare function resolveMessageScope(message: Message): string | null;
-export declare function isAuthorizedMessage(message: Message, scope: string, accessConfig: GatewayAccessConfig): boolean;
+export declare function resolveMessageScope(message: Message): SessionScope | null;
+export declare function isAuthorizedMessage(message: Message, scope: SessionScope, accessConfig: GatewayAccessConfig): boolean;

package/dist/discord-message-handler.js

@@ -1,59 +1,57 @@
-import { executeSessionCommand } from "./session-commands";
 import { readMediaAttachments, readTextAttachments, } from "./discord-attachments";
-import { getAuthorDisplayName, isAuthorizedMessage, resolveMessageScope, } from "./discord-auth";
-import { addWorkingReaction, removeWorkingReaction, sendCommandReply, sendReply, } from "./discord-replies";
+import { isAuthorizedMessage, resolveMessageScope } from "./discord-auth";
 import { resolveMediaAttachmentsForPrompt } from "./discord-media-resolution";
+import { addReaction, addWorkingReaction, removeReaction, removeWorkingReaction, sendCommandReply, sendReply, } from "./discord-replies";
+import { executeSessionCommand } from "./session-commands";
 import { startTypingForChannel, stopTypingForChannel } from "./discord-typing";
 import { createModuleLogger } from "./logger";
-import { formatDiscordPromptTime, wrapXmlTag } from "./prompt-context";
+import { buildDiscordMessageMetadata, formatDiscordPromptTime, wrapXmlTag, } from "./prompt-context";
 import { runAgentTurn } from "./agent-turn-runner";
 const logger = createModuleLogger("discord-message-handler");
-/** Build a Discord metadata XML string for a message. */
-function formatDiscordMessageMetadata(message, scope) {
-    const isThread = scope.startsWith("thread:") && message.channel.isThread();
-    const contextEntries = [
-        ["scope", scope === "dm" ? "dm" : "thread"],
-        ["sent_at", message.createdAt.toISOString()],
-        ["sent_at_local", formatDiscordPromptTime(message.createdAt)],
-        ["message_id", message.id],
-        [
-            "author_name",
-            getAuthorDisplayName(message).replace(/\s+/g, " ").trim() || undefined,
-        ],
-        ["author_id", message.author.id],
-        [
-            "thread_title",
-            isThread
-                ? (message.channel.name ?? "").replace(/\s+/g, " ").trim()
-                : undefined,
-        ],
-        ["thread_id", isThread ? message.channel.id : undefined],
-        [
-            "forum_channel_id",
-            isThread ? (message.channel.parentId ?? undefined) : undefined,
-        ],
-    ].filter((entry) => {
-        return typeof entry[1] === "string" && entry[1].length > 0;
-    });
-    const contextJson = JSON.stringify(Object.fromEntries(contextEntries), null, 2);
-    return `<discord_message_context>${contextJson}</discord_message_context>`;
-}
+const TOOL_REACTION_EMOJIS = {
+    bash: "🖥️",
+    edit: "✏️",
+    read: "👀",
+    write: "📝",
+};
+const DEFAULT_TOOL_REACTION_EMOJI = "🔧";
 export async function handleDiscordMessage(message, config, agentService, sessionRegistry, accessConfig) {
-    if (message.author.bot) {
-        // logger.debug("ignored bot message");
+    const preparedMessage = await prepareDiscordMessage(message, accessConfig);
+    if (!preparedMessage) {
         return;
     }
-    if (message.system) {
-        // logger.debug({ messageId: message.id }, "ignored system message");
+    logger.info({
+        scope: preparedMessage.scope,
+        content: preparedMessage.content,
+    }, "message received");
+    const channelKey = message.channel.id;
+    startTypingIfPossible(message, channelKey);
+    const { entry, created } = await sessionRegistry.getOrCreate(preparedMessage.scope);
+    logNewThreadSession(message, preparedMessage.scope, created);
+    const commandResult = await executeSessionCommand(preparedMessage.content, {
+        agentService,
+        promptQueue: entry.promptQueue,
+        session: entry.session,
+        scope: preparedMessage.scope,
+        workingEmoji: entry.workingEmoji,
+    });
+    if (commandResult.handled) {
+        await handleCommandResult(message, sessionRegistry, preparedMessage.scope, entry, commandResult, preparedMessage.content, channelKey);
         return;
     }
+    await processAgentPrompt(message, config, agentService, entry, preparedMessage, channelKey);
+}
+async function prepareDiscordMessage(message, accessConfig) {
+    if (message.author.bot || message.system) {
+        return null;
+    }
     const scope = resolveMessageScope(message);
     if (scope === null) {
         logger.debug({
             messageId: message.id,
             channelType: message.channel.type,
         }, "unsupported channel type, ignoring");
-        return;
+        return null;
     }
     if (!isAuthorizedMessage(message, scope, accessConfig)) {
         logger.debug({
@@ -61,129 +59,176 @@ export async function handleDiscordMessage(message, config, agentService, sessio
             authorId: message.author.id,
             scope,
         }, "unauthorized");
-        return;
-    }
-    let content = message.content.trim();
-    const textAttachments = await readTextAttachments(message);
-    if (textAttachments.length > 0) {
-        const attachmentSuffix = textAttachments
-            .map((attachment) => {
-            return `\n\n--- Attachment: ${attachment.filename} ---\n${attachment.content}`;
-        })
-            .join("");
-        content = content
-            ? content + attachmentSuffix
-            : textAttachments[0].content;
+        return null;
     }
+    const content = await buildMessageContent(message);
     const mediaAttachments = await readMediaAttachments(message);
     if (!content && mediaAttachments.length === 0) {
         logger.debug({ messageId: message.id }, "ignored empty message (no text or images)");
-        return;
+        return null;
     }
-    logger.info({
-        // direction: "IN",
+    return {
         scope,
-        // messageId: message.id,
-        // authorId: message.author.id,
-        // channelType: message.channel.type,
         content,
-    }, "message received");
-    const channelKey = message.channel.id;
+        mediaAttachments,
+    };
+}
+async function buildMessageContent(message) {
+    const baseContent = message.content.trim();
+    const textAttachments = await readTextAttachments(message);
+    if (textAttachments.length === 0) {
+        return baseContent;
+    }
+    const attachmentText = textAttachments
+        .map((attachment) => {
+        return `\n\n--- Attachment: ${attachment.filename} ---\n${attachment.content}`;
+    })
+        .join("");
+    if (!baseContent) {
+        return textAttachments[0]?.content ?? "";
+    }
+    return baseContent + attachmentText;
+}
+function startTypingIfPossible(message, channelKey) {
     if (message.channel.isSendable()) {
         startTypingForChannel(message.channel, channelKey);
     }
-    const { entry, created } = await sessionRegistry.getOrCreate(scope);
-    const { session, promptQueue } = entry;
-    if (created && scope.startsWith("thread:") && message.channel.isThread()) {
-        logger.info({
-            scope,
-            threadName: message.channel.name,
-        }, "new thread session");
+}
+function logNewThreadSession(message, scope, created) {
+    if (!created || !scope.startsWith("thread:") || !message.channel.isThread()) {
+        return;
     }
-    const commandResult = await executeSessionCommand(content, {
-        agentService,
-        promptQueue,
-        session,
+    logger.info({
         scope,
-        workingEmoji: entry.workingEmoji,
-    });
-    if (commandResult.handled) {
-        stopTypingForChannel(channelKey);
-        if (commandResult.workingEmoji) {
-            entry.workingEmoji = commandResult.workingEmoji;
-            logger.info({ scope, emoji: commandResult.workingEmoji }, "working emoji updated");
-        }
-        if (commandResult.newSession) {
-            entry.session = commandResult.newSession;
-            logger.info({ scope, sessionId: commandResult.newSession.sessionId }, "session replaced");
-        }
-        if (commandResult.archive && scope.startsWith("thread:")) {
-            logger.info({ scope }, "archiving thread");
-            const archiveChannel = message.channel;
-            if (archiveChannel.isSendable()) {
-                await archiveChannel.send(`\`\`\`\n${commandResult.response ?? "Archiving..."}\n\`\`\``);
-            }
-            try {
-                if (archiveChannel.isThread()) {
-                    await archiveChannel.setArchived(true);
-                }
-            }
-            catch (error) {
-                logger.error({ error }, "failed to archive thread");
-            }
-            await sessionRegistry.remove(scope);
-            return;
-        }
-        logger.info({
-            messageId: message.id,
-            command: content,
-            hasResponse: Boolean(commandResult.response),
-        }, `command handled: ${content}`);
-        if (commandResult.response) {
-            await sendCommandReply(message, commandResult.response);
-        }
+        threadName: message.channel.name,
+    }, "new thread session");
+}
+async function handleCommandResult(message, sessionRegistry, scope, entry, commandResult, content, channelKey) {
+    stopTypingForChannel(channelKey);
+    if (commandResult.workingEmoji) {
+        entry.workingEmoji = commandResult.workingEmoji;
+        logger.info({ scope, emoji: commandResult.workingEmoji }, "working emoji updated");
+    }
+    if (commandResult.newSession) {
+        entry.session = commandResult.newSession;
+        logger.info({ scope, sessionId: commandResult.newSession.sessionId }, "session replaced");
+    }
+    if (commandResult.archive && scope.startsWith("thread:")) {
+        await archiveThreadSession(message, sessionRegistry, scope, commandResult);
         return;
     }
+    logger.info({
+        messageId: message.id,
+        command: content,
+        hasResponse: Boolean(commandResult.response),
+    }, `command handled: ${content}`);
+    if (commandResult.response) {
+        await sendCommandReply(message, commandResult.response);
+    }
+}
+async function archiveThreadSession(message, sessionRegistry, scope, commandResult) {
+    logger.info({ scope }, "archiving thread");
+    if (message.channel.isSendable()) {
+        await message.channel.send(`\`\`\`\n${commandResult.response ?? "Archiving..."}\n\`\`\``);
+    }
+    try {
+        if (message.channel.isThread()) {
+            await message.channel.setArchived(true);
+        }
+    }
+    catch (error) {
+        logger.error({ error }, "failed to archive thread");
+    }
+    await sessionRegistry.remove(scope);
+}
+function resolveToolReactionEmoji(toolName) {
+    return TOOL_REACTION_EMOJIS[toolName] ?? DEFAULT_TOOL_REACTION_EMOJI;
+}
+async function processAgentPrompt(message, config, agentService, entry, preparedMessage, channelKey) {
     if (!message.channel.isSendable()) {
         stopTypingForChannel(channelKey);
         logger.debug({ messageId: message.id }, "channel not sendable");
         return;
     }
     await addWorkingReaction(message, entry.workingEmoji);
-    const queuePosition = promptQueue.getSnapshot().pending;
-    if (queuePosition > 0) {
-        await sendReply(message, `Queued. ${queuePosition} request(s) ahead of this one.`);
-    }
-    let response;
+    await notifyIfPromptQueued(message, entry.promptQueue.getSnapshot().pending);
+    const toolEmojiByCallId = new Map();
+    const activeToolCountByEmoji = new Map();
     try {
-        response = await promptQueue.enqueue(async () => {
-            let promptContent = content;
-            let promptImages;
-            if (mediaAttachments.length > 0) {
-                const resolvedPromptMedia = await resolveMediaAttachmentsForPrompt(mediaAttachments, promptContent, session.model, config, agentService);
-                promptContent = resolvedPromptMedia.content;
-                if (resolvedPromptMedia.images.length > 0) {
-                    promptImages = resolvedPromptMedia.images;
-                }
-            }
-            const discordMetadata = formatDiscordMessageMetadata(message, scope);
-            const transformedPrompt = await config.promptTransform({
-                rawContent: promptContent,
-                discordMetadata,
-                now: () => wrapXmlTag("datetime", formatDiscordPromptTime(new Date(), {
-                    timeZone: config.promptTimeZone,
-                    locale: config.promptLocale,
-                })),
-                userMessage: () => wrapXmlTag("user_message", promptContent),
-            });
-            return runAgentTurn(session, transformedPrompt, {
-                images: promptImages,
+        const response = await entry.promptQueue.enqueue(async () => {
+            const promptInput = await buildPromptInput(message, config, agentService, entry, preparedMessage);
+            return runAgentTurn(entry.session, promptInput.prompt, {
+                images: promptInput.images,
+                onToolStart: async ({ toolName, toolCallId }) => {
+                    const emoji = resolveToolReactionEmoji(toolName);
+                    toolEmojiByCallId.set(toolCallId, emoji);
+                    const activeCount = activeToolCountByEmoji.get(emoji) ?? 0;
+                    activeToolCountByEmoji.set(emoji, activeCount + 1);
+                    if (activeCount === 0) {
+                        await addReaction(message, emoji);
+                    }
+                },
+                onToolEnd: async ({ toolCallId }) => {
+                    const emoji = toolEmojiByCallId.get(toolCallId);
+                    if (!emoji) {
+                        return;
+                    }
+                    toolEmojiByCallId.delete(toolCallId);
+                    const activeCount = activeToolCountByEmoji.get(emoji) ?? 0;
+                    if (activeCount <= 1) {
+                        activeToolCountByEmoji.delete(emoji);
+                        await removeReaction(message, emoji);
+                        return;
+                    }
+                    activeToolCountByEmoji.set(emoji, activeCount - 1);
+                },
             });
         });
+        await sendReply(message, response);
     }
     finally {
         stopTypingForChannel(channelKey);
+        const activeEmojis = Array.from(activeToolCountByEmoji.keys());
+        await Promise.all(activeEmojis.map(async (emoji) => {
+            await removeReaction(message, emoji);
+        }));
         await removeWorkingReaction(message, entry.workingEmoji);
     }
-    await sendReply(message, response);
+}
+async function notifyIfPromptQueued(message, pendingCount) {
+    if (pendingCount > 0) {
+        await sendReply(message, `Queued. ${pendingCount} request(s) ahead of this one.`);
+    }
+}
+async function buildPromptInput(message, config, agentService, entry, preparedMessage) {
+    const resolvedPromptMedia = await resolvePromptMedia(preparedMessage, entry, config, agentService);
+    const discordMetadata = buildDiscordMessageMetadata(message, preparedMessage.scope);
+    const prompt = await config.promptTransform({
+        rawContent: resolvedPromptMedia.content,
+        discordMetadata,
+        now: () => {
+            return wrapXmlTag("datetime", formatDiscordPromptTime(new Date(), {
+                timeZone: config.promptTimeZone,
+                locale: config.promptLocale,
+            }));
+        },
+        userMessage: () => {
+            return wrapXmlTag("user_message", resolvedPromptMedia.content);
+        },
+    });
+    return {
+        prompt,
+        images: resolvedPromptMedia.images.length > 0
+            ? resolvedPromptMedia.images
+            : undefined,
+    };
+}
+async function resolvePromptMedia(preparedMessage, entry, config, agentService) {
+    if (preparedMessage.mediaAttachments.length === 0) {
+        return {
+            content: preparedMessage.content,
+            images: [],
+        };
+    }
+    return resolveMediaAttachmentsForPrompt(preparedMessage.mediaAttachments, preparedMessage.content, entry.session.model, config, agentService);
 }

package/dist/discord-replies.d.ts

@@ -1,5 +1,7 @@
 import type { Message } from "discord.js";
 export declare const DEFAULT_WORKING_EMOJI = "\u2699\uFE0F";
+export declare function addReaction(message: Message, emoji: string): Promise<void>;
+export declare function removeReaction(message: Message, emoji: string): Promise<void>;
 export declare function addWorkingReaction(message: Message, emoji?: string): Promise<void>;
 export declare function removeWorkingReaction(message: Message, emoji?: string): Promise<void>;
 export declare function sendReply(message: Message, text: string): Promise<void>;

package/dist/discord-replies.js

@@ -35,15 +35,15 @@ function chunkByLines(text, maxSize) {
     return chunks;
 }
 export const DEFAULT_WORKING_EMOJI = "⚙️";
-export async function addWorkingReaction(message, emoji = DEFAULT_WORKING_EMOJI) {
+export async function addReaction(message, emoji) {
     try {
         await message.react(emoji);
     }
     catch (error) {
-        logger.debug({ messageId: message.id, error }, "failed to add working reaction");
+        logger.debug({ messageId: message.id, emoji, error }, "failed to add reaction");
     }
 }
-export async function removeWorkingReaction(message, emoji = DEFAULT_WORKING_EMOJI) {
+export async function removeReaction(message, emoji) {
     try {
         const reaction = message.reactions.cache.get(emoji);
         if (reaction) {
@@ -51,9 +51,15 @@ export async function removeWorkingReaction(message, emoji = DEFAULT_WORKING_EMO
         }
     }
     catch (error) {
-        logger.debug({ messageId: message.id, error }, "failed to remove working reaction");
+        logger.debug({ messageId: message.id, emoji, error }, "failed to remove reaction");
     }
 }
+export async function addWorkingReaction(message, emoji = DEFAULT_WORKING_EMOJI) {
+    await addReaction(message, emoji);
+}
+export async function removeWorkingReaction(message, emoji = DEFAULT_WORKING_EMOJI) {
+    await removeReaction(message, emoji);
+}
 export async function sendReply(message, text) {
     const channel = message.channel;
     if (!channel.isSendable()) {

package/dist/prompt-context.d.ts

@@ -1,7 +1,10 @@
+import type { Message } from "discord.js";
+import type { SessionScope } from "./session-registry";
 export type DiscordPromptTimeFormatOptions = {
     timeZone?: string;
     locale?: string;
 };
 export declare function formatDiscordPromptTime(date: Date, options?: DiscordPromptTimeFormatOptions): string;
+export declare function buildDiscordMessageMetadata(message: Message, scope: SessionScope): string;
 /** Wrap content in an XML-style tag: `<tag>content</tag>`. */
 export declare function wrapXmlTag(tag: string, content: string): string;

package/dist/prompt-context.js

@@ -1,3 +1,4 @@
+import { getAuthorDisplayName } from "./discord-auth";
 export function formatDiscordPromptTime(date, options = {}) {
     const timeZone = options.timeZone || "UTC";
     const locale = options.locale || "en-AU";
@@ -13,6 +14,34 @@ export function formatDiscordPromptTime(date, options = {}) {
         timeZoneName: "short",
     }).format(date);
 }
+export function buildDiscordMessageMetadata(message, scope) {
+    const isThread = scope.startsWith("thread:") && message.channel.isThread();
+    const contextEntries = [
+        ["scope", scope === "dm" ? "dm" : "thread"],
+        ["sent_at", message.createdAt.toISOString()],
+        ["sent_at_local", formatDiscordPromptTime(message.createdAt)],
+        ["message_id", message.id],
+        [
+            "author_name",
+            getAuthorDisplayName(message).replace(/\s+/g, " ").trim() || undefined,
+        ],
+        ["author_id", message.author.id],
+        [
+            "thread_title",
+            isThread
+                ? (message.channel.name ?? "").replace(/\s+/g, " ").trim()
+                : undefined,
+        ],
+        ["thread_id", isThread ? message.channel.id : undefined],
+        [
+            "forum_channel_id",
+            isThread ? (message.channel.parentId ?? undefined) : undefined,
+        ],
+    ].filter((entry) => {
+        return typeof entry[1] === "string" && entry[1].length > 0;
+    });
+    return wrapXmlTag("discord_message_context", JSON.stringify(Object.fromEntries(contextEntries), null, 2));
+}
 /** Wrap content in an XML-style tag: `<tag>content</tag>`. */
 export function wrapXmlTag(tag, content) {
     return `<${tag}>${content}</${tag}>`;

package/dist/session-registry.d.ts

@@ -1,7 +1,7 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { AgentService } from "./agent-service";
 import { PromptQueue } from "./prompt-queue";
-export type SessionScope = string;
+export type SessionScope = "dm" | `thread:${string}`;
 export type ScopedSessionEntry = {
     session: AgentSession;
     promptQueue: PromptQueue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friendlyrobot/discord-pi-agent",
-  "version": "0.21.3",
+  "version": "0.22.0",
   "description": "Reusable Discord gateway for persistent pi agent sessions",
   "license": "MIT",
   "type": "module",