talon-agent 3.21.0 → 3.22.1

package/src/frontend/telegram/actions/moderation.ts

@@ -0,0 +1,255 @@
+/**
+ * Moderation actions — the `moderate` tool's member/chat/topic operations,
+ * plus profile-photo lookup.
+ *
+ * Handlers call the Bot API directly and let Telegram's own errors surface
+ * (missing admin rights come back as descriptive 400s the model can read);
+ * pre-checking rights here would just race the real check.
+ */
+
+import type { ChatPermissions } from "grammy/types";
+import { toPositiveId } from "./shared.js";
+import { resolveMediaInput } from "./media.js";
+import { clearJoinRequest, listJoinRequests } from "../join-requests.js";
+import type { TelegramActionHandlers } from "./types.js";
+
+/** Seconds-from-now → Telegram until_date, honouring "omit = forever". */
+function untilDate(minutes: unknown): number | undefined {
+  const n = Number(minutes);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return Math.floor(Date.now() / 1000) + Math.round(n * 60);
+}
+
+/**
+ * Friendly permission names → ChatPermissions. `send_media` fans out to all
+ * the per-kind media flags; raw `can_*` keys pass through untouched so the
+ * full API surface stays reachable.
+ */
+function toChatPermissions(raw: Record<string, boolean>): ChatPermissions {
+  const out: Record<string, boolean> = {};
+  const alias: Record<string, string[]> = {
+    send_messages: ["can_send_messages"],
+    send_media: [
+      "can_send_audios",
+      "can_send_documents",
+      "can_send_photos",
+      "can_send_videos",
+      "can_send_video_notes",
+      "can_send_voice_notes",
+    ],
+    send_polls: ["can_send_polls"],
+    send_other: ["can_send_other_messages"],
+    web_previews: ["can_add_web_page_previews"],
+    change_info: ["can_change_info"],
+    invite_users: ["can_invite_users"],
+    pin_messages: ["can_pin_messages"],
+    manage_topics: ["can_manage_topics"],
+  };
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value !== "boolean") continue;
+    for (const target of alias[key] ?? (key.startsWith("can_") ? [key] : [])) {
+      out[target] = value;
+    }
+  }
+  return out;
+}
+
+/** Everything a mute takes away; unmute grants it back. */
+const FULL_MEMBER_PERMISSIONS: ChatPermissions = toChatPermissions({
+  send_messages: true,
+  send_media: true,
+  send_polls: true,
+  send_other: true,
+  web_previews: true,
+});
+
+/** The workaday admin kit `promote` grants; demote sets all of these false. */
+const DEFAULT_ADMIN_RIGHTS = {
+  can_manage_chat: true,
+  can_delete_messages: true,
+  can_restrict_members: true,
+  can_pin_messages: true,
+  can_invite_users: true,
+  can_change_info: true,
+  can_manage_topics: true,
+  can_manage_video_chats: true,
+};
+
+export const moderationHandlers: TelegramActionHandlers = {
+  moderate: async (body, chatId, ctx) => {
+    const { bot, InputFileClass } = ctx;
+    const op = String(body.op ?? "");
+    const userId = toPositiveId(body.user_id);
+    const needsUser = [
+      "ban",
+      "unban",
+      "mute",
+      "unmute",
+      "promote",
+      "demote",
+      "set_admin_title",
+      "approve_join_request",
+      "decline_join_request",
+    ];
+    if (needsUser.includes(op) && userId === undefined)
+      return { ok: false, error: `${op}: user_id is required` };
+
+    switch (op) {
+      case "ban":
+        await bot.api.banChatMember(chatId, userId!, {
+          until_date: untilDate(body.minutes),
+          revoke_messages: body.delete_messages === true || undefined,
+        });
+        return { ok: true };
+      case "unban":
+        // only_if_banned keeps this from kicking a current member.
+        await bot.api.unbanChatMember(chatId, userId!, {
+          only_if_banned: true,
+        });
+        return { ok: true };
+      case "mute":
+        await bot.api.restrictChatMember(
+          chatId,
+          userId!,
+          { can_send_messages: false },
+          { until_date: untilDate(body.minutes) },
+        );
+        return { ok: true };
+      case "unmute":
+        await bot.api.restrictChatMember(
+          chatId,
+          userId!,
+          FULL_MEMBER_PERMISSIONS,
+        );
+        return { ok: true };
+      case "promote":
+        await bot.api.promoteChatMember(chatId, userId!, DEFAULT_ADMIN_RIGHTS);
+        return { ok: true };
+      case "demote": {
+        const revoked = Object.fromEntries(
+          Object.keys(DEFAULT_ADMIN_RIGHTS).map((k) => [k, false]),
+        );
+        await bot.api.promoteChatMember(chatId, userId!, revoked);
+        return { ok: true };
+      }
+      case "set_admin_title":
+        await bot.api.setChatAdministratorCustomTitle(
+          chatId,
+          userId!,
+          String(body.title ?? ""),
+        );
+        return { ok: true };
+      case "set_permissions": {
+        const raw = body.permissions;
+        if (!raw || typeof raw !== "object")
+          return { ok: false, error: "set_permissions: permissions required" };
+        await bot.api.setChatPermissions(
+          chatId,
+          toChatPermissions(raw as Record<string, boolean>),
+        );
+        return { ok: true };
+      }
+      case "create_invite_link": {
+        const expireMin = Number(body.expire_minutes);
+        const link = await bot.api.createChatInviteLink(chatId, {
+          name: body.title ? String(body.title) : undefined,
+          expire_date:
+            Number.isFinite(expireMin) && expireMin > 0
+              ? Math.floor(Date.now() / 1000) + Math.round(expireMin * 60)
+              : undefined,
+          member_limit: toPositiveId(body.member_limit),
+        });
+        return { ok: true, invite_link: link.invite_link };
+      }
+      case "revoke_invite_link": {
+        if (!body.link)
+          return { ok: false, error: "revoke_invite_link: link required" };
+        await bot.api.revokeChatInviteLink(chatId, String(body.link));
+        return { ok: true };
+      }
+      case "approve_join_request":
+        await bot.api.approveChatJoinRequest(chatId, userId!);
+        clearJoinRequest(chatId, userId!);
+        return { ok: true };
+      case "decline_join_request":
+        await bot.api.declineChatJoinRequest(chatId, userId!);
+        clearJoinRequest(chatId, userId!);
+        return { ok: true };
+      case "list_join_requests":
+        return { ok: true, requests: listJoinRequests(chatId) };
+      case "set_chat_photo": {
+        const resolved = resolveMediaInput(
+          body,
+          "set_chat_photo",
+          InputFileClass,
+        );
+        if ("error" in resolved) return { ok: false, error: resolved.error };
+        if (typeof resolved.file === "string")
+          return {
+            ok: false,
+            error: "set_chat_photo needs a local file_path (no url/file_id)",
+          };
+        await bot.api.setChatPhoto(chatId, resolved.file);
+        return { ok: true };
+      }
+      case "delete_chat_photo":
+        await bot.api.deleteChatPhoto(chatId);
+        return { ok: true };
+      case "unpin_all":
+        await bot.api.unpinAllChatMessages(chatId);
+        return { ok: true };
+      case "leave_chat":
+        await bot.api.leaveChat(chatId);
+        return { ok: true };
+      case "create_topic": {
+        if (!body.title)
+          return { ok: false, error: "create_topic: title required" };
+        const topic = await bot.api.createForumTopic(
+          chatId,
+          String(body.title),
+        );
+        return { ok: true, thread_id: topic.message_thread_id };
+      }
+      case "edit_topic": {
+        const threadId = toPositiveId(body.thread_id);
+        if (threadId === undefined)
+          return { ok: false, error: "edit_topic: thread_id required" };
+        await bot.api.editForumTopic(chatId, threadId, {
+          name: body.title ? String(body.title) : undefined,
+        });
+        return { ok: true };
+      }
+      case "close_topic":
+      case "reopen_topic":
+      case "delete_topic": {
+        const threadId = toPositiveId(body.thread_id);
+        if (threadId === undefined)
+          return { ok: false, error: `${op}: thread_id required` };
+        if (op === "close_topic")
+          await bot.api.closeForumTopic(chatId, threadId);
+        else if (op === "reopen_topic")
+          await bot.api.reopenForumTopic(chatId, threadId);
+        else await bot.api.deleteForumTopic(chatId, threadId);
+        return { ok: true };
+      }
+      default:
+        return { ok: false, error: `Unknown moderation op: ${op}` };
+    }
+  },
+
+  get_user_profile_photos: async (body, _chatId, { bot }) => {
+    const userId = toPositiveId(body.user_id);
+    if (userId === undefined)
+      return { ok: false, error: "user_id is required" };
+    const limit = toPositiveId(body.limit) ?? 5;
+    const photos = await bot.api.getUserProfilePhotos(userId, {
+      limit: Math.min(limit, 100),
+    });
+    return {
+      ok: true,
+      total: photos.total_count,
+      // Largest size of each photo; its file_id sends/downloads like media.
+      file_ids: photos.photos.map((sizes) => sizes[sizes.length - 1].file_id),
+    };
+  },
+};

