@friendlyrobot/discord-pi-agent 0.5.8 → 0.6.0

package/README.md

@@ -23,6 +23,31 @@ Reusable Discord gateway bridge for persistent pi agent sessions — DM and foru
 
 Any other text is sent to the active session (DM or thread).
 
+## Prompt metadata
+
+Every Discord prompt is wrapped with lightweight Discord context before `promptTransform` runs:
+
+```text
+<discord_message_context>
+{
+  "scope": "thread",
+  "sent_at": "2026-05-07T04:31:00.000Z",
+  "sent_at_local": "Thu, 7 May 26, 14:31 AEST",
+  "message_id": "...",
+  "author_name": "Alice",
+  "author_id": "...",
+  "thread_title": "Bug report",
+  "thread_id": "...",
+  "forum_channel_id": "..."
+}
+</discord_message_context>
+
+User message:
+...
+```
+
+DM prompts omit thread-only fields. `sent_at_local` uses `promptTimeZone` and `promptLocale`.
+
 ## Install
 
 ```bash
@@ -33,19 +58,14 @@ bun add @friendlyrobot/discord-pi-agent
 
 ```ts
 import {
-  buildTimeContextPrompt,
   loadDiscordGatewayConfigFromEnv,
   startDiscordGateway,
 } from "@friendlyrobot/discord-pi-agent";
 
 const config = loadDiscordGatewayConfigFromEnv({
   cwd: process.cwd(),
-  promptTransform: (input) => {
-    return buildTimeContextPrompt(input, {
-      timeZone: "Australia/Sydney",
-      locale: "en-AU",
-    });
-  },
+  promptTimeZone: "Australia/Sydney",
+  promptLocale: "en-AU",
   // Enable forum channel support (omit for DM-only)
   discordAllowedForumChannelIds: ["1498563501780897832"],
 });
