@friendlyrobot/discord-pi-agent 0.21.1 → 0.21.4

package/dist/debug-print.js

@@ -0,0 +1,22 @@
+/**
+ * Print a text body to stdout with ASCII fences.
+ * Useful for ad-hoc debug output that stands out in logs.
+ *
+ * @param body  The text content to print.
+ * @param title Optional label for the opening fence (defaults to "DEBUG").
+ */
+export function debugPrint(body, title) {
+    const WIDTH = 80;
+    const label = title ?? "DEBUG";
+    function centeredFence(text) {
+        const inner = ` ${text} `;
+        const padLen = Math.floor((WIDTH - inner.length) / 2);
+        const pad = "=".repeat(padLen);
+        const result = pad + inner + pad;
+        // tack on one extra "=" if the width is odd
+        return result.length < WIDTH ? result + "=" : result;
+    }
+    console.info(centeredFence(label));
+    console.info(body);
+    console.info(centeredFence(`${label} END`));
+}

package/dist/discord-attachments.js

@@ -0,0 +1,148 @@
+import { createModuleLogger } from "./logger";
+const logger = createModuleLogger("discord-attachments");
+const TEXT_ATTACHMENT_EXTENSIONS = [
+    ".txt",
+    ".md",
+    ".json",
+    ".csv",
+    ".log",
+    ".yml",
+    ".yaml",
+    ".xml",
+    ".toml",
+    ".ini",
+    ".cfg",
+];
+const MAX_TEXT_ATTACHMENT_SIZE_BYTES = 25 * 1024 * 1024;
+const MEDIA_ATTACHMENT_EXTENSIONS = [
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".pdf",
+    ".docx",
+    ".doc",
+    ".pptx",
+    ".ppt",
+    ".xlsx",
+    ".xls",
+];
+const MAX_MEDIA_ATTACHMENT_SIZE_BYTES = 25 * 1024 * 1024;
+const OFFICE_MIME_TYPES = new Set([
+    "application/pdf",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "application/vnd.ms-powerpoint",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-excel",
+]);
+export function isSupportedTextAttachment(attachment) {
+    const ext = attachment.name
+        ?.slice(attachment.name.lastIndexOf("."))
+        .toLowerCase();
+    return Boolean(ext && TEXT_ATTACHMENT_EXTENSIONS.includes(ext));
+}
+export function isSupportedMediaAttachment(attachment) {
+    const ext = attachment.name
+        ?.slice(attachment.name.lastIndexOf("."))
+        .toLowerCase();
+    if (!ext || !MEDIA_ATTACHMENT_EXTENSIONS.includes(ext)) {
+        return false;
+    }
+    const contentType = attachment.contentType;
+    if (!contentType) {
+        return false;
+    }
+    return contentType.startsWith("image/") || OFFICE_MIME_TYPES.has(contentType);
+}
+export async function readTextAttachments(message) {
+    const attachments = message.attachments;
+    if (attachments.size === 0) {
+        return [];
+    }
+    const results = [];
+    for (const [, attachment] of attachments) {
+        if (!isSupportedTextAttachment(attachment)) {
+            logger.debug({ messageId: message.id, filename: attachment.name }, "skipping non-text attachment");
+            continue;
+        }
+        if (attachment.size > MAX_TEXT_ATTACHMENT_SIZE_BYTES) {
+            logger.warn({
+                messageId: message.id,
+                filename: attachment.name,
+                size: attachment.size,
+            }, "attachment too large, skipping");
+            continue;
+        }
+        try {
+            logger.info({
+                messageId: message.id,
+                filename: attachment.name,
+                size: attachment.size,
+            }, "fetching attachment");
+            const response = await fetch(attachment.url);
+            if (!response.ok) {
+                logger.warn({
+                    messageId: message.id,
+                    filename: attachment.name,
+                    status: response.status,
+                }, "failed to fetch attachment");
+                continue;
+            }
+            const content = await response.text();
+            results.push({ filename: attachment.name, content });
+        }
+        catch (error) {
+            logger.error({ messageId: message.id, filename: attachment.name, error }, "error fetching attachment");
+        }
+    }
+    return results;
+}
+export async function readMediaAttachments(message) {
+    const attachments = message.attachments;
+    if (attachments.size === 0) {
+        return [];
+    }
+    const results = [];
+    for (const [, attachment] of attachments) {
+        if (!isSupportedMediaAttachment(attachment)) {
+            continue;
+        }
+        if (attachment.size > MAX_MEDIA_ATTACHMENT_SIZE_BYTES) {
+            logger.warn({
+                messageId: message.id,
+                filename: attachment.name,
+                size: attachment.size,
+            }, "media attachment too large, skipping");
+            continue;
+        }
+        try {
+            logger.info({
+                messageId: message.id,
+                filename: attachment.name,
+                size: attachment.size,
+            }, "fetching media attachment");
+            const response = await fetch(attachment.url);
+            if (!response.ok) {
+                logger.warn({
+                    messageId: message.id,
+                    filename: attachment.name,
+                    status: response.status,
+                }, "failed to fetch media attachment");
+                continue;
+            }
+            const buffer = await response.arrayBuffer();
+            results.push({
+                filename: attachment.name,
+                data: Buffer.from(buffer).toString("base64"),
+                mimeType: attachment.contentType ?? "application/octet-stream",
+            });
+        }
+        catch (error) {
+            logger.error({ messageId: message.id, filename: attachment.name, error }, "error fetching media attachment");
+        }
+    }
+    return results;
+}

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-auth.js

