talon-agent 3.21.0 → 3.22.0

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

@@ -6,6 +6,7 @@
 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(
@@ -15,6 +16,30 @@ export function replyParams(
   return replyTo !== undefined ? { message_id: replyTo } : 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,
+  };
+}
+
 /**
  * Telegram/GramJS APIs expect numeric IDs. `snowflakeOrIdSchema` normalizes IDs
  * to digit-strings (so 17-19 digit Discord snowflakes survive validation), so a
@@ -79,6 +104,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,6 +112,13 @@ 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(
@@ -94,6 +127,7 @@ export async function sendText(
         {
           reply_parameters: replyTo ? { message_id: replyTo } : undefined,
           reply_markup: replyMarkup,
+          ...opts,
         },
       );
       return sent.message_id;
@@ -108,6 +142,7 @@ export async function sendText(
       parse_mode: "HTML",
       reply_parameters: replyTo ? { message_id: replyTo } : undefined,
       reply_markup: replyMarkup,
+      ...opts,
     });
     return sent.message_id;
   } catch (err) {
@@ -118,6 +153,7 @@ export async function sendText(
     const sent = await bot.api.sendMessage(chatId, text, {
       reply_parameters: replyTo ? { message_id: replyTo } : undefined,
       reply_markup: replyMarkup,
+      ...opts,
     });
     return sent.message_id;
   }

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

@@ -11,6 +11,7 @@ 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 { ambientThreadId } from "../topics.js";
 import { trackDmUser } from "./access.js";
 
 export async function sendHtml(
@@ -22,6 +23,7 @@ export async function sendHtml(
   const params = {
     parse_mode: "HTML" as const,
     reply_parameters: replyToId ? { message_id: replyToId } : undefined,
+    message_thread_id: ambientThreadId(chatId),
   };
   try {
     const sent = await bot.api.sendMessage(chatId, html, params);
@@ -39,6 +41,7 @@ export async function sendHtml(
     } while (plain !== prev);
     const sent = await bot.api.sendMessage(chatId, plain, {
       reply_parameters: replyToId ? { message_id: replyToId } : undefined,
+      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/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();
+}

package/src/frontend/telegram/userbot.ts

@@ -129,10 +129,17 @@ export async function disconnectUserClient(): Promise<void> {
 const CHECK_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 
 let reconnecting = false;
+// Bumped by stopConnectionMonitor so a tick whose awaits straddle a shutdown
+// can tell that its own client was torn down under it — the liveness probe
+// rejecting because *we* disconnected must not trigger a reconnect, or
+// shutdown resurrects the client it just closed.
+let monitorGeneration = 0;
 
 function startConnectionMonitor(): void {
   if (reconnectTimer) return;
+  const gen = monitorGeneration;
   reconnectTimer = setInterval(async () => {
+    if (gen !== monitorGeneration) return;
     if (!client) return;
     if (reconnecting) return; // prevent overlapping reconnect attempts
 
@@ -146,10 +153,12 @@ function startConnectionMonitor(): void {
         await client.getMe();
         return; // genuinely alive
       } catch {
+        if (gen !== monitorGeneration) return; // monitor stopped mid-probe
         logWarn("userbot", "Liveness check failed — treating socket as dead.");
       }
     }
 
+    if (!client) return; // torn down while the probe was in flight
     reconnecting = true;
     logWarn("userbot", "Connection lost, attempting reconnect...");
     try {
@@ -160,6 +169,7 @@ function startConnectionMonitor(): void {
         logWarn("userbot", "Reconnected but not authorized.");
       }
     } catch (err) {
+      if (gen !== monitorGeneration) return; // stopped while reconnecting
       logError("userbot", "Reconnect failed", err);
       // Try a full re-init on next check
       if (storedApiId && storedApiHash) {
@@ -189,6 +199,7 @@ function startConnectionMonitor(): void {
 }
 
 function stopConnectionMonitor(): void {
+  monitorGeneration++;
   if (reconnectTimer) {
     clearInterval(reconnectTimer);
     reconnectTimer = null;