package/src/frontend/telegram/actions/shared.ts

@@ -6,13 +6,60 @@
 import type { Bot } from "grammy";
 import { markdownToTelegramHtml } from "../formatting.js";
 import { logWarn } from "../../../util/log.js";
+import { ambientThreadId, resolveThreadId } from "../topics.js";
 import { TELEGRAM_MAX_TEXT } from "./types.js";
 
 export function replyParams(
   body: Record<string, unknown>,
-): { message_id: number } | undefined {
-  const replyTo = toPositiveId(body.reply_to ?? body.reply_to_message_id);
-  return replyTo !== undefined ? { message_id: replyTo } : undefined;
+): ReplyParams | undefined {
+  return replyParamsFor(
+    toPositiveId(body.reply_to ?? body.reply_to_message_id),
+  );
+}
+
+export type ReplyParams = {
+  message_id: number;
+  allow_sending_without_reply: true;
+};
+
+/**
+ * Build `reply_parameters` for an outbound send. Always allows sending
+ * without the reply: the target message may have been deleted by the time
+ * we send (fast-moving groups, cleanup bots), and without this flag
+ * Telegram 400s the whole send — every formatting-level fallback then
+ * fails identically and the message is lost. A send that arrives
+ * un-linked beats one that never arrives.
+ */
+export function replyParamsFor(
+  replyTo: number | undefined,
+): ReplyParams | undefined {
+  return replyTo !== undefined && replyTo > 0
+    ? { message_id: replyTo, allow_sending_without_reply: true }
+    : undefined;
+}
+
+/** Delivery modifiers shared by every outbound send. */
+export type ExtraSendOpts = {
+  message_thread_id?: number;
+  disable_notification?: boolean;
+  protect_content?: boolean;
+  link_preview_options?: { is_disabled: boolean };
+};
+
+/**
+ * Extract the delivery modifiers from an action body: forum topic (explicit
+ * `thread_id` beats the chat's ambient one), `silent` (no notification sound),
+ * and `protect` (no forwarding/saving). Spread into any Bot API send options.
+ */
+export function sendOpts(
+  body: Record<string, unknown>,
+  chatId: number,
+): ExtraSendOpts {
+  return {
+    message_thread_id: resolveThreadId(body, chatId),
+    disable_notification: body.silent === true || undefined,
+    protect_content: body.protect === true || undefined,
+  };
 }
 
 /**
@@ -79,6 +126,7 @@ export async function sendText(
   replyMarkup?: NonNullable<
     Parameters<Bot["api"]["sendRichMessage"]>[2]
   >["reply_markup"],
+  extra?: ExtraSendOpts,
 ): Promise<number> {
   if (text.length > TELEGRAM_MAX_TEXT) {
     throw new Error(
@@ -86,14 +134,22 @@ export async function sendText(
     );
   }
 
+  // Default to the chat's ambient forum topic so every text path — commands,
+  // menus, scheduled replays — stays in the topic the conversation is in.
+  // An explicit `extra` (from sendOpts) already resolved this.
+  const opts: ExtraSendOpts = extra ?? {
+    message_thread_id: ambientThreadId(chatId),
+  };
+
   if (richMessagesSupported) {
     try {
       const sent = await bot.api.sendRichMessage(
         chatId,
         { markdown: text },
         {
-          reply_parameters: replyTo ? { message_id: replyTo } : undefined,
+          reply_parameters: replyParamsFor(replyTo),
           reply_markup: replyMarkup,
+          ...opts,
         },
       );
       return sent.message_id;
@@ -106,8 +162,9 @@ export async function sendText(
   try {
     const sent = await bot.api.sendMessage(chatId, html, {
       parse_mode: "HTML",
-      reply_parameters: replyTo ? { message_id: replyTo } : undefined,
+      reply_parameters: replyParamsFor(replyTo),
       reply_markup: replyMarkup,
+      ...opts,
     });
     return sent.message_id;
   } catch (err) {
@@ -116,8 +173,9 @@ export async function sendText(
       `Legacy HTML send failed; retrying as plain text (chat=${chatId}): ${err instanceof Error ? err.message : err}`,
     );
     const sent = await bot.api.sendMessage(chatId, text, {
-      reply_parameters: replyTo ? { message_id: replyTo } : undefined,
+      reply_parameters: replyParamsFor(replyTo),
       reply_markup: replyMarkup,
+      ...opts,
     });
     return sent.message_id;
   }

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

@@ -10,7 +10,8 @@ import { toolInputToRecord } from "../../../core/agent-runtime/events.js";
 import { appendDailyLogResponse } from "../../../storage/daily-log.js";
 import { stripMcpPrefix } from "../../../core/tools/index.js";
 import { logWarn } from "../../../util/log.js";
-import { sendText } from "../actions/shared.js";
+import { replyParamsFor, sendText } from "../actions/shared.js";
+import { ambientThreadId } from "../topics.js";
 import { trackDmUser } from "./access.js";
 
 export async function sendHtml(
@@ -21,7 +22,8 @@ export async function sendHtml(
 ): Promise<number> {
   const params = {
     parse_mode: "HTML" as const,
-    reply_parameters: replyToId ? { message_id: replyToId } : undefined,
+    reply_parameters: replyParamsFor(replyToId),
+    message_thread_id: ambientThreadId(chatId),
   };
   try {
     const sent = await bot.api.sendMessage(chatId, html, params);
@@ -38,7 +40,8 @@ export async function sendHtml(
       plain = plain.replace(/<[^>]*>/g, "");
     } while (plain !== prev);
     const sent = await bot.api.sendMessage(chatId, plain, {
-      reply_parameters: replyToId ? { message_id: replyToId } : undefined,
+      reply_parameters: replyParamsFor(replyToId),
+      message_thread_id: ambientThreadId(chatId),
     });
     return sent.message_id;
   }
@@ -97,7 +100,9 @@ function createStreamCallbacks(
           ? accumulated.slice(0, 3900) + "…"
           : accumulated;
 
-      await bot.api.sendMessageDraft(chatId, state.draftId, display);
+      await bot.api.sendMessageDraft(chatId, state.draftId, display, {
+        message_thread_id: ambientThreadId(chatId),
+      });
       if (draftsSupported === null) draftsSupported = true;
       state.lastSentLength = accumulated.length;
     } catch {

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

@@ -9,13 +9,18 @@
 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 {
+  classify,
+  friendlyMessage,
+  RETRY_ELAPSED_CAP_MS,
+} from "../../../core/errors.js";
 import {
   getRecentHistory,
   type HistoryMessage,
 } from "../../../storage/history.js";
 import {
   recordMessageProcessed,
+  recordMessageSettled,
   recordMessageReceived,
   recordError,
 } from "../../../util/watchdog.js";
@@ -176,6 +181,7 @@ async function flushQueue(chatId: string): Promise<void> {
       chatTitle: last.chatTitle,
     });
 
+  const startedAt = Date.now();
   try {
     await runTurn();
     lastHandledMessageIdByChat.set(chatId, last.messageId);
@@ -190,8 +196,20 @@ async function flushQueue(chatId: string): Promise<void> {
     );
     recordError(classified.message);
 
-    // Retry once for transient errors (rate_limit, overloaded, network)
-    if (classified.retryable) {
+    // Retry once for transient errors (rate_limit, overloaded, network) —
+    // but only when the failed attempt was actually brief. An attempt that
+    // already ran for minutes (a remote turn deadline, a slow collapse)
+    // won't be saved by a 2s pause, and turns serialize per chat, so the
+    // blind retry used to double a 10-minute stall for everything queued
+    // behind it.
+    const attemptMs = Date.now() - startedAt;
+    if (classified.retryable && attemptMs >= RETRY_ELAPSED_CAP_MS) {
+      log(
+        "bot",
+        `[${chatId}] Not retrying ${classified.reason}: the attempt already ran ${Math.round(attemptMs / 1000)}s`,
+      );
+    }
+    if (classified.retryable && attemptMs < RETRY_ELAPSED_CAP_MS) {
       const delayMs = classified.retryAfterMs ?? 2000;
       log(
         "bot",
@@ -209,6 +227,7 @@ async function flushQueue(chatId: string): Promise<void> {
           "bot",
           `[${chatId}] [${chatType}] Retry failed: ${retryClassified.message}`,
         );
+        recordMessageSettled();
         await sendHtml(
           bot,
           numericChatId,
@@ -219,6 +238,7 @@ async function flushQueue(chatId: string): Promise<void> {
       }
     }
 
+    recordMessageSettled();
     await sendHtml(
       bot,
       numericChatId,

package/src/frontend/telegram/index.ts

@@ -14,6 +14,7 @@ import { soulEnabled } from "../../core/soul/settings.js";
 import type { ContextManager } from "../../core/types.js";
 import type { Gateway } from "../../core/engine/gateway.js";
 import { createTelegramActionHandler, sendText } from "./actions/index.js";
+import { ambientThreadId } from "./topics.js";
 import { initUserClient, disconnectUserClient } from "./userbot.js";
 import {
   registerCommands,
@@ -60,7 +61,11 @@ export function createTelegramFrontend(
     context,
 
     sendTyping: (chatId: number) =>
-      bot.api.sendChatAction(chatId, "typing").then(() => {}),
+      bot.api
+        .sendChatAction(chatId, "typing", {
+          message_thread_id: ambientThreadId(chatId),
+        })
+        .then(() => {}),
 
     sendMessage: async (chatId: number, text: string) => {
       await sendText(bot, chatId, text);
@@ -118,13 +123,16 @@ export function createTelegramFrontend(
           process.exit(1);
         }
       });
-      // Reactions arrive only if we explicitly request `message_reaction`
-      // (it is absent from grammY's default allowed_updates). Subscribe only
-      // when the soul is enabled, so a soulless deployment keeps the default
-      // update set and behaves byte-identically.
-      const allowedUpdates = soulEnabled(config.soul)
-        ? [...API_CONSTANTS.DEFAULT_UPDATE_TYPES, "message_reaction" as const]
-        : undefined;
+      // Beyond grammY's defaults: `chat_join_request` feeds the moderation
+      // tool's pending-join cache (inert unless the bot admins an
+      // approval-gated chat), and `message_reaction` feeds the soul's
+      // reaction tap — subscribed only when the soul is enabled, so a
+      // soulless deployment's reaction behaviour is unchanged.
+      const allowedUpdates = [
+        ...API_CONSTANTS.DEFAULT_UPDATE_TYPES,
+        "chat_join_request" as const,
+        ...(soulEnabled(config.soul) ? ["message_reaction" as const] : []),
+      ];
       await bot.start({
         allowed_updates: allowedUpdates,
         onStart: (info) => log("bot", `Talon running as @${info.username}`),

package/src/frontend/telegram/join-requests.ts

@@ -0,0 +1,53 @@
+/**
+ * Pending chat-join-request tracking.
+ *
+ * When the bot administers a group whose invite link requires approval,
+ * Telegram delivers `chat_join_request` updates. They're stored here (not
+ * enqueued as agent turns — a join isn't a conversation) so the agent can
+ * review and act when asked: `moderate(op="list_join_requests")`, then
+ * approve/decline by user_id.
+ *
+ * In-memory by design: requests are also visible in Telegram's own UI, so
+ * losing the cache on restart costs nothing but a re-request.
+ */
+
+export type JoinRequest = {
+  userId: number;
+  name: string;
+  username?: string;
+  bio?: string;
+  /** Unix ms the request arrived. */
+  at: number;
+};
+
+const MAX_PER_CHAT = 200;
+
+const pendingByChat = new Map<number, Map<number, JoinRequest>>();
+
+export function recordJoinRequest(chatId: number, req: JoinRequest): void {
+  let chat = pendingByChat.get(chatId);
+  if (!chat) {
+    chat = new Map();
+    pendingByChat.set(chatId, chat);
+  }
+  if (chat.size >= MAX_PER_CHAT && !chat.has(req.userId)) {
+    // Drop the oldest (first-inserted) entry to stay bounded.
+    const oldest = chat.keys().next();
+    if (!oldest.done) chat.delete(oldest.value);
+  }
+  chat.set(req.userId, req);
+}
+
+/** Forget a request once it's been approved/declined (or withdrawn). */
+export function clearJoinRequest(chatId: number, userId: number): void {
+  pendingByChat.get(chatId)?.delete(userId);
+}
+
+export function listJoinRequests(chatId: number): JoinRequest[] {
+  return [...(pendingByChat.get(chatId)?.values() ?? [])];
+}
+
+/** Test seam. */
+export function resetJoinRequests(): void {
+  pendingByChat.clear();
+}

