talon-agent 3.21.0 → 3.22.0

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

@@ -9,9 +9,47 @@ import { expandFsPath } from "../../../util/fs-path.js";
 import { markdownToTelegramHtml } from "../formatting.js";
 import { withRetry } from "../../../core/engine/gateway.js";
 import { resolveStickerByEmoji } from "../sticker-library.js";
-import { replyParams } from "./shared.js";
+import { replyParams, sendOpts } from "./shared.js";
 import type { TelegramActionHandlers } from "./types.js";
 
+type MediaSource = {
+  file_path?: unknown;
+  url?: unknown;
+  file_id?: unknown;
+};
+
+/**
+ * Resolve one media input to what the Bot API accepts. Three sources, in
+ * priority order: a public URL or a Telegram file_id (both passed as a plain
+ * string — Telegram fetches/reuses server-side, no local bytes involved),
+ * else a workspace file path uploaded as multipart.
+ */
+export function resolveMediaInput(
+  src: MediaSource,
+  label: string,
+  InputFileClass: typeof import("grammy").InputFile,
+): { file: string | import("grammy").InputFile } | { error: string } {
+  const remote = src.url ?? src.file_id;
+  if (remote) return { file: String(remote) };
+  // Fail with guidance the model can act on, not a raw ENOENT: a
+  // mistyped path is the most common media-send error, and naming
+  // the alternatives (url / file_id) teaches the recovery path.
+  if (!src.file_path)
+    return {
+      error: `${label}: provide file_path (workspace file), url (public), or file_id (seen in chat)`,
+    };
+  const filePath = expandFsPath(String(src.file_path));
+  if (!existsSync(filePath))
+    return {
+      error: `File not found: ${filePath} — check the workspace path, or send by url/file_id instead`,
+    };
+  const stat = statSync(filePath);
+  if (stat.size > 49 * 1024 * 1024)
+    return { error: "File too large (max 49MB)" };
+  const data = readFileSync(filePath);
+  return { file: new InputFileClass(data, basename(filePath)) };
+}
+
 const sendMediaFile: TelegramActionHandlers[string] = async (
   body,
   chatId,
@@ -25,36 +63,13 @@ const sendMediaFile: TelegramActionHandlers[string] = async (
     : undefined;
   const captionParseMode = caption ? ("HTML" as const) : undefined;
   gateway.incrementMessages(chatId);
-  // Three media sources, in priority order: a public URL or a Telegram
-  // file_id (both passed to the Bot API as a plain string — Telegram
-  // fetches/reuses server-side, no local bytes involved), else a
-  // workspace file path uploaded as multipart.
-  const remote = body.url ?? body.file_id;
-  let file: string | import("grammy").InputFile;
-  if (remote) {
-    file = String(remote);
-  } else {
-    // Fail with guidance the model can act on, not a raw ENOENT: a
-    // mistyped path is the most common media-send error, and naming
-    // the alternatives (url / file_id) teaches the recovery path.
-    if (!body.file_path)
-      return {
-        ok: false,
-        error: `${action}: provide file_path (workspace file), url (public), or file_id (seen in chat)`,
-      };
-    const filePath = expandFsPath(String(body.file_path));
-    if (!existsSync(filePath))
-      return {
-        ok: false,
-        error: `File not found: ${filePath} — check the workspace path, or send by url/file_id instead`,
-      };
-    const stat = statSync(filePath);
-    if (stat.size > 49 * 1024 * 1024)
-      return { ok: false, error: "File too large (max 49MB)" };
-    const data = readFileSync(filePath);
-    file = new InputFileClass(data, basename(filePath));
-  }
+  const resolved = resolveMediaInput(body, action, InputFileClass);
+  if ("error" in resolved) return { ok: false, error: resolved.error };
+  const file = resolved.file;
   const rp = replyParams(body);
+  const opts = sendOpts(body, chatId);
+  // Spoiler blur only exists for visual media; Telegram rejects it elsewhere.
+  const spoiler = body.spoiler === true || undefined;
   let sent;
   switch (action) {
     case "send_file":
@@ -63,6 +78,7 @@ const sendMediaFile: TelegramActionHandlers[string] = async (
           caption,
           parse_mode: captionParseMode,
           reply_parameters: rp,
+          ...opts,
         }),
       );
       break;
@@ -72,6 +88,8 @@ const sendMediaFile: TelegramActionHandlers[string] = async (
           caption,
           parse_mode: captionParseMode,
           reply_parameters: rp,
+          has_spoiler: spoiler,
+          ...opts,
         }),
       );
       break;