@@ -70,6 +90,8 @@ The initial post body becomes the first prompt. Sessions survive restarts.
 - `modelProvider` default: `openrouter`
 - `modelId` default: `anthropic/claude-3.5-haiku`
 - `thinkingLevel` default: `medium` (values: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`)
+- `promptTimeZone` default: `UTC` — used for `sent_at_local` in Discord prompt metadata
+- `promptLocale` default: `en-AU` — used for `sent_at_local` in Discord prompt metadata
 - `promptTransform` default: identity
 - `startupMessage` default: `Bot is online and ready.`
 - `shutdownOnSignals` default: `true`
@@ -90,6 +112,8 @@ The initial post body becomes the first prompt. Sessions survive restarts.
 - `PI_AGENT_DIR`
 - `PI_MODEL_PROVIDER`
 - `PI_MODEL_ID`
+- `PI_PROMPT_TIME_ZONE`
+- `PI_PROMPT_LOCALE`
 - `DISCORD_STARTUP_MESSAGE`
 - `DISCORD_FORUM_CHANNEL_IDS` — comma-separated forum channel IDs
 - `DISCORD_ALLOWED_USER_IDS` — comma-separated allowed user IDs

package/dist/agent-service.d.ts

@@ -24,6 +24,9 @@ export declare class AgentService {
     private requireSession;
     private applyConfiguredThinkingLevel;
     private applyConfiguredThinkingLevelForSession;
+    listModels(): Promise<string>;
+    switchModel(provider: string, modelId: string): Promise<string>;
+    getCurrentModelDisplay(): string;
     getThinkingLevel(): {
         current: ThinkingLevel;
         available: ThinkingLevel[];

package/dist/discord-gateway-client.d.ts

@@ -8,8 +8,4 @@ export type GatewayAuthConfig = {
     discordAllowedUserIds: string[];
     startupMessage: string | false;
 };
-/**
- * Combine a forum thread title with the post body for the initial session prompt.
- */
-export declare function buildThreadOpeningPrompt(threadName: string, content: string): string;
 export declare function startGatewayClient(config: ResolvedDiscordPiBridgeConfig, agentService: AgentService, sessionRegistry: SessionRegistry, authConfig: GatewayAuthConfig): Promise<Client>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { DiscordGateway, DiscordGatewayConfig, DiscordPiBridge, DiscordPiBridgeConfig } from "./types";
-export { buildTimeContextPrompt, type TimeContextPromptOptions, } from "./prompt-context";
+export { buildDiscordMessageContextPrompt, formatDiscordPromptTime, type DiscordMessageContextPromptOptions, type DiscordPromptScope, type DiscordPromptTimeFormatOptions, } from "./prompt-context";
 export { loadDiscordPiBridgeConfigFromEnv, loadDiscordGatewayConfigFromEnv, resolveConfig, } from "./config";
 export type { AgentStatus, DiscordGateway, DiscordGatewayConfig, DiscordPiBridge, DiscordPiBridgeConfig, PromptTransform, ResolvedDiscordPiBridgeConfig, } from "./types";
 /**

package/dist/index.js

@@ -361,6 +361,51 @@ class AgentService {
       }
     }
   }
+  async listModels() {
+    const availableModels = await this.modelRegistry.getAvailable();
+    const session = this.session;
+    const currentDisplay = session?.model ? `${session.model.provider}/${session.model.id}` : null;
+    const lines = availableModels.map((model) => {
+      const display = `${model.provider}/${model.id}`;
+      const marker = currentDisplay === display ? " (current)" : "";
+      return `  ${display}${marker}`;
+    });
+    return [
+      `Available models (${availableModels.length}):`,
+      ...lines,
+      `
+Usage: !model <provider/modelId> to switch.`
+    ].join(`
+`);
+  }
+  async switchModel(provider, modelId) {
+    const session = this.requireSession();
+    const model = this.modelRegistry.find(provider, modelId);
+    if (!model) {
+      const availableModels = await this.modelRegistry.getAvailable();
+      const matches = availableModels.filter((m) => {
+        return m.provider === provider;
+      }).map((m) => `${m.provider}/${m.id}`);
+      const hint = matches.length > 0 ? `
+Models from "${provider}": ${matches.join(", ")}` : `
+Use !model to see all available models.`;
+      return `Model not found: ${provider}/${modelId}.${hint}`;
+    }
+    if (isSameModel(session.model, model)) {
+      return `Already using ${provider}/${modelId}.`;
+    }
+    await session.setModel(model);
+    await this.applyConfiguredThinkingLevelForSession(session);
+    const thinkingInfo = session.supportsThinking() ? ` (thinking: ${session.thinkingLevel})` : "";
+    return `Switched to ${provider}/${modelId}${thinkingInfo}.`;
+  }
+  getCurrentModelDisplay() {
+    const session = this.session;
+    if (!session?.model) {
+      return "(no model selected)";
+    }
+    return `${session.model.provider}/${session.model.id}`;
+  }
   getThinkingLevel() {
     const session = this.requireSession();
     if (!session.supportsThinking()) {
@@ -407,6 +452,8 @@ function resolveConfig(config) {
     modelProvider: config.modelProvider?.trim() || "openrouter",
     modelId: config.modelId?.trim() || "anthropic/claude-3.5-haiku",
     thinkingLevel: parseThinkingLevel(config.thinkingLevel) || "medium",
+    promptTimeZone: config.promptTimeZone?.trim() || "UTC",
+    promptLocale: config.promptLocale?.trim() || "en-AU",
     promptTransform: config.promptTransform || identityPromptTransform,
     startupMessage: config.startupMessage === undefined ? "Bot is online and ready." : config.startupMessage,
     shutdownOnSignals: config.shutdownOnSignals ?? true
@@ -422,6 +469,8 @@ function loadDiscordPiBridgeConfigFromEnv(overrides = {}) {
     modelProvider: overrides.modelProvider || process.env.PI_MODEL_PROVIDER,
     modelId: overrides.modelId || process.env.PI_MODEL_ID,
     thinkingLevel: parseThinkingLevel(overrides.thinkingLevel || process.env.PI_THINKING_LEVEL),
+    promptTimeZone: overrides.promptTimeZone || process.env.PI_PROMPT_TIME_ZONE,
+    promptLocale: overrides.promptLocale || process.env.PI_PROMPT_LOCALE,
     promptTransform: overrides.promptTransform,
     startupMessage: overrides.startupMessage ?? readStartupMessageFromEnv(),
     shutdownOnSignals: overrides.shutdownOnSignals
@@ -558,6 +607,7 @@ async function handleCommand(input, ctx) {
         "!help - show this message",
         "!status - show current session status",
         "!thinking - show or set thinking/reasoning level",
+        "!model - list available models or switch to one",
         "!compact - compact the persistent session",
         "!reset-session - start a fresh persistent session",
         "!reload - reload resources (AGENTS.md, extensions, skills, etc.)",
@@ -640,6 +690,42 @@ async function handleCommand(input, ctx) {
       response: `Thinking level set to "${requestedLevel}".`
     };
   }
+  if (trimmed === "!model" || trimmed.startsWith("!model ")) {
+    const effectiveSession = session ?? agentService.getSession();
+    if (!effectiveSession) {
+      return {
+        handled: true,
+        response: "No active session."
+      };
+    }
+    const parts = trimmed.split(" ");
+    if (parts.length === 1) {
+      const current = agentService.getCurrentModelDisplay();
+      const modelList = await agentService.listModels();
+      return {
+        handled: true,
+        response: `Current model: ${current}
+
+${modelList}`
+      };
+    }
+    const arg = parts.slice(1).join(" ");
+    const slashIndex = arg.indexOf("/");
+    if (slashIndex === -1) {
+      return {
+        handled: true,
+        response: `Usage: !model <provider/modelId>
+Example: !model openrouter/anthropic/claude-sonnet-4
+Use !model without args to see available models.`
+      };
+    }
+    const provider = arg.substring(0, slashIndex);
+    const modelId = arg.substring(slashIndex + 1);
+    return {
+      handled: true,
+      response: await agentService.switchModel(provider, modelId)
+    };
+  }
   if (trimmed === "!compact") {
     const effectiveSession = session ?? agentService.getSession();
     if (!effectiveSession) {
@@ -720,11 +806,74 @@ function chunkMessage(text, maxChunkSize = SAFE_MESSAGE_LIMIT) {
   return chunks.map((chunk) => chunk.slice(0, DISCORD_MESSAGE_LIMIT));
 }
 
-// src/discord-gateway-client.ts
-function buildThreadOpeningPrompt(threadName, content) {
-  return `<thread_title>${threadName}</thread_title>
+// 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";
+  return new Intl.DateTimeFormat(locale, {
+    timeZone,
+    weekday: "short",
+    day: "numeric",
+    month: "short",
+    year: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    timeZoneName: "short"
+  }).format(date);
+}
+function normalizeContextValue(value) {
+  if (value === undefined) {
+    return;
+  }
+  return value.replace(/\s+/g, " ").trim();
+}
 
