@friendlyrobot/discord-pi-agent 0.20.1 → 0.21.1

package/README.md

@@ -43,8 +43,9 @@ Every Discord prompt is wrapped with lightweight Discord context before `promptT
 }
 </discord_message_context>
 
-User message:
+<user_message>
 ...
+</user_message>
 ```
 
 DM prompts omit thread-only fields. `sent_at_local` uses `promptTimeZone` and `promptLocale`.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { DiscordGateway, DiscordGatewayConfig } from "./types";
-export { buildDiscordMessageContextPrompt, formatDiscordPromptTime, type DiscordMessageContextPromptOptions, type DiscordPromptScope, type DiscordPromptTimeFormatOptions, } from "./prompt-context";
+export { formatDiscordPromptTime } from "./prompt-context";
 export { loadDiscordGatewayConfigFromEnv, resolveConfig } from "./config";
-export type { AgentStatus, DiscordGateway, DiscordGatewayConfig, PromptTransform, ResolvedDiscordGatewayConfig, GatewayAccessConfig, } from "./types";
+export type { AgentStatus, DiscordGateway, DiscordGatewayConfig, PromptTransform, PromptTransformContext, ResolvedDiscordGatewayConfig, GatewayAccessConfig, } from "./types";
 /**
  * Start the unified Discord gateway. Supports DM and forum thread sessions
  * out of the box. Set discordAllowedForumChannelIds to enable forum support.

package/dist/index.js

@@ -506,7 +506,12 @@ class AgentService {
   }
   async prompt(text) {
     const session = this.requireSession();
-    const transformedPrompt = await this.config.promptTransform(text);
+    const transformedPrompt = await this.config.promptTransform({
+      rawContent: text,
+      discordMetadata: "",
+      now: () => "",
+      userMessage: () => text
+    });
     return runAgentTurn(session, transformedPrompt);
   }
   async compact() {
@@ -603,7 +608,7 @@ function resolveConfig(config) {
     thinkingLevel: parseThinkingLevel(config.thinkingLevel) || "medium",
     promptTimeZone: config.promptTimeZone?.trim() || "UTC",
     promptLocale: config.promptLocale?.trim() || "en-AU",
-    promptTransform: config.promptTransform || identityPromptTransform,
+    promptTransform: config.promptTransform || defaultPromptTransform,
     startupMessage: config.startupMessage === undefined ? "Bot is online and ready." : config.startupMessage,
     shutdownOnSignals: config.shutdownOnSignals ?? true,
     visionModelId: config.visionModelId?.trim() || null,
@@ -669,8 +674,9 @@ function parseThinkingLevel(value) {
   }
   return;
 }
-function identityPromptTransform(input) {
-  return input;
+function defaultPromptTransform(ctx) {
+  return [ctx.now(), ctx.discordMetadata, "", ctx.userMessage()].filter(Boolean).join(`
+`);
 }
 function parseStringArrayFromEnv(key) {
   const value = process.env[key];
@@ -683,6 +689,245 @@ function parseStringArrayFromEnv(key) {
 // src/discord-gateway-client.ts
 import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
 
+// src/session-registry.ts
+import path3 from "node:path";
+
+// src/prompt-queue.ts
+class PromptQueue {
+  queue = [];
+  running = false;
+  enqueue(task) {
+    return new Promise((resolve, reject) => {
+      this.queue.push(async () => {
+        try {
+          resolve(await task());
+        } catch (error) {
+          reject(error);
+        }
+      });
+      this.runNextTask();
+    });
+  }
+  getSnapshot() {
+    return {
+      pending: this.queue.length,
+      busy: this.running
+    };
+  }
+  runNextTask() {
+    if (this.running) {
+      return;
+    }
+    const next = this.queue.shift();
+    if (!next) {
+      return;
+    }
+    this.running = true;
+    next().finally(() => {
+      this.running = false;
+      this.runNextTask();
+    });
+  }
+}
+
+// src/message-chunker.ts
+import { marked } from "marked";
+var DISCORD_MESSAGE_LIMIT = 2000;
+var SAFE_MESSAGE_LIMIT = 1900;
+function chunkMessage(text, maxChunkSize = SAFE_MESSAGE_LIMIT) {
+  if (text.length <= maxChunkSize) {
+    return [text];
+  }
+  const tokens = marked.lexer(text);
+  const chunks = [];
+  let currentTokens = [];
+  let currentSize = 0;
+  const flushChunk = () => {
+    if (currentTokens.length > 0) {
+      chunks.push(currentTokens.map((t) => t.raw).join("").trim());
+      currentTokens = [];
+      currentSize = 0;
+    }
+  };
+  for (const token of tokens) {
+    const size = token.raw.length;
+    if (currentSize + size > maxChunkSize && currentTokens.length > 0) {
+      flushChunk();
+    }
+    currentTokens.push(token);
+    currentSize += size;
+  }
+  flushChunk();
+  return chunks.map((chunk) => chunk.slice(0, DISCORD_MESSAGE_LIMIT));
+}
+
+// src/discord-replies.ts
+var logger6 = createModuleLogger("discord-replies");
+var DISCORD_MESSAGE_LIMIT2 = 2000;
+var FENCE_OVERHEAD = 8;
+var MAX_CODE_FENCE_CONTENT = DISCORD_MESSAGE_LIMIT2 - FENCE_OVERHEAD;
+function chunkByLines(text, maxSize) {
+  const lines = text.split(`
+`);
+  const chunks = [];
+  let current = "";
+  for (const line of lines) {
+    const candidate = current ? current + `
+` + line : line;
+    if (candidate.length > maxSize) {
+      if (current) {
+        chunks.push(current);
+        current = line;
+      } else {
+        chunks.push(line.slice(0, maxSize));
+        current = line.slice(maxSize);
+      }
+    } else {
+      current = candidate;
+    }
+  }
+  if (current) {
+    chunks.push(current);
+  }
+  return chunks;
+}
+var DEFAULT_WORKING_EMOJI = "⚙️";
+async function addWorkingReaction(message, emoji = DEFAULT_WORKING_EMOJI) {
+  try {
+    await message.react(emoji);
+  } catch (error) {
+    logger6.debug({ messageId: message.id, error }, "failed to add working reaction");
+  }
+}
+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) {
+    logger6.debug({ messageId: message.id, error }, "failed to remove working reaction");
+  }
+}
+async function sendReply(message, text) {
+  const channel = message.channel;
+  if (!channel.isSendable()) {
+    logger6.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) {
+    logger6.error({
+      messageId: message.id,
+      error
+    }, "send reply failed");
+  }
+}
+async function sendCommandReply(message, text) {
+  const channel = message.channel;
+  if (!channel.isSendable()) {
+    logger6.debug({
+      messageId: message.id
+    }, "command reply skipped, channel not sendable");
+    return;
+  }
+  const chunks = chunkByLines(text, MAX_CODE_FENCE_CONTENT).map((c) => `\`\`\`
+${c}
+\`\`\``);
+  const [firstChunk, ...remainingChunks] = chunks;
+  if (!firstChunk) {
+    return;
+  }
+  try {
+    await message.reply(firstChunk);
+    for (const chunk of remainingChunks) {
+      await channel.send(chunk);
+    }
+  } catch (error) {
+    logger6.error({
+      messageId: message.id,
+      error
+    }, "send command reply failed");
+  }
+}
+
+// src/session-registry.ts
+function sessionDirForScope(agentDir, scope) {
+  if (scope === "dm") {
+    return path3.join(agentDir, "sessions");
+  }
+  if (scope.startsWith("thread:")) {
+    const threadId = scope.slice(7);
+    return path3.join(agentDir, "sessions", `thread-${threadId}`);
+  }
+  throw new Error(`Unknown session scope: ${scope}`);
+}
+var logger7 = createModuleLogger("session-registry");
+
+class SessionRegistry {
+  scopes = new Map;
+  agentService;
+  constructor(agentService) {
+    this.agentService = agentService;
+  }
+  async getOrCreate(scope) {
+    const existing = this.scopes.get(scope);
+    if (existing) {
+      return { entry: existing, created: false };
+    }
+    const sessionDir = sessionDirForScope(this.agentService.getAgentDir(), scope);
+    const session = await this.agentService.createSession(sessionDir);
+    const promptQueue = new PromptQueue;
+    const entry = {
+      session,
+      promptQueue,
+      createdAt: new Date,
+      workingEmoji: DEFAULT_WORKING_EMOJI
+    };
+    this.scopes.set(scope, entry);
+    logger7.debug({
+      scope,
+      sessionDir,
+      sessionId: session.sessionId
+    }, "scope registered");
+    return { entry, created: true };
+  }
+  async remove(scope) {
+    const entry = this.scopes.get(scope);
+    if (!entry) {
+      return;
+    }
+    logger7.debug({ scope }, "removing scope");
+    await entry.session.abort();
+    entry.session.dispose();
+    this.scopes.delete(scope);
+  }
+  get(scope) {
+    return this.scopes.get(scope);
+  }
+  getScopes() {
+    return Array.from(this.scopes.keys());
+  }
+  async shutdownAll() {
+    logger7.info({ count: this.scopes.size }, "shutting down all scopes");
+    const scopes = Array.from(this.scopes.keys());
+    for (const scope of scopes) {
+      await this.remove(scope);
+    }
+  }
+}
+
 // src/session-commands.ts
 function getSessionStatusText(session, promptQueue, extras) {
   const model = session.model ? `${session.model.provider}/${session.model.id}` : "(no model selected)";
@@ -886,22 +1131,23 @@ async function handleResetSessionCommand(trimmedInput, context) {
   if (trimmedInput !== "!reset-session") {
     return null;
   }
-  if (context.session) {
-    return {
-      handled: true,
-      response: await context.promptQueue.enqueue(async () => {
-        const previousSession = context.session;
-        await previousSession.abort();
-        previousSession.dispose();
-        return `Session reset. Old session kept at ${previousSession.sessionFile ?? "(unknown path)"}. Use !archive to archive the thread and start fresh.`;
-      })
-    };
+  const effectiveSession = requireEffectiveSession(context);
+  if ("handled" in effectiveSession) {
+    return effectiveSession;
   }
+  let newSession;
+  const response = await context.promptQueue.enqueue(async () => {
+    const previousSessionFile = effectiveSession.session.sessionFile;
+    await effectiveSession.session.abort();
+    effectiveSession.session.dispose();
+    const sessionDir = sessionDirForScope(context.agentService.getAgentDir(), context.scope);
+    newSession = await context.agentService.createSession(sessionDir);
+    return `Started a fresh session. Old session kept at ${previousSessionFile ?? "(unknown path)"}.`;
+  });
   return {
     handled: true,
-    response: await context.promptQueue.enqueue(async () => {
-      return context.agentService.resetSession();
-    })
+    response,
+    newSession
   };
 }
 async function handleReactionCommand(trimmedInput, _context) {
@@ -959,7 +1205,7 @@ async function executeSessionCommand(input, context) {
 }
 
 // src/discord-attachments.ts
-var logger6 = createModuleLogger("discord-attachments");
+var logger8 = createModuleLogger("discord-attachments");
 var TEXT_ATTACHMENT_EXTENSIONS = [
   ".txt",
   ".md",
@@ -1021,11 +1267,11 @@ async function readTextAttachments(message) {
   const results = [];
   for (const [, attachment] of attachments) {
     if (!isSupportedTextAttachment(attachment)) {
-      logger6.debug({ messageId: message.id, filename: attachment.name }, "skipping non-text attachment");
+      logger8.debug({ messageId: message.id, filename: attachment.name }, "skipping non-text attachment");
       continue;
     }
     if (attachment.size > MAX_TEXT_ATTACHMENT_SIZE_BYTES) {
-      logger6.warn({
+      logger8.warn({
         messageId: message.id,
         filename: attachment.name,
         size: attachment.size
@@ -1033,14 +1279,14 @@ async function readTextAttachments(message) {
       continue;
     }
     try {
-      logger6.info({
+      logger8.info({
         messageId: message.id,
         filename: attachment.name,
         size: attachment.size
       }, "fetching attachment");
       const response = await fetch(attachment.url);
       if (!response.ok) {
-        logger6.warn({
+        logger8.warn({
           messageId: message.id,
           filename: attachment.name,
           status: response.status
@@ -1050,7 +1296,7 @@ async function readTextAttachments(message) {
       const content = await response.text();
       results.push({ filename: attachment.name, content });
     } catch (error) {
-      logger6.error({ messageId: message.id, filename: attachment.name, error }, "error fetching attachment");
+      logger8.error({ messageId: message.id, filename: attachment.name, error }, "error fetching attachment");
     }
   }
   return results;
@@ -1066,7 +1312,7 @@ async function readMediaAttachments(message) {
       continue;
     }
     if (attachment.size > MAX_MEDIA_ATTACHMENT_SIZE_BYTES) {
-      logger6.warn({
+      logger8.warn({
         messageId: message.id,
         filename: attachment.name,
         size: attachment.size
@@ -1074,14 +1320,14 @@ async function readMediaAttachments(message) {
       continue;
     }
     try {
-      logger6.info({
+      logger8.info({
         messageId: message.id,
         filename: attachment.name,
         size: attachment.size
       }, "fetching media attachment");
       const response = await fetch(attachment.url);
       if (!response.ok) {
-        logger6.warn({
+        logger8.warn({
           messageId: message.id,
           filename: attachment.name,
           status: response.status
@@ -1095,7 +1341,7 @@ async function readMediaAttachments(message) {
         mimeType: attachment.contentType ?? "application/octet-stream"
       });
     } catch (error) {
-      logger6.error({ messageId: message.id, filename: attachment.name, error }, "error fetching media attachment");
+      logger8.error({ messageId: message.id, filename: attachment.name, error }, "error fetching media attachment");
     }
   }
   return results;
@@ -1133,140 +1379,8 @@ function isAuthorizedMessage(message, scope, accessConfig) {
   return false;
 }
 
-// src/message-chunker.ts
-import { marked } from "marked";
-var DISCORD_MESSAGE_LIMIT = 2000;
-var SAFE_MESSAGE_LIMIT = 1900;
-function chunkMessage(text, maxChunkSize = SAFE_MESSAGE_LIMIT) {
-  if (text.length <= maxChunkSize) {
-    return [text];
-  }
-  const tokens = marked.lexer(text);
-  const chunks = [];
-  let currentTokens = [];
-  let currentSize = 0;
-  const flushChunk = () => {
-    if (currentTokens.length > 0) {
-      chunks.push(currentTokens.map((t) => t.raw).join("").trim());
-      currentTokens = [];
-      currentSize = 0;
-    }
-  };
-  for (const token of tokens) {
-    const size = token.raw.length;
-    if (currentSize + size > maxChunkSize && currentTokens.length > 0) {
-      flushChunk();
-    }
-    currentTokens.push(token);
-    currentSize += size;
-  }
-  flushChunk();
-  return chunks.map((chunk) => chunk.slice(0, DISCORD_MESSAGE_LIMIT));
-}
-
-// src/discord-replies.ts
-var logger7 = createModuleLogger("discord-replies");
-var DISCORD_MESSAGE_LIMIT2 = 2000;
-var FENCE_OVERHEAD = 8;
-var MAX_CODE_FENCE_CONTENT = DISCORD_MESSAGE_LIMIT2 - FENCE_OVERHEAD;
-function chunkByLines(text, maxSize) {
-  const lines = text.split(`
-`);
-  const chunks = [];
-  let current = "";
-  for (const line of lines) {
-    const candidate = current ? current + `
-` + line : line;
-    if (candidate.length > maxSize) {
-      if (current) {
-        chunks.push(current);
-        current = line;
-      } else {
-        chunks.push(line.slice(0, maxSize));
-        current = line.slice(maxSize);
-      }
-    } else {
-      current = candidate;
-    }
-  }
-  if (current) {
-    chunks.push(current);
-  }
-  return chunks;
-}
-var DEFAULT_WORKING_EMOJI = "⚙️";
-async function addWorkingReaction(message, emoji = DEFAULT_WORKING_EMOJI) {
-  try {
-    await message.react(emoji);
-  } catch (error) {
-    logger7.debug({ messageId: message.id, error }, "failed to add working reaction");
-  }
-}
-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) {
-    logger7.debug({ messageId: message.id, error }, "failed to remove working reaction");
-  }
-}
-async function sendReply(message, text) {
-  const channel = message.channel;
-  if (!channel.isSendable()) {
-    logger7.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) {
-    logger7.error({
-      messageId: message.id,
-      error
-    }, "send reply failed");
-  }
-}
-async function sendCommandReply(message, text) {
-  const channel = message.channel;
-  if (!channel.isSendable()) {
-    logger7.debug({
-      messageId: message.id
-    }, "command reply skipped, channel not sendable");
-    return;
-  }
-  const chunks = chunkByLines(text, MAX_CODE_FENCE_CONTENT).map((c) => `\`\`\`
-${c}
-\`\`\``);
-  const [firstChunk, ...remainingChunks] = chunks;
-  if (!firstChunk) {
-    return;
-  }
-  try {
-    await message.reply(firstChunk);
-    for (const chunk of remainingChunks) {
-      await channel.send(chunk);
-    }
-  } catch (error) {
-    logger7.error({
-      messageId: message.id,
-      error
-    }, "send command reply failed");
-  }
-}
-
 // src/media-description.ts
-var logger8 = createModuleLogger("media-description");
+var logger9 = createModuleLogger("media-description");
 async function describeMediaAttachment(agentService, imageData, mimeType, userText, visionModel) {
   const session = await agentService.createTemporarySession();
   await session.setModel(visionModel);
@@ -1287,7 +1401,7 @@ async function describeMediaAttachment(agentService, imageData, mimeType, userTe
     await session.prompt(promptText, { images: [imageContent] });
     text = extractLastAssistantText(session);
   } catch (error) {
-    logger8.error({ error, mimeType }, "vision model prompt failed");
+    logger9.error({ error, mimeType }, "vision model prompt failed");
     text = "(Vision model failed to process the file.)";
   } finally {
     session.dispose();
@@ -1295,7 +1409,7 @@ async function describeMediaAttachment(agentService, imageData, mimeType, userTe
   if (!text) {
     return "(Vision model returned no description.)";
   }
-  logger8.debug({ textLength: text.length, mimeType }, "media described");
+  logger9.debug({ textLength: text.length, mimeType }, "media described");
   return text;
 }
 function extractLastAssistantText(session) {
@@ -1331,7 +1445,7 @@ function isAssistantMessage(msg) {
 }
 
 // src/discord-media-resolution.ts
-var logger9 = createModuleLogger("discord-media-resolution");
+var logger10 = createModuleLogger("discord-media-resolution");
 function parseProviderModelId(value) {
   const trimmed = value.trim();
   if (!trimmed) {
@@ -1365,7 +1479,7 @@ async function resolveMediaAttachmentsForPrompt(mediaAttachments, content, curre
   const modelSupportsVision = currentModel?.input.includes("image") ?? false;
   if (modelSupportsVision) {
     const names = mediaAttachments.map((media) => media.filename).join(", ");
-    logger9.info({
+    logger10.info({
       count: mediaAttachments.length,
       filenames: names,
       model: currentModel ? `${currentModel.provider}/${currentModel.id}` : "none"
@@ -1381,7 +1495,7 @@ async function resolveMediaAttachmentsForPrompt(mediaAttachments, content, curre
   }
   if (!config.visionModelId) {
     const names = mediaAttachments.map((media) => media.filename).join(", ");
-    logger9.info({ filenames: names }, "media attachments received but vision model not configured");
+    logger10.info({ filenames: names }, "media attachments received but vision model not configured");
     const note = `
 
 [User sent media attachment(s): ${names}]
@@ -1397,7 +1511,7 @@ async function resolveMediaAttachmentsForPrompt(mediaAttachments, content, curre
   }
   const visionModel = agentService.models.findModel(parsedVisionModelId.provider, parsedVisionModelId.modelId);
   if (!visionModel) {
-    logger9.warn({ visionModelId: config.visionModelId }, "vision model not found in registry");
+    logger10.warn({ visionModelId: config.visionModelId }, "vision model not found in registry");
     const names = mediaAttachments.map((media) => media.filename).join(", ");
     const note = `
 
@@ -1408,7 +1522,7 @@ async function resolveMediaAttachmentsForPrompt(mediaAttachments, content, curre
       images: []
     };
   }
-  logger9.info({
+  logger10.info({
     count: mediaAttachments.length,
     visionModel: `${visionModel.provider}/${visionModel.id}`
   }, "describing media with vision model");
@@ -1435,7 +1549,7 @@ ${content}` : descriptionPrefix,
 }
 
 // src/discord-typing.ts
-var logger10 = createModuleLogger("discord-typing");
+var logger11 = createModuleLogger("discord-typing");
 var TYPING_INTERVAL_MS = 9000;
 var typingIntervals = new Map;
 async function sendTypingSafe(channel, channelKey) {
@@ -1458,18 +1572,18 @@ async function sendTypingSafe(channel, channelKey) {
           retryMs = parsed.retry_after * 1000 + 500;
         }
       } catch {}
-      logger10.warn({ channelKey, retryMs, response: body }, `[TYPING] 429, retrying after ${retryMs}ms delay`);
+      logger11.warn({ channelKey, retryMs, response: body }, `[TYPING] 429, retrying after ${retryMs}ms delay`);
       await new Promise((resolve) => setTimeout(resolve, retryMs));
       await fetch(url, {
         method: "POST",
         headers: { Authorization: `Bot ${token}` }
       });
-      logger10.warn({ channelKey }, "[TYPING] retry done");
+      logger11.warn({ channelKey }, "[TYPING] retry done");
       return;
     }
-    logger10.warn({ channelKey, status: response.status }, "[TYPING] unexpected status");
+    logger11.warn({ channelKey, status: response.status }, "[TYPING] unexpected status");
   } catch (error) {
-    logger10.error({ channelKey, error }, "[TYPING] FAILED");
+    logger11.error({ channelKey, error }, "[TYPING] FAILED");
   }
 }
 function startTypingForChannel(channel, channelKey) {
@@ -1478,7 +1592,7 @@ function startTypingForChannel(channel, channelKey) {
     existing.refs += 1;
     return;
   }
-  logger10.debug("[TYPING] started new interval");
+  logger11.debug("[TYPING] started new interval");
   sendTypingSafe(channel, channelKey);
   const interval = setInterval(() => {
     sendTypingSafe(channel, channelKey);
@@ -1499,31 +1613,6 @@ function stopTypingForChannel(channelKey) {
 }
 
 // src/prompt-context.ts
-function buildDiscordMessageContextPrompt(userMessage, options) {
-  const contextEntries = [
-    ["scope", options.scope],
-    ["sent_at", options.sentAt],
-    ["sent_at_local", options.sentAtLocal],
-    ["message_id", options.messageId],
-    ["author_name", normalizeContextValue(options.authorName)],
-    ["author_id", options.authorId],
-    ["thread_title", normalizeContextValue(options.threadTitle)],
-    ["thread_id", options.threadId],
-    ["forum_channel_id", options.forumChannelId ?? undefined]
-  ].filter((entry) => {
-    return typeof entry[1] === "string" && entry[1].trim().length > 0;
-  });
-  const contextJson = JSON.stringify(Object.fromEntries(contextEntries), null, 2);
-  return [
-    "<discord_message_context>",
-    contextJson,
-    "</discord_message_context>",
-    "",
-    "User message:",
-    userMessage.trim()
-  ].join(`
-`);
-}
 function formatDiscordPromptTime(date, options = {}) {
   const timeZone = options.timeZone || "UTC";
   const locale = options.locale || "en-AU";
@@ -1539,31 +1628,38 @@ function formatDiscordPromptTime(date, options = {}) {
     timeZoneName: "short"
   }).format(date);
 }
-function normalizeContextValue(value) {
-  if (value === undefined) {
-    return;
-  }
-  return value.replace(/\s+/g, " ").trim();
+function wrapXmlTag(tag, content) {
+  return `<${tag}>${content}</${tag}>`;
 }
 
 // src/discord-message-handler.ts
-var logger11 = createModuleLogger("discord-message-handler");
-function buildDiscordPromptContent(message, scope, content, config) {
+var logger12 = createModuleLogger("discord-message-handler");
+function formatDiscordMessageMetadata(message, scope) {
   const isThread = scope.startsWith("thread:") && message.channel.isThread();
-  return buildDiscordMessageContextPrompt(content, {
-    scope: scope === "dm" ? "dm" : "thread",
-    sentAt: message.createdAt.toISOString(),
-    sentAtLocal: formatDiscordPromptTime(message.createdAt, {
-      timeZone: config.promptTimeZone,
-      locale: config.promptLocale
-    }),
-    messageId: message.id,
-    authorId: message.author.id,
-    authorName: getAuthorDisplayName(message),
-    threadId: isThread ? message.channel.id : undefined,
-    threadTitle: isThread ? message.channel.name : undefined,
-    forumChannelId: isThread ? message.channel.parentId : undefined
+  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>`;
 }
 async function handleDiscordMessage(message, config, agentService, sessionRegistry, accessConfig) {
   if (message.author.bot) {
@@ -1574,14 +1670,14 @@ async function handleDiscordMessage(message, config, agentService, sessionRegist
   }
   const scope = resolveMessageScope(message);
   if (scope === null) {
-    logger11.debug({
+    logger12.debug({
       messageId: message.id,
       channelType: message.channel.type
     }, "unsupported channel type, ignoring");
     return;
   }
   if (!isAuthorizedMessage(message, scope, accessConfig)) {
-    logger11.debug({
+    logger12.debug({
       messageId: message.id,
       authorId: message.author.id,
       scope
@@ -1601,10 +1697,10 @@ ${attachment.content}`;
   }
   const mediaAttachments = await readMediaAttachments(message);
   if (!content && mediaAttachments.length === 0) {
-    logger11.debug({ messageId: message.id }, "ignored empty message (no text or images)");
+    logger12.debug({ messageId: message.id }, "ignored empty message (no text or images)");
     return;
   }
-  logger11.info({
+  logger12.info({
     scope,
     content
   }, "message received");
@@ -1615,7 +1711,7 @@ ${attachment.content}`;
   const { entry, created } = await sessionRegistry.getOrCreate(scope);
   const { session, promptQueue } = entry;
   if (created && scope.startsWith("thread:") && message.channel.isThread()) {
-    logger11.info({
+    logger12.info({
       scope,
       threadName: message.channel.name
     }, "new thread session");
@@ -1624,16 +1720,21 @@ ${attachment.content}`;
     agentService,
     promptQueue,
     session,
+    scope,
     workingEmoji: entry.workingEmoji
   });
   if (commandResult.handled) {
     stopTypingForChannel(channelKey);
     if (commandResult.workingEmoji) {
       entry.workingEmoji = commandResult.workingEmoji;
-      logger11.info({ scope, emoji: commandResult.workingEmoji }, "working emoji updated");
+      logger12.info({ scope, emoji: commandResult.workingEmoji }, "working emoji updated");
+    }
+    if (commandResult.newSession) {
+      entry.session = commandResult.newSession;
+      logger12.info({ scope, sessionId: commandResult.newSession.sessionId }, "session replaced");
     }
     if (commandResult.archive && scope.startsWith("thread:")) {
-      logger11.info({ scope }, "archiving thread");
+      logger12.info({ scope }, "archiving thread");
       const archiveChannel = message.channel;
       if (archiveChannel.isSendable()) {
         await archiveChannel.send(`\`\`\`
@@ -1645,12 +1746,12 @@ ${commandResult.response ?? "Archiving..."}
           await archiveChannel.setArchived(true);
         }
       } catch (error) {
-        logger11.error({ error }, "failed to archive thread");
+        logger12.error({ error }, "failed to archive thread");
       }
       await sessionRegistry.remove(scope);
       return;
     }
-    logger11.info({
+    logger12.info({
       messageId: message.id,
       command: content,
       hasResponse: Boolean(commandResult.response)
@@ -1662,7 +1763,7 @@ ${commandResult.response ?? "Archiving..."}
   }
   if (!message.channel.isSendable()) {
     stopTypingForChannel(channelKey);
-    logger11.debug({ messageId: message.id }, "channel not sendable");
+    logger12.debug({ messageId: message.id }, "channel not sendable");
     return;
   }
   await addWorkingReaction(message, entry.workingEmoji);
@@ -1682,8 +1783,16 @@ ${commandResult.response ?? "Archiving..."}
           promptImages = resolvedPromptMedia.images;
         }
       }
-      const wrappedContent = buildDiscordPromptContent(message, scope, promptContent, config);
-      const transformedPrompt = await config.promptTransform(wrappedContent);
+      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
       });
@@ -1696,7 +1805,7 @@ ${commandResult.response ?? "Archiving..."}
 }
 
 // src/discord-gateway-client.ts
-var logger12 = createModuleLogger("discord-gateway");
+var logger13 = createModuleLogger("discord-gateway");
 async function startGatewayClient(config, agentService, sessionRegistry, accessConfig) {
   const client = new Client({
     intents: [
@@ -1708,7 +1817,7 @@ async function startGatewayClient(config, agentService, sessionRegistry, accessC
     partials: [Partials.Channel]
   });
   client.once(Events.ClientReady, async (readyClient) => {
-    logger12.info({ userTag: readyClient.user.tag }, "logged in");
+    logger13.info({ userTag: readyClient.user.tag }, "logged in");
     if (!accessConfig.startupMessage) {
       return;
     }
@@ -1716,137 +1825,30 @@ async function startGatewayClient(config, agentService, sessionRegistry, accessC
       const user = await readyClient.users.fetch(accessConfig.discordAllowedUserId);
       const dmChannel = await user.createDM();
       await dmChannel.send(accessConfig.startupMessage);
-      logger12.info({
+      logger13.info({
         userId: accessConfig.discordAllowedUserId
       }, "sent startup dm");
     } catch (error) {
-      logger12.error({ error }, "failed to send startup dm");
+      logger13.error({ error }, "failed to send startup dm");
     }
   });
   client.on(Events.MessageCreate, async (message) => {
     try {
       await handleDiscordMessage(message, config, agentService, sessionRegistry, accessConfig);
     } catch (error) {
-      logger12.error({ error, direction: "IN" }, "message handling failed");
+      logger13.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}`;
-    logger12.info({ threadId: thread.id, scope }, "thread deleted");
+    logger13.info({ threadId: thread.id, scope }, "thread deleted");
     await sessionRegistry.remove(scope);
   });
   await client.login(config.discordBotToken);
   return client;
 }
 
-// src/session-registry.ts
-import path3 from "node:path";
-
-// src/prompt-queue.ts
-class PromptQueue {
-  queue = [];
-  running = false;
-  enqueue(task) {
-    return new Promise((resolve, reject) => {
-      this.queue.push(async () => {
-        try {
-          resolve(await task());
-        } catch (error) {
-          reject(error);
-        }
-      });
-      this.runNextTask();
-    });
-  }
-  getSnapshot() {
-    return {
-      pending: this.queue.length,
-      busy: this.running
-    };
-  }
-  runNextTask() {
-    if (this.running) {
-      return;
-    }
-    const next = this.queue.shift();
-    if (!next) {
-      return;
-    }
-    this.running = true;
-    next().finally(() => {
-      this.running = false;
-      this.runNextTask();
-    });
-  }
-}
-
-// src/session-registry.ts
-function sessionDirForScope(agentDir, scope) {
-  if (scope === "dm") {
-    return path3.join(agentDir, "sessions");
-  }
-  if (scope.startsWith("thread:")) {
-    const threadId = scope.slice(7);
-    return path3.join(agentDir, "sessions", `thread-${threadId}`);
-  }
-  throw new Error(`Unknown session scope: ${scope}`);
-}
-var logger13 = createModuleLogger("session-registry");
-
-class SessionRegistry {
-  scopes = new Map;
-  agentService;
-  constructor(agentService) {
-    this.agentService = agentService;
-  }
-  async getOrCreate(scope) {
-    const existing = this.scopes.get(scope);
-    if (existing) {
-      return { entry: existing, created: false };
-    }
-    const sessionDir = sessionDirForScope(this.agentService.getAgentDir(), scope);
-    const session = await this.agentService.createSession(sessionDir);
-    const promptQueue = new PromptQueue;
-    const entry = {
-      session,
-      promptQueue,
-      createdAt: new Date,
-      workingEmoji: DEFAULT_WORKING_EMOJI
-    };
-    this.scopes.set(scope, entry);
-    logger13.debug({
-      scope,
-      sessionDir,
-      sessionId: session.sessionId
-    }, "scope registered");
-    return { entry, created: true };
-  }
-  async remove(scope) {
-    const entry = this.scopes.get(scope);
-    if (!entry) {
-      return;
-    }
-    logger13.debug({ scope }, "removing scope");
-    await entry.session.abort();
-    entry.session.dispose();
-    this.scopes.delete(scope);
-  }
-  get(scope) {
-    return this.scopes.get(scope);
-  }
-  getScopes() {
-    return Array.from(this.scopes.keys());
-  }
-  async shutdownAll() {
-    logger13.info({ count: this.scopes.size }, "shutting down all scopes");
-    const scopes = Array.from(this.scopes.keys());
-    for (const scope of scopes) {
-      await this.remove(scope);
-    }
-  }
-}
-
 // src/index.ts
 var logger14 = createModuleLogger("index");
 async function startDiscordGateway(config) {
@@ -1910,6 +1912,5 @@ export {
   startDiscordGateway,
   resolveConfig,
   loadDiscordGatewayConfigFromEnv,
-  formatDiscordPromptTime,
-  buildDiscordMessageContextPrompt
+  formatDiscordPromptTime
 };

package/dist/prompt-context.d.ts

@@ -2,17 +2,6 @@ export type DiscordPromptTimeFormatOptions = {
     timeZone?: string;
     locale?: string;
 };
-export type DiscordPromptScope = "dm" | "thread";
-export type DiscordMessageContextPromptOptions = {
-    scope: DiscordPromptScope;
-    messageId: string;
-    authorId: string;
-    sentAt?: string;
-    sentAtLocal?: string;
-    authorName?: string;
-    threadId?: string;
-    threadTitle?: string;
-    forumChannelId?: string | null;
-};
-export declare function buildDiscordMessageContextPrompt(userMessage: string, options: DiscordMessageContextPromptOptions): string;
 export declare function formatDiscordPromptTime(date: Date, options?: DiscordPromptTimeFormatOptions): string;
+/** Wrap content in an XML-style tag: `<tag>content</tag>`. */
+export declare function wrapXmlTag(tag: string, content: string): string;