package/src/frontend/telegram/middleware.ts

@@ -10,6 +10,8 @@ import { allowChat, revokeChat } from "./userbot.js";
 import { registerChat } from "../../core/background/pulse.js";
 import { log } from "../../util/log.js";
 import { getSenderName } from "./handlers/index.js";
+import { noteInboundThread } from "./topics.js";
+import { recordJoinRequest } from "./join-requests.js";
 import { newlyAddedEmojis, recordReactionToBot } from "../../core/soul/taps.js";
 import {
   handleTextMessage,
@@ -28,6 +30,10 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
   bot.on("message", (ctx, next) => {
     const chatId = String(ctx.chat.id);
     const sender = getSenderName(ctx.from);
+    // Keep the ambient forum topic current so outbound sends (which have no
+    // reply anchor — drafts, media, plain sends) land in the topic the
+    // conversation is actually happening in, not General.
+    noteInboundThread(ctx.chat.id, ctx.message);
     // The handle is the only addressable form of a user — persist it with
     // every row so later readers (history views, heartbeat-composed
     // messages) can mention someone instead of guessing.
@@ -188,6 +194,25 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
     recordReactionToBot(mr.chat.id, mr.message_id, added);
   });
 
+  // ── Join requests — cache for moderate(op="list_join_requests") ─────────
+  // Delivered only when subscribed via allowed_updates (see index.ts) and
+  // the bot admins a chat whose invite link requires approval. Stored, not
+  // enqueued: a join request isn't a conversation turn.
+  bot.on("chat_join_request", (ctx) => {
+    const req = ctx.chatJoinRequest;
+    recordJoinRequest(ctx.chat.id, {
+      userId: req.from.id,
+      name: getSenderName(req.from),
+      username: req.from.username,
+      bio: req.bio,
+      at: Date.now(),
+    });
+    log(
+      "bot",
+      `Join request for chat ${ctx.chat.id} from ${req.from.id} (@${req.from.username ?? "?"})`,
+    );
+  });
+
   // ── Bot removed from group — revoke userbot access ─────────────────────
   bot.on("my_chat_member", (ctx) => {
     const newStatus = ctx.myChatMember.new_chat_member.status;

package/src/frontend/telegram/topics.ts

@@ -0,0 +1,63 @@
+/**
+ * Forum-topic (message thread) tracking.
+ *
+ * In a supergroup with topics enabled, every message lives in a thread, and a
+ * bot send without a `message_thread_id` lands in the General topic — so
+ * without this the agent answers a question asked in #support over in
+ * General. Telegram does route a send that *replies* to a topic message into
+ * that topic, but most agent output (reactions aside) is not a reply: draft
+ * streaming, scheduled sends, media, and plain `send(type="text")` all go out
+ * unanchored.
+ *
+ * The registry keeps the last inbound thread per chat, updated by the
+ * history-capture middleware that already sees every message. Outbound
+ * helpers consult it via {@link resolveThreadId}, with an explicit
+ * `thread_id` in the action body always winning over the ambient value.
+ *
+ * Last-write-wins per chat is the right granularity: chats are processed as
+ * serial turns, and each turn's replies belong to the topic that woke it.
+ */
+
+const lastThreadByChat = new Map<number, number>();
+
+/** Record (or clear) the ambient thread from an inbound message. */
+export function noteInboundThread(
+  chatId: number,
+  msg: { is_topic_message?: boolean; message_thread_id?: number },
+): void {
+  // `message_thread_id` is also set on plain reply chains in non-forum
+  // groups; only `is_topic_message` marks a real forum topic. General-topic
+  // messages carry neither, and must clear a stale thread.
+  if (msg.is_topic_message && msg.message_thread_id) {
+    lastThreadByChat.set(chatId, msg.message_thread_id);
+  } else {
+    lastThreadByChat.delete(chatId);
+  }
+}
+
+/** The thread the chat's latest topic message arrived in, if any. */
+export function ambientThreadId(chatId: number): number | undefined {
+  return lastThreadByChat.get(chatId);
+}
+
+/**
+ * Thread for an outbound action: an explicit `thread_id` in the body wins,
+ * else the chat's ambient thread. `thread_id: 0` (or "general") explicitly
+ * targets the General topic, suppressing the ambient value.
+ */
+export function resolveThreadId(
+  body: Record<string, unknown>,
+  chatId: number,
+): number | undefined {
+  const raw = body.thread_id;
+  if (raw === 0 || raw === "0" || raw === "general") return undefined;
+  const n =
+    typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN;
+  if (Number.isInteger(n) && n > 0) return n;
+  return ambientThreadId(chatId);
+}
+
+/** Test seam. */
+export function resetThreadRegistry(): void {
+  lastThreadByChat.clear();
+}