talon-agent 1.12.0 → 1.34.0

package/src/frontend/telegram/handlers/messages.ts

@@ -0,0 +1,477 @@
+/**
+ * Per-message-type handlers — text, photo, document, voice, sticker, video,
+ * animation, audio, video-note, and callback queries. Each validates access /
+ * rate limits, builds a prompt, and enqueues (or runs the agent directly for
+ * callback queries).
+ */
+
+import type { Bot, Context } from "grammy";
+import type { TalonConfig } from "../../../util/config.js";
+import { escapeHtml } from "../formatting.js";
+import { friendlyMessage } from "../../../core/errors.js";
+import { setMessageFilePath } from "../../../storage/history.js";
+import { addMedia } from "../../../storage/media-index.js";
+import { appendDailyLog } from "../../../storage/daily-log.js";
+import { logError } from "../../../util/log.js";
+import { recordMessageSignal } from "../../../core/soul/taps.js";
+import {
+  getSenderName,
+  getReplyContext,
+  getForwardContext,
+  downloadReplyPhoto,
+  downloadTelegramFile,
+} from "./context.js";
+import { shouldHandleInGroup, isAccessAllowed } from "./access.js";
+import { enqueueMessage, isUserRateLimited } from "./queue.js";
+import { ensurePackSaved } from "../sticker-library.js";
+import { processAndReply, sendHtml } from "./delivery.js";
+
+// ── Shared media handler ──────────────────────────────────────────────────────
+
+type MediaDescriptor = {
+  /** Human-readable media type for prompt (e.g. "photo", "video", "voice message"). */
+  type: string;
+  /** File ID to download from Telegram. */
+  fileId: string;
+  /** File name for saving locally. */
+  fileName: string;
+  /** Extra prompt lines describing the media. */
+  promptLines: string[];
+  /** Caption from the message, if any. */
+  caption?: string;
+  /** Optional file size check (reject if too large). */
+  fileSize?: number;
+};
+
+/**
+ * Shared handler for all downloadable media types (photo, document, voice, video, animation).
+ * Extracts forward/reply context, downloads the file, builds a prompt, and enqueues.
+ */
+async function handleMediaMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+  media: MediaDescriptor,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat) return;
+  if (ctx.from?.id && isUserRateLimited(ctx.from.id)) return;
+
+  const chatId = String(ctx.chat.id);
+  const isGroup = ctx.chat.type === "group" || ctx.chat.type === "supergroup";
+  const sender = getSenderName(ctx.from);
+  const senderUsername = ctx.from?.username;
+
+  try {
+    // File size check
+    if (media.fileSize && media.fileSize > 20 * 1024 * 1024) {
+      await sendHtml(
+        bot,
+        ctx.chat.id,
+        "File too large (max 20MB).",
+        ctx.message.message_id,
+      );
+      return;
+    }
+
+    const savedPath = await downloadTelegramFile(
+      bot,
+      config,
+      media.fileId,
+      media.fileName,
+    );
+
+    // Store file path in history + media index
+    setMessageFilePath(chatId, ctx.message.message_id, savedPath);
+    addMedia({
+      chatId,
+      msgId: ctx.message.message_id,
+      senderName: sender,
+      type: media.type as
+        | "photo"
+        | "document"
+        | "voice"
+        | "video"
+        | "animation"
+        | "audio"
+        | "sticker",
+      filePath: savedPath,
+      caption: media.caption,
+      timestamp: Date.now(),
+    });
+
+    const fwdCtx = getForwardContext(
+      ctx.message as Parameters<typeof getForwardContext>[0],
+    );
+    const replyCtx = getReplyContext(
+      ctx.message.reply_to_message as Parameters<typeof getReplyContext>[0],
+      ctx.me.id,
+      (ctx.message as { quote?: { text?: string; is_manual?: boolean } }).quote,
+    );
+    const replyPhotoCtx = await downloadReplyPhoto(
+      ctx.message.reply_to_message as Parameters<typeof downloadReplyPhoto>[0],
+      bot,
+      config,
+    );
+
+    const promptParts = [
+      fwdCtx,
+      replyCtx,
+      replyPhotoCtx,
+      ...media.promptLines.map((l) => l.replace("${savedPath}", savedPath)),
+      media.caption ? `Caption: ${media.caption}` : "",
+    ].filter(Boolean);
+
+    const prompt = promptParts.join("\n");
+
+    enqueueMessage(bot, config, chatId, ctx.chat.id, {
+      prompt,
+      replyToId: ctx.message.message_id,
+      messageId: ctx.message.message_id,
+      senderName: sender,
+      senderUsername,
+      senderId: ctx.from?.id,
+      isGroup,
+      chatTitle: isGroup ? (ctx.chat as { title?: string }).title : undefined,
+    });
+  } catch (err) {
+    logError(
+      "bot",
+      `[${chatId}] ${media.type} error (${sender}): ${err instanceof Error ? err.message : err}`,
+    );
+    await sendHtml(
+      bot,
+      ctx.chat.id,
+      escapeHtml(friendlyMessage(err)),
+      ctx.message.message_id,
+    );
+  }
+}
+
+// ── Text message handler ────────────────────────────────────────────────────
+
+export async function handleTextMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+  if (ctx.from?.id && isUserRateLimited(ctx.from.id)) return;
+
+  const chatId = String(ctx.chat.id);
+  const isGroup = ctx.chat.type === "group" || ctx.chat.type === "supergroup";
+  const sender = getSenderName(ctx.from);
+  const senderUsername = ctx.from?.username;
+
+  const replyCtx = getReplyContext(
+    ctx.message.reply_to_message as Parameters<typeof getReplyContext>[0],
+    ctx.me.id,
+    (ctx.message as { quote?: { text?: string; is_manual?: boolean } }).quote,
+  );
+  const replyPhotoCtx = await downloadReplyPhoto(
+    ctx.message.reply_to_message as Parameters<typeof downloadReplyPhoto>[0],
+    bot,
+    config,
+  );
+  const fwdCtx = getForwardContext(
+    ctx.message as Parameters<typeof getForwardContext>[0],
+  );
+  const prompt = fwdCtx + replyCtx + replyPhotoCtx + (ctx.message.text ?? "");
+
+  // Soul tap: a message reaching here is addressed to Talon (DM, mention, or
+  // reply). If it reads as a standing directive or a correction, record it as
+  // evidence. No-op unless the soul is enabled.
+  recordMessageSignal({
+    text: ctx.message.text ?? "",
+    actor: sender,
+    addressedToBot: true,
+  });
+
+  enqueueMessage(bot, config, chatId, ctx.chat.id, {
+    prompt,
+    replyToId: ctx.message.message_id,
+    messageId: ctx.message.message_id,
+    senderName: sender,
+    senderUsername,
+    senderId: ctx.from?.id,
+    isGroup,
+    chatTitle: isGroup ? (ctx.chat as { title?: string }).title : undefined,
+  });
+}
+
+export async function handlePhotoMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+
+  const photos = ctx.message.photo;
+  if (!photos?.length) return;
+  const bestPhoto = photos[photos.length - 1];
+  const caption = ctx.message.caption || "";
+
+  await handleMediaMessage(ctx, bot, config, {
+    type: "photo",
+    fileId: bestPhoto.file_id,
+    fileName: `photo_${bestPhoto.file_unique_id}.jpg`,
+    promptLines: [
+      "User sent a photo saved to: ${savedPath}",
+      "Read this file to view it. If you need to reference this image in future turns, re-read the file — image data does not persist between turns.",
+    ],
+    caption,
+  });
+}
+
+export async function handleDocumentMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+
+  const doc = ctx.message.document;
+  if (!doc) return;
+
+  const fileName = doc.file_name || `doc_${doc.file_unique_id}`;
+  const caption = ctx.message.caption || "";
+
+  await handleMediaMessage(ctx, bot, config, {
+    type: "document",
+    fileId: doc.file_id,
+    fileName,
+    fileSize: doc.file_size,
+    promptLines: [
+      `User sent a document: "${fileName}" (${doc.mime_type || "unknown"}).`,
+      "Saved to: ${savedPath}",
+      "Read and process this file.",
+    ],
+    caption,
+  });
+}
+
+export async function handleVoiceMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+
+  const voice = ctx.message.voice;
+  if (!voice) return;
+
+  await handleMediaMessage(ctx, bot, config, {
+    type: "voice",
+    fileId: voice.file_id,
+    fileName: `voice_${voice.file_unique_id}.ogg`,
+    promptLines: [
+      `User sent a voice message (${voice.duration}s).`,
+      "Audio saved to: ${savedPath}. You cannot transcribe audio — acknowledge it and respond based on context.",
+    ],
+  });
+}
+
+export async function handleStickerMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+
+  const chatId = String(ctx.chat.id);
+  const isGroup = ctx.chat.type === "group" || ctx.chat.type === "supergroup";
+  const sender = getSenderName(ctx.from);
+  const senderUsername = ctx.from?.username;
+
+  const sticker = ctx.message.sticker;
+  if (!sticker) return;
+
+  const emoji = sticker.emoji || "";
+  const setName = sticker.set_name || "";
+
+  // Grow the sticker library organically: any pack a user sends from
+  // gets saved in the background (skipped if already saved), so the
+  // model can later send from it by emoji without any browsing.
+  if (setName) void ensurePackSaved(bot, setName);
+
+  const prompt = [
+    `User sent a sticker: ${emoji}`,
+    `Sticker file_id: ${sticker.file_id}`,
+    setName ? `Sticker set: ${setName} (saved to your sticker library)` : "",
+    sticker.is_animated
+      ? "(animated)"
+      : sticker.is_video
+        ? "(video sticker)"
+        : "",
+    'You can send it back via send(type="sticker", file_id=...) — or send any sticker from your library by emoji.',
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  enqueueMessage(bot, config, chatId, ctx.chat.id, {
+    prompt,
+    replyToId: ctx.message.message_id,
+    messageId: ctx.message.message_id,
+    senderName: sender,
+    senderUsername,
+    senderId: ctx.from?.id,
+    isGroup,
+    chatTitle: isGroup ? (ctx.chat as { title?: string }).title : undefined,
+  });
+}
+
+export async function handleVideoMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+
+  const video = ctx.message.video;
+  if (!video) return;
+
+  const fileName = video.file_name || `video_${video.file_unique_id}.mp4`;
+  const caption = ctx.message.caption || "";
+
+  await handleMediaMessage(ctx, bot, config, {
+    type: "video",
+    fileId: video.file_id,
+    fileName,
+    promptLines: [
+      `User sent a video: "${fileName}" (${video.duration}s, ${video.width}x${video.height}).`,
+      "Saved to: ${savedPath}",
+    ],
+    caption,
+  });
+}
+
+export async function handleAnimationMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+
+  const anim = ctx.message.animation;
+  if (!anim) return;
+
+  const fileName = anim.file_name || `animation_${anim.file_unique_id}.mp4`;
+  const caption = ctx.message.caption || "";
+
+  await handleMediaMessage(ctx, bot, config, {
+    type: "animation",
+    fileId: anim.file_id,
+    fileName,
+    promptLines: [
+      `User sent a GIF/animation: "${fileName}" (${anim.duration}s).`,
+      "Saved to: ${savedPath}",
+      `file_id: ${anim.file_id} — re-send it anytime with send(type="animation", file_id=...).`,
+    ],
+    caption,
+  });
+}
+
+export async function handleAudioMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+  if (ctx.from?.id && isUserRateLimited(ctx.from.id)) return;
+
+  const audio = ctx.message.audio;
+  if (!audio) return;
+
+  const title = audio.title || audio.file_name || "audio";
+  const performer = audio.performer ? ` by ${audio.performer}` : "";
+  const fileName = audio.file_name || `audio_${audio.file_unique_id}.mp3`;
+  const caption = ctx.message.caption || "";
+
+  await handleMediaMessage(ctx, bot, config, {
+    type: "audio",
+    fileId: audio.file_id,
+    fileName,
+    fileSize: audio.file_size,
+    promptLines: [
+      `User sent an audio file: "${title}"${performer} (${audio.duration}s).`,
+      "Saved to: ${savedPath}",
+    ],
+    caption,
+  });
+}
+
+export async function handleVideoNoteMessage(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.message || !ctx.chat || !shouldHandleInGroup(ctx)) return;
+  if (!(await isAccessAllowed(ctx, bot))) return;
+  if (ctx.from?.id && isUserRateLimited(ctx.from.id)) return;
+
+  const videoNote = ctx.message.video_note;
+  if (!videoNote) return;
+
+  await handleMediaMessage(ctx, bot, config, {
+    type: "video note",
+    fileId: videoNote.file_id,
+    fileName: `videonote_${videoNote.file_unique_id}.mp4`,
+    fileSize: videoNote.file_size,
+    promptLines: [
+      `User sent a round video note (${videoNote.duration}s).`,
+      "Saved to: ${savedPath}",
+    ],
+  });
+}
+
+export async function handleCallbackQuery(
+  ctx: Context,
+  bot: Bot,
+  config: TalonConfig,
+): Promise<void> {
+  if (!ctx.callbackQuery || !("data" in ctx.callbackQuery)) return;
+
+  const chatId = String(ctx.chat?.id ?? ctx.from?.id);
+  const numericChatId = ctx.chat?.id ?? ctx.from?.id ?? 0;
+  const isGroup = ctx.chat?.type === "group" || ctx.chat?.type === "supergroup";
+  const sender = getSenderName(ctx.from);
+  const callbackData = ctx.callbackQuery.data;
+
+  // Acknowledge the callback immediately
+  await ctx.answerCallbackQuery().catch(() => {});
+
+  try {
+    const prompt = `[Button pressed] User clicked inline button with callback data: "${callbackData}"`;
+    const replyToId = ctx.callbackQuery.message?.message_id ?? 0;
+
+    const chatTitle = isGroup
+      ? (ctx.chat as { title?: string })?.title
+      : undefined;
+    appendDailyLog(sender, `Button: ${callbackData}`, { chatTitle });
+
+    await processAndReply({
+      bot,
+      config,
+      chatId,
+      numericChatId,
+      replyToId,
+      messageId: replyToId,
+      prompt,
+      senderName: sender,
+      isGroup,
+      chatTitle,
+    });
+  } catch (err) {
+    logError(
+      "bot",
+      `[${chatId}] Callback error (${sender}): ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}

package/src/frontend/telegram/handlers/queue.ts

@@ -0,0 +1,241 @@
+/**
+ * Message queue + per-user rate limiting.
+ *
+ * Debounces rapid-fire messages per chat (concatenating them into a single
+ * agent turn), tracks per-user rate limits, and surfaces a "messages were
+ * skipped" notice for groups.
+ */
+
+import type { Bot } from "grammy";
+import type { TalonConfig } from "../../../util/config.js";
+import { escapeHtml } from "../formatting.js";
+import { classify, friendlyMessage } from "../../../core/errors.js";
+import {
+  getRecentHistory,
+  type HistoryMessage,
+} from "../../../storage/history.js";
+import { recordMessageProcessed, recordError } from "../../../util/watchdog.js";
+import { log, logError, logWarn, logDebug } from "../../../util/log.js";
+import { appendDailyLog } from "../../../storage/daily-log.js";
+import { processAndReply, sendHtml } from "./delivery.js";
+import {
+  messageQueues,
+  lastHandledMessageIdByChat,
+  userMessageTimestamps,
+  DEBOUNCE_MS,
+  MAX_QUEUED_PER_CHAT,
+  RATE_LIMIT_WINDOW_MS,
+  RATE_LIMIT_MAX_MESSAGES,
+  type QueuedMessage,
+} from "./state.js";
+
+export function isUserRateLimited(senderId: number): boolean {
+  const now = Date.now();
+  let timestamps = userMessageTimestamps.get(senderId);
+  if (!timestamps) {
+    timestamps = [];
+    userMessageTimestamps.set(senderId, timestamps);
+  }
+
+  // Remove old entries outside the window
+  while (timestamps.length > 0 && timestamps[0] < now - RATE_LIMIT_WINDOW_MS) {
+    timestamps.shift();
+  }
+
+  if (timestamps.length >= RATE_LIMIT_MAX_MESSAGES) {
+    logDebug("bot", `Rate-limited user ${senderId}`);
+    return true;
+  }
+
+  timestamps.push(now);
+
+  // Evict stale entries — remove users who haven't messaged in 10+ minutes
+  if (userMessageTimestamps.size > 5_000) {
+    const cutoff = now - 10 * 60_000;
+    for (const [userId, ts] of userMessageTimestamps) {
+      if (ts.length === 0 || ts[ts.length - 1] < cutoff) {
+        userMessageTimestamps.delete(userId);
+      }
+      if (userMessageTimestamps.size <= 2_500) break; // evict down to half
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Enqueue a message for processing. If another message arrives within DEBOUNCE_MS,
+ * they are concatenated and sent as a single query to avoid duplicate SDK spawns.
+ * Queued messages get a hourglass reaction to indicate they've been seen.
+ */
+export function enqueueMessage(
+  bot: Bot,
+  config: TalonConfig,
+  chatId: string,
+  numericChatId: number,
+  msg: QueuedMessage,
+): void {
+  const existing = messageQueues.get(chatId);
+  if (existing) {
+    if (existing.messages.length >= MAX_QUEUED_PER_CHAT) return; // drop excess
+    existing.messages.push(msg);
+    // Show hourglass reaction on the queued message to indicate it's been seen
+    bot.api
+      .setMessageReaction(numericChatId, msg.messageId, [
+        {
+          type: "emoji",
+          emoji: "⏳" as "👍" /* grammY wants union type */,
+        },
+      ])
+      .catch(() => {});
+    existing.queuedReactionMsgIds.push(msg.messageId);
+    clearTimeout(existing.timer);
+    existing.timer = setTimeout(() => flushQueue(chatId), DEBOUNCE_MS);
+    return;
+  }
+
+  const entry = {
+    messages: [msg],
+    timer: setTimeout(() => flushQueue(chatId), DEBOUNCE_MS),
+    bot,
+    config,
+    numericChatId,
+    queuedReactionMsgIds: [] as number[],
+  };
+  messageQueues.set(chatId, entry);
+}
+
+async function flushQueue(chatId: string): Promise<void> {
+  const entry = messageQueues.get(chatId);
+  if (!entry) return;
+  messageQueues.delete(chatId);
+
+  const { messages, bot, config, numericChatId, queuedReactionMsgIds } = entry;
+
+  // Clear hourglass reactions on queued messages now that we're processing
+  for (const msgId of queuedReactionMsgIds) {
+    bot.api.setMessageReaction(numericChatId, msgId, []).catch((err) => {
+      logWarn(
+        "bot",
+        `Failed to clear reaction on msg ${msgId}: ${err instanceof Error ? err.message : err}`,
+      );
+    });
+  }
+
+  // Use last message's metadata for reply context
+  const first = messages[0];
+  const last = messages[messages.length - 1];
+
+  // Concatenate prompts (with newlines between them if multiple)
+  const combinedPrompt =
+    messages.length === 1
+      ? messages[0].prompt
+      : messages.map((m) => m.prompt).join("\n\n");
+  const groupGapContext = buildGroupGapContextNotice({
+    isGroup: last.isGroup,
+    chatId,
+    firstQueuedMessageId: first.messageId,
+    lastHandledMessageId: lastHandledMessageIdByChat.get(chatId),
+  });
+  const promptWithContext = groupGapContext
+    ? `${groupGapContext}\n\n${combinedPrompt}`
+    : combinedPrompt;
+
+  const chatContext = {
+    chatTitle: last.chatTitle,
+    username: last.senderUsername,
+  };
+  appendDailyLog(last.senderName, promptWithContext, chatContext);
+
+  const runTurn = () =>
+    processAndReply({
+      bot,
+      config,
+      chatId,
+      numericChatId,
+      replyToId: last.replyToId,
+      messageId: last.messageId,
+      prompt: promptWithContext,
+      senderName: last.senderName,
+      isGroup: last.isGroup,
+      senderUsername: last.senderUsername,
+      senderId: last.senderId,
+      chatTitle: last.chatTitle,
+    });
+
+  try {
+    await runTurn();
+    lastHandledMessageIdByChat.set(chatId, last.messageId);
+    recordMessageProcessed();
+  } catch (err) {
+    const classified = classify(err);
+    const chatType = last.isGroup ? "group" : "DM";
+    const promptPreview = promptWithContext.slice(0, 100).replace(/\n/g, " ");
+    logError(
+      "bot",
+      `[${chatId}] [${chatType}] [${last.senderName}] ${classified.reason}: ${classified.message} | prompt: "${promptPreview}"`,
+    );
+    recordError(classified.message);
+
+    // Retry once for transient errors (rate_limit, overloaded, network)
+    if (classified.retryable) {
+      const delayMs = classified.retryAfterMs ?? 2000;
+      log(
+        "bot",
+        `[${chatId}] Retrying after ${classified.reason} (${delayMs}ms)...`,
+      );
+      try {
+        await new Promise((r) => setTimeout(r, delayMs));
+        await runTurn();
+        lastHandledMessageIdByChat.set(chatId, last.messageId);
+        recordMessageProcessed();
+        return;
+      } catch (retryErr) {
+        const retryClassified = classify(retryErr);
+        logError(
+          "bot",
+          `[${chatId}] [${chatType}] Retry failed: ${retryClassified.message}`,
+        );
+        await sendHtml(
+          bot,
+          numericChatId,
+          escapeHtml(friendlyMessage(retryClassified)),
+          last.replyToId,
+        );
+        return;
+      }
+    }
+
+    await sendHtml(
+      bot,
+      numericChatId,
+      escapeHtml(friendlyMessage(classified)),
+      last.replyToId,
+    );
+  }
+}
+
+export function buildGroupGapContextNotice(inputs: {
+  isGroup: boolean;
+  chatId: string;
+  firstQueuedMessageId: number;
+  lastHandledMessageId?: number;
+  history?: HistoryMessage[];
+}): string {
+  if (!inputs.isGroup || inputs.lastHandledMessageId === undefined) return "";
+
+  const history = inputs.history ?? getRecentHistory(inputs.chatId, 100);
+  const interveningCount = history.filter(
+    (m) =>
+      m.msgId > inputs.lastHandledMessageId! &&
+      m.msgId < inputs.firstQueuedMessageId,
+  ).length;
+  if (interveningCount === 0) return "";
+
+  const noun = interveningCount === 1 ? "message" : "messages";
+  return (
+    `[Group context notice: ${interveningCount} ${noun} were sent in this ` +
+    "chat since your last handled turn. If this prompt is vague, ambiguous, " +
+    "or asks what you think, use read_chat_history before answering.]"
+  );
+}