@@ -81,6 +99,8 @@ const sendMediaFile: TelegramActionHandlers[string] = async (
           caption,
           parse_mode: captionParseMode,
           reply_parameters: rp,
+          has_spoiler: spoiler,
+          ...opts,
         }),
       );
       break;
@@ -90,6 +110,8 @@ const sendMediaFile: TelegramActionHandlers[string] = async (
           caption,
           parse_mode: captionParseMode,
           reply_parameters: rp,
+          has_spoiler: spoiler,
+          ...opts,
         }),
       );
       break;
@@ -101,6 +123,7 @@ const sendMediaFile: TelegramActionHandlers[string] = async (
           reply_parameters: rp,
           title: body.title as string | undefined,
           performer: body.performer as string | undefined,
+          ...opts,
         }),
       );
       break;
@@ -110,6 +133,7 @@ const sendMediaFile: TelegramActionHandlers[string] = async (
           caption,
           parse_mode: captionParseMode,
           reply_parameters: rp,
+          ...opts,
         }),
       );
       break;
@@ -125,6 +149,90 @@ export const mediaHandlers: TelegramActionHandlers = {
   send_voice: sendMediaFile,
   send_audio: sendMediaFile,
 
+  send_media_group: async (body, chatId, { bot, InputFileClass, gateway }) => {
+    const items = Array.isArray(body.media) ? body.media : [];
+    if (items.length < 2 || items.length > 10)
+      return {
+        ok: false,
+        error: `Albums need 2–10 media items (got ${items.length}).`,
+      };
+    const spoiler = body.spoiler === true || undefined;
+    type AlbumItem = {
+      type: "photo" | "video" | "document" | "audio";
+      media: string | import("grammy").InputFile;
+      caption?: string;
+      parse_mode?: "HTML";
+      has_spoiler?: boolean;
+    };
+    const media: AlbumItem[] = [];
+    for (const [i, raw] of items.entries()) {
+      const item = raw as MediaSource & { type?: unknown; caption?: unknown };
+      // Telegram albums mix photos and videos; documents/audio group only
+      // with their own kind. Pass the declared type through and let the API
+      // reject invalid mixes with its own (clear) error.
+      const type = String(item.type ?? "photo");
+      if (!["photo", "video", "document", "audio"].includes(type))
+        return {
+          ok: false,
+          error: `media[${i}]: type must be photo, video, document, or audio`,
+        };
+      const resolved = resolveMediaInput(item, `media[${i}]`, InputFileClass);
+      if ("error" in resolved) return { ok: false, error: resolved.error };
+      const caption = item.caption
+        ? markdownToTelegramHtml(String(item.caption))
+        : undefined;
+      media.push({
+        type: type as AlbumItem["type"],
+        media: resolved.file,
+        caption,
+        parse_mode: caption ? ("HTML" as const) : undefined,
+        ...(type === "photo" || type === "video"
+          ? { has_spoiler: spoiler }
+          : {}),
+      });
+    }
+    gateway.incrementMessages(chatId);
+    // The wrapper types each album as homogeneous; runtime validation above
+    // plus Telegram's own mixed-group errors cover what the cast waives.
+    const group = media as unknown as Parameters<
+      import("grammy").Bot["api"]["sendMediaGroup"]
+    >[1];
+    const sent = await withRetry(() =>
+      bot.api.sendMediaGroup(chatId, group, {
+        reply_parameters: replyParams(body),
+        ...sendOpts(body, chatId),
+      }),
+    );
+    return { ok: true, message_ids: sent.map((m) => m.message_id) };
+  },
+
+  send_video_note: async (body, chatId, { bot, InputFileClass, gateway }) => {
+    const resolved = resolveMediaInput(body, "send_video_note", InputFileClass);
+    if ("error" in resolved) return { ok: false, error: resolved.error };
+    gateway.incrementMessages(chatId);
+    // Round video bubbles take no caption; Telegram wants square video ≤60s.
+    const sent = await withRetry(() =>
+      bot.api.sendVideoNote(chatId, resolved.file, {
+        reply_parameters: replyParams(body),
+        ...sendOpts(body, chatId),
+      }),
+    );
+    return { ok: true, message_id: sent.message_id };
+  },
+
+  send_venue: async (body, chatId, { bot, gateway }) => {
+    gateway.incrementMessages(chatId);
+    const sent = await bot.api.sendVenue(
+      chatId,
+      Number(body.latitude),
+      Number(body.longitude),
+      String(body.title ?? ""),
+      String(body.address ?? ""),
+      { reply_parameters: replyParams(body), ...sendOpts(body, chatId) },
+    );
+    return { ok: true, message_id: sent.message_id };
+  },
+
   send_sticker: async (body, chatId, { bot, gateway }) => {
     // Three addressing modes: a concrete file_id, a public URL of a
     // .webp (Telegram fetches it server-side, like other media), or an
@@ -155,6 +263,7 @@ export const mediaHandlers: TelegramActionHandlers = {
     gateway.incrementMessages(chatId);
     const sent = await bot.api.sendSticker(chatId, fileId, {
       reply_parameters: replyParams(body),
+      ...sendOpts(body, chatId),
     });
     return { ok: true, message_id: sent.message_id };
   },
@@ -176,6 +285,7 @@ export const mediaHandlers: TelegramActionHandlers = {
             : undefined,
         explanation: body.explanation as string | undefined,
         reply_parameters: replyParams(body),
+        ...sendOpts(body, chatId),
       },
     );
     return { ok: true, message_id: sent.message_id };
@@ -187,7 +297,7 @@ export const mediaHandlers: TelegramActionHandlers = {
       chatId,
       Number(body.latitude),
       Number(body.longitude),
-      { reply_parameters: replyParams(body) },
+      { reply_parameters: replyParams(body), ...sendOpts(body, chatId) },
     );
     return { ok: true, message_id: sent.message_id };
   },