-${content}`;
+// src/discord-gateway-client.ts
+function getAuthorDisplayName(message) {
+  return message.member?.displayName || message.author.globalName || message.author.username;
+}
+function buildDiscordPromptContent(message, scope, content, config) {
+  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
+  });
 }
 function resolveScope(message) {
   if (message.channel.type === ChannelType.DM) {
@@ -887,16 +1036,11 @@ async function onMessage(message, config, agentService, sessionRegistry, authCon
   }
   const { entry, created } = await sessionRegistry.getOrCreate(scope);
   const { session, promptQueue } = entry;
-  let effectiveContent = content;
-  if (created && scope.startsWith("thread:")) {
-    const thread = message.channel;
-    if (thread.isThread() && thread.name) {
-      effectiveContent = buildThreadOpeningPrompt(thread.name, content);
-      console.log("[gateway] new thread session — prepending title", {
-        scope,
-        threadName: thread.name
-      });
-    }
+  if (created && scope.startsWith("thread:") && message.channel.isThread()) {
+    console.log("[gateway] new thread session", {
+      scope,
+      threadName: message.channel.name
+    });
   }
   let typingInterval = null;
   if (message.channel.isSendable()) {
@@ -951,7 +1095,8 @@ async function onMessage(message, config, agentService, sessionRegistry, authCon
   }
   const response = await promptQueue.enqueue(async () => {
     console.log(`[queue] processing message ${message.id} in scope ${scope}`);
-    const transformedPrompt = await config.promptTransform(effectiveContent);
+    const promptContent = buildDiscordPromptContent(message, scope, content, config);
+    const transformedPrompt = await config.promptTransform(promptContent);
     return collectReply(session, transformedPrompt, {
       logPrefix: `[agent:${session.sessionId}]`
     });
@@ -1071,27 +1216,6 @@ class SessionRegistry {
   }
 }
 
-// src/prompt-context.ts
-function buildTimeContextPrompt(userMessage, options = {}) {
-  const timeZone = options.timeZone || "UTC";
-  const locale = options.locale || "en-AU";
-  const now = options.now || new Date;
-  const localTime = new Intl.DateTimeFormat(locale, {
-    timeZone,
-    weekday: "short",
-    day: "numeric",
-    month: "short",
-    year: "2-digit",
-    hour: "2-digit",
-    minute: "2-digit",
-    hour12: false,
-    timeZoneName: "short"
-  }).format(now);
-  const trimmedMessage = userMessage.trim();
-  return [`<time>${localTime}</time>`, "", trimmedMessage].join(`
-`);
-}
-
 // src/index.ts
 async function startDiscordGateway(config) {
   const resolvedConfig = resolveGatewayConfig(config);
@@ -1159,5 +1283,6 @@ export {
   resolveConfig,
   loadDiscordPiBridgeConfigFromEnv,
   loadDiscordGatewayConfigFromEnv,
-  buildTimeContextPrompt
+  formatDiscordPromptTime,
+  buildDiscordMessageContextPrompt
 };

package/dist/prompt-context.d.ts

@@ -1,6 +1,18 @@
-export type TimeContextPromptOptions = {
+export type DiscordPromptTimeFormatOptions = {
     timeZone?: string;
     locale?: string;
-    now?: Date;
 };
-export declare function buildTimeContextPrompt(userMessage: string, options?: TimeContextPromptOptions): 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;

package/dist/types.d.ts

@@ -9,6 +9,8 @@ export type DiscordPiBridgeConfig = {
     modelProvider?: string;
     modelId?: string;
     thinkingLevel?: ThinkingLevel;
+    promptTimeZone?: string;
+    promptLocale?: string;
     promptTransform?: PromptTransform;
     startupMessage?: string | false;
     shutdownOnSignals?: boolean;
@@ -21,6 +23,8 @@ export type ResolvedDiscordPiBridgeConfig = {
     modelProvider: string;
     modelId: string;
     thinkingLevel: ThinkingLevel;
+    promptTimeZone: string;
+    promptLocale: string;
     promptTransform: PromptTransform;
     startupMessage: string | false;
     shutdownOnSignals: boolean;

package/package.json

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

package/dist/discord-gateway-client.test.d.ts

@@ -1 +0,0 @@
-export {};