talon-agent 3.20.0 → 3.22.0

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,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;