@@ -201,6 +311,7 @@ export const mediaHandlers: TelegramActionHandlers = {
       {
         last_name: body.last_name as string | undefined,
         reply_parameters: replyParams(body),
+        ...sendOpts(body, chatId),
       },
     );
     return { ok: true, message_id: sent.message_id };
@@ -213,6 +324,7 @@ export const mediaHandlers: TelegramActionHandlers = {
       (body.emoji as string) || "🎲",
       {
         reply_parameters: replyParams(body),
+        ...sendOpts(body, chatId),
       },
     );
     return {

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

@@ -18,9 +18,11 @@ import {
 import {
   noteRichMessageFailure,
   richMessagesAvailable,
+  sendOpts,
   sendText,
   toPositiveId,
 } from "./shared.js";
+import { resolveThreadId } from "../topics.js";
 import { TELEGRAM_MAX_TEXT, type TelegramActionHandlers } from "./types.js";
 
 // ── Inline keyboards ─────────────────────────────────────────────────────────
@@ -201,7 +203,14 @@ export const messagingHandlers: TelegramActionHandlers = {
     const text = String(body.text ?? "");
     const replyTo = toPositiveId(body.reply_to_message_id);
     gateway.incrementMessages(chatId);
-    const msgId = await withRetry(() => sendText(bot, chatId, text, replyTo));
+    const extra = {
+      ...sendOpts(body, chatId),
+      link_preview_options:
+        body.no_link_preview === true ? { is_disabled: true } : undefined,
+    };
+    const msgId = await withRetry(() =>
+      sendText(bot, chatId, text, replyTo, undefined, extra),
+    );
     return { ok: true, message_id: msgId };
   },
 
@@ -249,6 +258,23 @@ export const messagingHandlers: TelegramActionHandlers = {
         ok: false,
         error: `Text too long (max ${TELEGRAM_MAX_TEXT})`,
       };
+    // Media messages have captions, not text — editMessageText on them fails
+    // with "there is no text in the message to edit".
+    if (body.is_caption === true) {
+      await withRetry(async () => {
+        try {
+          await bot.api.editMessageCaption(chatId, Number(body.message_id), {
+            caption: markdownToTelegramHtml(text),
+            parse_mode: "HTML",
+          });
+        } catch {
+          await bot.api.editMessageCaption(chatId, Number(body.message_id), {
+            caption: text,
+          });
+        }
+      });
+      return { ok: true };
+    }
     await withRetry(async () => {
       if (richMessagesAvailable()) {
         try {
@@ -275,6 +301,19 @@ export const messagingHandlers: TelegramActionHandlers = {
   },
 
   delete_message: async (body, chatId, { bot }) => {
+    // Bulk form: deleteMessages takes up to 100 ids per call and skips ids
+    // it can't delete instead of failing the batch.
+    if (Array.isArray(body.message_ids) && body.message_ids.length > 0) {
+      const ids = body.message_ids
+        .map(toPositiveId)
+        .filter((n): n is number => n !== undefined);
+      if (ids.length === 0)
+        return { ok: false, error: "message_ids contains no valid ids" };
+      for (let i = 0; i < ids.length; i += 100) {
+        await bot.api.deleteMessages(chatId, ids.slice(i, i + 100));
+      }
+      return { ok: true, deleted: ids.length };
+    }
     await bot.api.deleteMessage(chatId, Number(body.message_id));
     return { ok: true };
   },
@@ -293,22 +332,42 @@ export const messagingHandlers: TelegramActionHandlers = {
   },
 
   forward_message: async (body, chatId, { bot }) => {
-    if (body.to_chat_id && Number(body.to_chat_id) !== chatId)
-      return { ok: false, error: "Cross-chat forwarding not allowed." };
+    // Cross-chat by explicit override; both ends default to the current
+    // chat. The bot can only ever read from / deliver to chats it is in —
+    // Telegram enforces membership on both ids.
+    const from = Number(body.from_chat_id ?? chatId);
+    const to = Number(body.to_chat_id ?? chatId);
+    const ids = Array.isArray(body.message_ids)
+      ? body.message_ids
+          .map(toPositiveId)
+          .filter((n): n is number => n !== undefined)
+      : [];
+    if (ids.length > 0) {
+      // forwardMessages keeps album grouping and skips unfindable ids.
+      const sent = await bot.api.forwardMessages(to, from, ids);
+      return { ok: true, message_ids: sent.map((m) => m.message_id) };
+    }
     const sent = await bot.api.forwardMessage(
-      chatId,
-      chatId,
+      to,
+      from,
       Number(body.message_id),
     );
     return { ok: true, message_id: sent.message_id };
   },
 
   copy_message: async (body, chatId, { bot }) => {
-    const sent = await bot.api.copyMessage(
-      chatId,
-      chatId,
-      Number(body.message_id),
-    );
+    const from = Number(body.from_chat_id ?? chatId);
+    const to = Number(body.to_chat_id ?? chatId);
+    const ids = Array.isArray(body.message_ids)
+      ? body.message_ids
+          .map(toPositiveId)
+          .filter((n): n is number => n !== undefined)
+      : [];
+    if (ids.length > 0) {
+      const sent = await bot.api.copyMessages(to, from, ids);
+      return { ok: true, message_ids: sent.map((m) => m.message_id) };
+    }
+    const sent = await bot.api.copyMessage(to, from, Number(body.message_id));
     return { ok: true, message_id: sent.message_id };
   },
 
@@ -316,6 +375,7 @@ export const messagingHandlers: TelegramActionHandlers = {
     await bot.api.sendChatAction(
       chatId,
       String(body.chat_action ?? "typing") as "typing",
+      { message_thread_id: resolveThreadId(body, chatId) },
     );
     return { ok: true };
   },
@@ -329,9 +389,14 @@ export const messagingHandlers: TelegramActionHandlers = {
     if ("error" in built) return { ok: false, error: built.error };
     const keyboard = built.keyboard;
     gateway.incrementMessages(chatId);
-    const messageId = await sendText(bot, chatId, text, undefined, {
-      inline_keyboard: keyboard,
-    });
+    const messageId = await sendText(
+      bot,
+      chatId,
+      text,
+      toPositiveId(body.reply_to_message_id),
+      { inline_keyboard: keyboard },
+      sendOpts(body, chatId),
+    );
     return { ok: true, message_id: messageId };
   },
 

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),
+    };
+  },
+};