package/dist/session-commands.d.ts

@@ -1,6 +1,7 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { AgentService } from "./agent-service";
 import type { PromptQueue } from "./prompt-queue";
+import type { SessionScope } from "./session-registry";
 export type CommandResult = {
     handled: boolean;
     response?: string;
@@ -8,11 +9,15 @@ export type CommandResult = {
     archive?: boolean;
     /** When set, update the session's working reaction emoji. */
     workingEmoji?: string;
+    /** When set, the command created a new session that should replace the current one. */
+    newSession?: AgentSession;
 };
 export type CommandContext = {
     agentService: AgentService;
     promptQueue: PromptQueue;
     session?: AgentSession;
+    /** Session scope ("dm" or "thread:<id>") for session lifecycle commands. */
+    scope: SessionScope;
     /** Current working reaction emoji for this session. */
     workingEmoji: string;
 };

package/dist/types.d.ts

@@ -1,5 +1,18 @@
 import type { Client } from "discord.js";
-export type PromptTransform = (input: string) => string | Promise<string>;
+/** Context object passed to promptTransform so consumers can optionally
+ * wrap the raw content with Discord metadata. */
+export type PromptTransformContext = {
+    /** The raw user content without any XML wrapping. */
+    rawContent: string;
+    /** XML string with Discord message metadata (context JSON block). */
+    discordMetadata: string;
+    /** Returns current datetime formatted using the gateway config's
+     * promptTimeZone and promptLocale, wrapped in a <datetime> tag. */
+    now: () => string;
+    /** Returns rawContent wrapped in a <user_message> tag. */
+    userMessage: () => string;
+};
+export type PromptTransform = (ctx: PromptTransformContext) => string | Promise<string>;
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 export type DiscordGatewayConfig = {
     discordBotToken: string;

package/package.json

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