@@ -0,0 +1,37 @@
+import { ChannelType } from "discord.js";
+export function getAuthorDisplayName(message) {
+    return (message.member?.displayName ||
+        message.author.globalName ||
+        message.author.username);
+}
+/**
+ * Determine the session scope from an incoming message.
+ * Returns null for unsupported channel types (silently ignored).
+ */
+export function resolveMessageScope(message) {
+    if (message.channel.type === ChannelType.DM) {
+        return "dm";
+    }
+    if (message.channel.isThread()) {
+        return `thread:${message.channel.id}`;
+    }
+    return null;
+}
+export function isAuthorizedMessage(message, scope, accessConfig) {
+    if (scope === "dm") {
+        return message.author.id === accessConfig.discordAllowedUserId;
+    }
+    if (scope.startsWith("thread:")) {
+        const channel = message.channel;
+        if (!channel.isThread()) {
+            return false;
+        }
+        const parentId = channel.parentId;
+        if (!parentId ||
+            !accessConfig.discordAllowedForumChannelIds.includes(parentId)) {
+            return false;
+        }
+        return accessConfig.discordAllowedUserIds.includes(message.author.id);
+    }
+    return false;
+}

package/dist/discord-gateway-client.js

@@ -0,0 +1,49 @@
+import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
+import { handleDiscordMessage } from "./discord-message-handler";
+import { sendReply } from "./discord-replies";
+import { createModuleLogger } from "./logger";
+const logger = createModuleLogger("discord-gateway");
+export async function startGatewayClient(config, agentService, sessionRegistry, accessConfig) {
+    const client = new Client({
+        intents: [
+            GatewayIntentBits.DirectMessages,
+            GatewayIntentBits.Guilds,
+            GatewayIntentBits.GuildMessages,
+            GatewayIntentBits.MessageContent,
+        ],
+        partials: [Partials.Channel],
+    });
+    client.once(Events.ClientReady, async (readyClient) => {
+        logger.info({ userTag: readyClient.user.tag }, "logged in");
+        if (!accessConfig.startupMessage) {
+            return;
+        }
+        try {
+            const user = await readyClient.users.fetch(accessConfig.discordAllowedUserId);
+            const dmChannel = await user.createDM();
+            await dmChannel.send(accessConfig.startupMessage);
+            logger.info({
+                userId: accessConfig.discordAllowedUserId,
+            }, "sent startup dm");
+        }
+        catch (error) {
+            logger.error({ error }, "failed to send startup dm");
+        }
+    });
+    client.on(Events.MessageCreate, async (message) => {
+        try {
+            await handleDiscordMessage(message, config, agentService, sessionRegistry, accessConfig);
+        }
+        catch (error) {
+            logger.error({ error, direction: "IN" }, "message handling failed");
+            await sendReply(message, "The bot hit an error while handling that message.");
+        }
+    });
+    client.on(Events.ThreadDelete, async (thread) => {
+        const scope = `thread:${thread.id}`;
+        logger.info({ threadId: thread.id, scope }, "thread deleted");
+        await sessionRegistry.remove(scope);
+    });
+    await client.login(config.discordBotToken);
+    return client;
+}

package/dist/discord-media-resolution.js

@@ -0,0 +1,107 @@
+import { describeMediaAttachment } from "./media-description";
+import { createModuleLogger } from "./logger";
+const logger = createModuleLogger("discord-media-resolution");
+/**
+ * Parse a "provider/modelId" string, handling model IDs that contain slashes.
+ */
+export function parseProviderModelId(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const slashIndex = trimmed.indexOf("/");
+    if (slashIndex === -1) {
+        return null;
+    }
+    return {
+        provider: trimmed.substring(0, slashIndex),
+        modelId: trimmed.substring(slashIndex + 1),
+    };
+}
+export function getMediaAttachmentLabel(filename, mimeType) {
+    if (mimeType === "application/pdf") {
+        return `[PDF: ${filename}]`;
+    }
+    if (mimeType ===
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ||
+        mimeType === "application/msword") {
+        return `[Word: ${filename}]`;
+    }
+    if (mimeType ===
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" ||
+        mimeType === "application/vnd.ms-excel") {
+        return `[Excel: ${filename}]`;
+    }
+    if (mimeType ===
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation" ||
+        mimeType === "application/vnd.ms-powerpoint") {
+        return `[PowerPoint: ${filename}]`;
+    }
+    return `[Image: ${filename}]`;
+}
+export async function resolveMediaAttachmentsForPrompt(mediaAttachments, content, currentModel, config, agentService) {
+    const modelSupportsVision = currentModel?.input.includes("image") ?? false;
+    if (modelSupportsVision) {
+        const names = mediaAttachments.map((media) => media.filename).join(", ");
+        logger.info({
+            count: mediaAttachments.length,
+            filenames: names,
+            model: currentModel
+                ? `${currentModel.provider}/${currentModel.id}`
+                : "none",
+        }, "passing media natively to vision-capable model");
+        return {
+            content,
+            images: mediaAttachments.map((media) => ({
+                type: "image",
+                data: media.data,
+                mimeType: media.mimeType,
+            })),
+        };
+    }
+    if (!config.visionModelId) {
+        const names = mediaAttachments.map((media) => media.filename).join(", ");
+        logger.info({ filenames: names }, "media attachments received but vision model not configured");
+        const note = `\n\n[User sent media attachment(s): ${names}]\n` +
+            "(Media vision not configured. Set visionModelId to enable image/PDF/document understanding.)";
+        return {
+            content: content ? content + note : note,
+            images: [],
+        };
+    }
+    const parsedVisionModelId = parseProviderModelId(config.visionModelId);
+    if (!parsedVisionModelId) {
+        return { content, images: [] };
+    }
+    const visionModel = agentService.models.findModel(parsedVisionModelId.provider, parsedVisionModelId.modelId);
+    if (!visionModel) {
+        logger.warn({ visionModelId: config.visionModelId }, "vision model not found in registry");
+        const names = mediaAttachments.map((media) => media.filename).join(", ");
+        const note = `\n\n[User sent media attachment(s): ${names}]\n` +
+            `(Vision model not found: ${config.visionModelId})`;
+        return {
+            content: content ? content + note : note,
+            images: [],
+        };
+    }
+    logger.info({
+        count: mediaAttachments.length,
+        visionModel: `${visionModel.provider}/${visionModel.id}`,
+    }, "describing media with vision model");
+    const descriptions = [];
+    for (const media of mediaAttachments) {
+        const description = await describeMediaAttachment(agentService, media.data, media.mimeType, content, visionModel);
+        const label = getMediaAttachmentLabel(media.filename, media.mimeType);
+        descriptions.push(`${label}\n${description}`);
+    }
+    if (descriptions.length === 0) {
+        return { content, images: [] };
+    }
+    const descriptionPrefix = descriptions.join("\n\n");
+    return {
+        content: content
+            ? `${descriptionPrefix}\n\n---\n${content}`
+            : descriptionPrefix,
+        images: [],
+    };
+}

package/dist/discord-message-handler.js

@@ -0,0 +1,195 @@
+import { readMediaAttachments, readTextAttachments, } from "./discord-attachments";
+import { isAuthorizedMessage, resolveMessageScope } from "./discord-auth";
+import { resolveMediaAttachmentsForPrompt } from "./discord-media-resolution";
+import { addWorkingReaction, removeWorkingReaction, sendCommandReply, sendReply, } from "./discord-replies";
+import { executeSessionCommand } from "./session-commands";
+import { startTypingForChannel, stopTypingForChannel } from "./discord-typing";
+import { createModuleLogger } from "./logger";
+import { buildDiscordMessageMetadata, formatDiscordPromptTime, wrapXmlTag, } from "./prompt-context";
+import { runAgentTurn } from "./agent-turn-runner";
+const logger = createModuleLogger("discord-message-handler");
+export async function handleDiscordMessage(message, config, agentService, sessionRegistry, accessConfig) {
+    const preparedMessage = await prepareDiscordMessage(message, accessConfig);
+    if (!preparedMessage) {
+        return;
+    }
+    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 null;
+    }
+    if (!isAuthorizedMessage(message, scope, accessConfig)) {
+        logger.debug({
+            messageId: message.id,
+            authorId: message.author.id,
+            scope,
+        }, "unauthorized");
+        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 null;
+    }
+    return {
+        scope,
+        content,
+        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);
+    }
+}
+function logNewThreadSession(message, scope, created) {
+    if (!created || !scope.startsWith("thread:") || !message.channel.isThread()) {
+        return;
+    }
+    logger.info({
+        scope,
+        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);
+}
+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);
+    await notifyIfPromptQueued(message, entry.promptQueue.getSnapshot().pending);
+    try {
+        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,
+            });
+        });
+        await sendReply(message, response);
+    }
+    finally {
+        stopTypingForChannel(channelKey);
+        await removeWorkingReaction(message, entry.workingEmoji);
+    }
+}
+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.js

@@ -0,0 +1,112 @@
+import { createModuleLogger } from "./logger";
+import { chunkMessage } from "./message-chunker";
+const logger = createModuleLogger("discord-replies");
+const DISCORD_MESSAGE_LIMIT = 2000;
+const FENCE_OVERHEAD = 8; // \`\`\`\n + \n\`\`\`
+const MAX_CODE_FENCE_CONTENT = DISCORD_MESSAGE_LIMIT - FENCE_OVERHEAD;
+/**
+ * Splits text by newlines into chunks that fit within maxSize.
+ * Keeps lines intact unless a single line exceeds maxSize.
+ */
+function chunkByLines(text, maxSize) {
+    const lines = text.split("\n");
+    const chunks = [];
+    let current = "";
+    for (const line of lines) {
+        const candidate = current ? current + "\n" + line : line;
+        if (candidate.length > maxSize) {
+            if (current) {
+                chunks.push(current);
+                current = line;
+            }
+            else {
+                // A single line exceeds maxSize; split it mid-line.
+                chunks.push(line.slice(0, maxSize));
+                current = line.slice(maxSize);
+            }
+        }
+        else {
+            current = candidate;
+        }
+    }
+    if (current) {
+        chunks.push(current);
+    }
+    return chunks;
+}
+export const DEFAULT_WORKING_EMOJI = "⚙️";
+export async function addWorkingReaction(message, emoji = DEFAULT_WORKING_EMOJI) {
+    try {
+        await message.react(emoji);
+    }
+    catch (error) {
+        logger.debug({ messageId: message.id, error }, "failed to add working reaction");
+    }
+}
+export async function removeWorkingReaction(message, emoji = DEFAULT_WORKING_EMOJI) {
+    try {
+        const reaction = message.reactions.cache.get(emoji);
+        if (reaction) {
+            await reaction.users.remove(message.client.user);
+        }
+    }
+    catch (error) {
+        logger.debug({ messageId: message.id, error }, "failed to remove working reaction");
+    }
+}
+export async function sendReply(message, text) {
+    const channel = message.channel;
+    if (!channel.isSendable()) {
+        logger.debug({
+            messageId: message.id,
+        }, "reply skipped, channel not sendable");
+        return;
+    }
+    const chunks = chunkMessage(text);
+    const [firstChunk, ...remainingChunks] = chunks;
+    if (!firstChunk) {
+        return;
+    }
+    try {
+        await message.reply(firstChunk);
+        for (const chunk of remainingChunks) {
+            await channel.send(chunk);
+        }
+    }
+    catch (error) {
+        logger.error({
+            messageId: message.id,
+            error,
+        }, "send reply failed");
+    }
+}
+/**
+ * Sends a command response wrapped in triple backticks.
+ * Splits by newlines so each chunk stays within Discord's 2000-char limit.
+ */
+export async function sendCommandReply(message, text) {
+    const channel = message.channel;
+    if (!channel.isSendable()) {
+        logger.debug({
+            messageId: message.id,
+        }, "command reply skipped, channel not sendable");
+        return;
+    }
+    const chunks = chunkByLines(text, MAX_CODE_FENCE_CONTENT).map((c) => `\`\`\`\n${c}\n\`\`\``);
+    const [firstChunk, ...remainingChunks] = chunks;
+    if (!firstChunk) {
+        return;
+    }
+    try {
+        await message.reply(firstChunk);
+        for (const chunk of remainingChunks) {
+            await channel.send(chunk);
+        }
+    }
+    catch (error) {
+        logger.error({
+            messageId: message.id,
+            error,
+        }, "send command reply failed");
+    }
+}