kiro-telegram-bot 1.5.1

package/src/bot/handlers/mcp.ts

@@ -0,0 +1,205 @@
+/**
+ * /mcp — inspect and control the Kiro agent's MCP servers from Telegram.
+ *
+ *   • Lists every configured server with its enabled/disabled state, transport
+ *     (stdio/http) and scope (global/workspace).
+ *   • 🩺 Health-check runs a real MCP `initialize` handshake against each enabled
+ *     server and reports which connected and which failed (and why).
+ *   • 🔧 Enable/Disable toggles a server's `disabled` flag in its mcp.json. The
+ *     change applies when the agent next loads servers, so a 🔄 Restart button
+ *     is offered to apply it immediately.
+ */
+import { type Bot, type Context, InlineKeyboard } from "grammy";
+import type { BotDeps } from "../deps.js";
+import { listMcpServers, setMcpDisabled } from "../../mcp/config.js";
+import { probeAll } from "../../mcp/probe.js";
+import type { McpProbeResult, McpServer } from "../../mcp/types.js";
+
+const PAGE_SIZE = 10;
+
+/** Per-chat snapshot of the last listed servers, for index-based callbacks. */
+const snapshots = new Map<number, McpServer[]>();
+
+function snapshot(chatId: number, deps: BotDeps): McpServer[] {
+  const cwd = deps.registry.get(chatId).cwd;
+  const list = listMcpServers(cwd);
+  snapshots.set(chatId, list);
+  return list;
+}
+
+function trunc(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n - 1) + "\u2026" : s;
+}
+
+const TRANSPORT_ICON: Record<string, string> = { http: "\u{1F310}", stdio: "\u{1F5A5}\uFE0F", unknown: "\u2753" };
+
+/** Build the main MCP panel text + keyboard. */
+function mainPanel(list: McpServer[]): { text: string; kb: InlineKeyboard } {
+  const enabled = list.filter((s) => !s.disabled);
+  const disabled = list.filter((s) => s.disabled);
+  const lines = [`\u{1F9E9} MCP servers \u2014 ${list.length} total \u00B7 \u2705 ${enabled.length} enabled \u00B7 \u26D4 ${disabled.length} disabled`, ""];
+  if (list.length === 0) {
+    lines.push("No MCP servers configured in ~/.kiro/settings/mcp.json.");
+  } else {
+    const LIST_CAP = 60; // keep the message well under Telegram's 4096-char limit
+    for (const s of list.slice(0, LIST_CAP)) {
+      const mark = s.disabled ? "\u26D4" : "\u2705";
+      const ti = TRANSPORT_ICON[s.transport] ?? "";
+      const scope = s.scope === "workspace" ? " \u00B7 ws" : "";
+      lines.push(`${mark} ${ti} ${trunc(s.name, 28)}${scope}`);
+    }
+    if (list.length > LIST_CAP) lines.push(`\u2026and ${list.length - LIST_CAP} more (use \u{1F527} Enable/Disable to browse).`);
+  }
+  lines.push("", "\u{1F9EA} Health-check runs a live connection test on enabled servers.");
+  const kb = new InlineKeyboard()
+    .text("\u{1F9EA} Health-check", "mcp:health")
+    .text("\u{1F527} Enable/Disable", "mcp:tog:0")
+    .row()
+    .text("\u{1F504} Restart agent", "mcp:restart")
+    .text("\u{1F501} Refresh", "mcp:refresh")
+    .row()
+    .text("\u2716 Close", "mcp:close");
+  return { text: lines.join("\n"), kb };
+}
+
+/** Build a paginated enable/disable view. */
+function togglePanel(list: McpServer[], page: number): { text: string; kb: InlineKeyboard } {
+  const pages = Math.max(1, Math.ceil(list.length / PAGE_SIZE));
+  const p = Math.min(Math.max(0, page), pages - 1);
+  const slice = list.slice(p * PAGE_SIZE, p * PAGE_SIZE + PAGE_SIZE);
+  const kb = new InlineKeyboard();
+  slice.forEach((s) => {
+    const idx = list.indexOf(s);
+    const label = s.disabled ? `\u2705 Enable ${trunc(s.name, 24)}` : `\u26D4 Disable ${trunc(s.name, 24)}`;
+    kb.text(label, `mcp:set:${idx}`).row();
+  });
+  if (pages > 1) {
+    if (p > 0) kb.text("\u25C0 Prev", `mcp:tog:${p - 1}`);
+    kb.text(`Page ${p + 1}/${pages}`, "mcp:noop");
+    if (p < pages - 1) kb.text("Next \u25B6", `mcp:tog:${p + 1}`);
+    kb.row();
+  }
+  kb.text("\u2B05 Back", "mcp:refresh");
+  const text = `\u{1F527} Enable/Disable MCP servers (${list.length})\nTap to toggle. Changes apply after \u{1F504} Restart agent.`;
+  return { text, kb };
+}
+
+export async function showMcp(ctx: Context, deps: BotDeps): Promise<void> {
+  const list = snapshot(ctx.chat!.id, deps);
+  const { text, kb } = mainPanel(list);
+  await ctx.reply(text, { reply_markup: kb });
+}
+
+function fmtProbe(r: McpProbeResult): string {
+  if (r.ok) {
+    const who = r.serverName ? ` \u00B7 ${trunc(r.serverName, 30)}` : "";
+    return `\u2705 ${trunc(r.name, 26)}  ${r.ms ?? 0}ms${who}`;
+  }
+  return `\u274C ${trunc(r.name, 26)}  ${trunc(r.error ?? "failed", 60)}`;
+}
+
+async function runHealthCheck(ctx: Context, deps: BotDeps): Promise<void> {
+  const list = snapshot(ctx.chat!.id, deps);
+  const enabled = list.filter((s) => !s.disabled);
+  if (enabled.length === 0) {
+    await ctx.editMessageText("No enabled MCP servers to check.", {
+      reply_markup: new InlineKeyboard().text("\u2B05 Back", "mcp:refresh"),
+    }).catch(() => {});
+    return;
+  }
+  const header = `\u{1F9EA} Health-check \u2014 probing ${enabled.length} enabled server(s)\u2026`;
+  await ctx.editMessageText(header).catch(() => {});
+
+  let lastEdit = 0;
+  const results = await probeAll(
+    enabled,
+    { timeoutMs: deps.cfg.mcpProbeTimeoutMs, concurrency: deps.cfg.mcpProbeConcurrency },
+    (_r, done, total) => {
+      const now = Date.now();
+      if (now - lastEdit < 1200 && done < total) return; // throttle progress edits
+      lastEdit = now;
+      void ctx.editMessageText(`${header}\n\nProgress: ${done}/${total}`).catch(() => {});
+    },
+  );
+
+  const ok = results.filter((r) => r.ok).length;
+  const bad = results.length - ok;
+  const body = results
+    .slice()
+    .sort((a, b) => Number(a.ok) - Number(b.ok) || a.name.localeCompare(b.name))
+    .map(fmtProbe)
+    .join("\n");
+  const text = `\u{1F9EA} Health-check \u2014 \u2705 ${ok} connected \u00B7 \u274C ${bad} failed\n\n${trunc(body, 3500)}`;
+  const kb = new InlineKeyboard().text("\u{1F501} Re-check", "mcp:health").row().text("\u2B05 Back", "mcp:refresh");
+  await ctx.editMessageText(text, { reply_markup: kb }).catch(() => {});
+}
+
+export function registerMcp(bot: Bot, deps: BotDeps): void {
+  bot.command("mcp", (ctx) => showMcp(ctx, deps));
+
+  bot.callbackQuery("mcp:noop", (ctx) => ctx.answerCallbackQuery());
+
+  bot.callbackQuery("mcp:close", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await ctx.deleteMessage().catch(() => {});
+  });
+
+  bot.callbackQuery("mcp:refresh", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const list = snapshot(ctx.chat!.id, deps);
+    const { text, kb } = mainPanel(list);
+    await ctx.editMessageText(text, { reply_markup: kb }).catch(() => {});
+  });
+
+  bot.callbackQuery("mcp:health", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Checking\u2026" });
+    await runHealthCheck(ctx, deps);
+  });
+
+  bot.callbackQuery(/^mcp:tog:(\d+)$/, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const list = snapshot(ctx.chat!.id, deps);
+    const { text, kb } = togglePanel(list, Number(ctx.match![1]));
+    await ctx.editMessageText(text, { reply_markup: kb }).catch(() => {});
+  });
+
+  bot.callbackQuery(/^mcp:set:(\d+)$/, async (ctx) => {
+    const idx = Number(ctx.match![1]);
+    const cached = snapshots.get(ctx.chat!.id);
+    const server = cached?.[idx];
+    if (!server) {
+      await ctx.answerCallbackQuery({ text: "Expired \u2014 reopen /mcp." });
+      return;
+    }
+    const res = setMcpDisabled(server, !server.disabled);
+    if (!res.ok) {
+      await ctx.answerCallbackQuery({ text: `Failed: ${res.error}`, show_alert: true });
+      return;
+    }
+    await ctx.answerCallbackQuery({ text: res.disabled ? `Disabled ${server.name}` : `Enabled ${server.name}` });
+    const page = Math.floor(idx / PAGE_SIZE);
+    const list = snapshot(ctx.chat!.id, deps); // re-list to reflect the change
+    const { text, kb } = togglePanel(list, page);
+    await ctx.editMessageText(`${text}\n\n\u26A0\uFE0F Tap \u{1F504} Restart agent (on the main panel) to apply.`, {
+      reply_markup: kb,
+    }).catch(() => {});
+  });
+
+  bot.callbackQuery("mcp:restart", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Restarting agent\u2026" });
+    await ctx.editMessageText("\u{1F504} Restarting the Kiro agent to apply MCP changes\u2026").catch(() => {});
+    try {
+      await deps.acp.restart();
+      const list = snapshot(ctx.chat!.id, deps);
+      const { text, kb } = mainPanel(list);
+      await ctx.editMessageText(`\u2705 Agent restarted \u2014 MCP changes applied.\n\n${text}`, {
+        reply_markup: kb,
+      }).catch(() => {});
+    } catch (err) {
+      await ctx.editMessageText(`\u274C Restart failed: ${(err as Error).message}`, {
+        reply_markup: new InlineKeyboard().text("\u2B05 Back", "mcp:refresh"),
+      }).catch(() => {});
+    }
+  });
+}
+

package/src/bot/handlers/menu.ts

@@ -0,0 +1,204 @@
+/**
+ * Menu handler — maps the persistent reply-keyboard buttons (matched by emoji
+ * prefix for stateful ones) to actions, and provides inline submenus for Agent
+ * (real Kiro modes), Reasoning, and Model. Changing a value re-renders the
+ * keyboard so its labels always reflect the current state.
+ */
+import { type Bot, type Context, InlineKeyboard } from "grammy";
+import { reasoningLabel } from "../../app/reasoning.js";
+import { REASONING_LEVELS, type ReasoningEffort } from "../../app/types.js";
+import type { BotDeps } from "../deps.js";
+import { BAR_LABELS, compactKeyboard, mainMenuInline, MENU_BTN, RUNNING_BTN, STOP_BTN } from "../menu/keyboard.js";
+import { refreshMenu } from "../menu/refresh.js";
+import { showKillConfirm } from "./kill.js";
+import { showMcp } from "./mcp.js";
+import { showProjects } from "./projects.js";
+import { showRunning } from "./running.js";
+import { showSessions } from "./sessions.js";
+import { showTasks } from "./tasks.js";
+import { showUsage } from "./usage.js";
+
+/** Open the full inline menu, showing the current agent/model/reasoning. */
+export async function openMainMenu(ctx: Context, deps: BotDeps): Promise<void> {
+  const rt = deps.registry.get(ctx.chat!.id);
+  await ctx.reply("\u2699\uFE0F Menu", {
+    reply_markup: mainMenuInline({
+      agent: rt.agent || "default",
+      model: rt.model || "default",
+      reasoning: reasoningLabel(rt.reasoning),
+    }),
+  });
+}
+
+export function registerMenu(bot: Bot, deps: BotDeps): void {
+  // Compact persistent bar.
+  bot.hears(BAR_LABELS, async (ctx) => {
+    deps.wizard.abort(ctx.chat.id);
+    switch (ctx.message?.text) {
+      case MENU_BTN:
+        return openMainMenu(ctx, deps);
+      case RUNNING_BTN:
+        return showRunning(ctx, deps);
+      case STOP_BTN: {
+        const rt = deps.registry.get(ctx.chat.id);
+        return void ctx.reply((await rt.cancel()) ? "\u23F9 Cancelling\u2026" : "Nothing is running.");
+      }
+    }
+  });
+
+  // Inline menu actions.
+  bot.callbackQuery(/^m:(\w+)$/, (ctx) => dispatchMenu(ctx, deps, ctx.match![1]!));
+
+  // ── Agent (real Kiro modes) ─────────────────────────────────────────────
+  bot.callbackQuery(/^agent:set:(\d+)$/, async (ctx) => {
+    const mode = deps.acp.availableModes[Number(ctx.match![1])];
+    if (!mode) return void ctx.answerCallbackQuery({ text: "Expired, tap Agent again." });
+    await deps.registry.get(ctx.chat!.id).setAgentPref(mode.id);
+    await confirm(ctx, deps, `\u{1F916} Agent: ${mode.name}`);
+  });
+
+  // ── Reasoning ──────────────────────────────────────────────────────────────
+  bot.callbackQuery(/^reason:(minimal|low|medium|high|max)$/, async (ctx) => {
+    const level = ctx.match![1] as ReasoningEffort;
+    deps.registry.get(ctx.chat!.id).setReasoningPref(level);
+    await confirm(ctx, deps, `\u{1F9E0} Reasoning: ${reasoningLabel(level)}`);
+  });
+
+  // ── Model ────────────────────────────────────────────────────────────────
+  bot.callbackQuery(/^model:set:(\d+)$/, async (ctx) => {
+    const entry = deps.acp.availableModels[Number(ctx.match![1])];
+    if (!entry) return void ctx.answerCallbackQuery({ text: "Expired, tap Model again." });
+    const res = await deps.registry.get(ctx.chat!.id).setModelPref(entry.modelId);
+    await confirm(ctx, deps, res.ok ? `\u{1F9E9} Model: ${entry.name}` : `\u26A0\uFE0F Model set failed: ${res.error}`);
+  });
+  bot.callbackQuery("model:clear", async (ctx) => {
+    await deps.registry.get(ctx.chat!.id).setModelPref("");
+    await confirm(ctx, deps, "\u{1F9E9} Model: default");
+  });
+}
+
+/** Dispatch an inline-menu action (`m:<action>`). */
+async function dispatchMenu(ctx: Context, deps: BotDeps, action: string): Promise<void> {
+  const chatId = ctx.chat!.id;
+  const rt = deps.registry.get(chatId);
+  switch (action) {
+    case "close":
+      await ctx.answerCallbackQuery();
+      return void ctx.deleteMessage().catch(() => {});
+    case "hidebar":
+      await ctx.answerCallbackQuery();
+      await ctx.deleteMessage().catch(() => {});
+      return void ctx.reply("\u{1F648} Bar hidden \u2014 send /menu to bring it back.", {
+        reply_markup: { remove_keyboard: true },
+      });
+    case "showbar":
+      await ctx.answerCallbackQuery();
+      return void ctx.reply("\u2328\uFE0F Bar restored.", { reply_markup: compactKeyboard() });
+    case "project":
+      await ctx.answerCallbackQuery();
+      return showProjects(ctx, deps);
+    case "running":
+      await ctx.answerCallbackQuery();
+      return showRunning(ctx, deps);
+    case "sessions":
+      await ctx.answerCallbackQuery();
+      return showSessions(ctx, deps);
+    case "tasks":
+      await ctx.answerCallbackQuery();
+      return showTasks(ctx, deps);
+    case "agent":
+      await ctx.answerCallbackQuery();
+      return showAgentMenu(ctx, deps);
+    case "model":
+      await ctx.answerCallbackQuery();
+      return showModelMenu(ctx, deps);
+    case "reasoning":
+      await ctx.answerCallbackQuery();
+      return showReasoningMenu(ctx, deps);
+    case "status":
+      await ctx.answerCallbackQuery();
+      await deps.statusPanel.refresh(chatId);
+      return void ctx.reply(deps.statusPanel.render(chatId));
+    case "usage":
+      await ctx.answerCallbackQuery();
+      return showUsage(ctx, deps);
+    case "mcp":
+      await ctx.answerCallbackQuery();
+      return showMcp(ctx, deps);
+    case "killall":
+      await ctx.answerCallbackQuery();
+      return showKillConfirm(ctx, deps);
+    case "new":
+      await ctx.answerCallbackQuery();
+      try {
+        await deps.registry.controller(chatId).addNew(rt.cwd, rt.projectName);
+        return refreshMenu(ctx, deps, `\u2728 New session in ${rt.projectName ?? rt.cwd}`);
+      } catch (e) {
+        return void ctx.reply(`\u274C ${(e as Error).message}`);
+      }
+    case "stop":
+      return void ctx.answerCallbackQuery({ text: (await rt.cancel()) ? "Cancelling\u2026" : "Nothing is running" });
+    default:
+      return void ctx.answerCallbackQuery();
+  }
+}
+
+async function confirm(ctx: Context, deps: BotDeps, text: string): Promise<void> {
+  await ctx.answerCallbackQuery({ text });
+  try {
+    await ctx.deleteMessage();
+  } catch {
+    /* ignore */
+  }
+  await deps.statusPanel.refresh(ctx.chat!.id);
+  await openMainMenu(ctx, deps); // reopen so the new value is visible
+}
+
+async function showAgentMenu(ctx: Context, deps: BotDeps): Promise<void> {
+  const rt = deps.registry.get(ctx.chat!.id);
+  await ensureReady(ctx, rt);
+  const modes = deps.acp.availableModes.slice(0, 60);
+  if (modes.length === 0) {
+    await ctx.reply(`Current agent: ${rt.agent || "default"}\n(No selectable agents reported by Kiro.)`);
+    return;
+  }
+  const kb = new InlineKeyboard();
+  modes.forEach((m, i) => kb.text(`${m.id === rt.agent ? "\u2713 " : ""}${m.name}`, `agent:set:${i}`).row());
+  await ctx.reply(`Current agent: ${rt.agent || "default"}\nChoose an agent:`, { reply_markup: kb });
+}
+
+async function showReasoningMenu(ctx: Context, deps: BotDeps): Promise<void> {
+  const rt = deps.registry.get(ctx.chat!.id);
+  const kb = new InlineKeyboard();
+  REASONING_LEVELS.forEach((l) => kb.text(`${l === rt.reasoning ? "\u2713 " : ""}${reasoningLabel(l)}`, `reason:${l}`));
+  await ctx.reply(`Current reasoning: ${reasoningLabel(rt.reasoning)}\nChoose effort:`, { reply_markup: kb });
+}
+
+async function showModelMenu(ctx: Context, deps: BotDeps): Promise<void> {
+  const rt = deps.registry.get(ctx.chat!.id);
+  await ensureReady(ctx, rt);
+  const models = deps.acp.availableModels;
+  if (models.length === 0) {
+    await ctx.reply("No selectable models reported by Kiro yet \u2014 send a message first, then try again.");
+    return;
+  }
+  const current = rt.model || deps.acp.currentModelId;
+  const kb = new InlineKeyboard();
+  models.forEach((m, i) => kb.text(`${m.modelId === current ? "\u2713 " : ""}${m.name}`, `model:set:${i}`).row());
+  kb.text("Default (agent's model)", "model:clear");
+  await ctx.reply(`Current model: ${rt.model || "default"}\nChoose a model:`, { reply_markup: kb });
+}
+
+/** Ensure a session is live so models/modes are populated; show typing meanwhile. */
+async function ensureReady(ctx: Context, rt: { prepare: () => Promise<void> }): Promise<void> {
+  try {
+    await ctx.replyWithChatAction("typing");
+  } catch {
+    /* ignore */
+  }
+  try {
+    await rt.prepare();
+  } catch {
+    /* menu will show whatever is available */
+  }
+}

package/src/bot/handlers/message.ts

@@ -0,0 +1,93 @@
+/**
+ * Plain text messages -> Kiro prompts.
+ *
+ * Telegram caps a single message at 4096 characters, so a long paste is
+ * delivered to the bot as several back-to-back messages. Naively, each part
+ * became its own queued turn ("Queued position 1…4") and a part that happened
+ * to start with "/" was misread as an "Unknown command". We therefore COALESCE
+ * rapid consecutive text messages per chat within a short debounce window
+ * (`MESSAGE_BATCH_MS`) into a single prompt — one submission, one confirmation.
+ *
+ * While a turn is running, the combined message is queued and runs
+ * automatically when the current turn finishes.
+ * (Wizard input and menu-button text are intercepted by earlier handlers.)
+ */
+import type { Bot } from "grammy";
+import { textPrompt } from "../../app/types.js";
+import { createLogger } from "../../logger.js";
+import type { BotDeps } from "../deps.js";
+
+const log = createLogger("message");
+
+/** A pending burst of text messages from one chat, awaiting coalescing. */
+interface TextBatch {
+  parts: string[];
+  timer: NodeJS.Timeout;
+}
+
+export function registerMessages(bot: Bot, deps: BotDeps): void {
+  const batches = new Map<number, TextBatch>();
+  const windowMs = deps.cfg.messageBatchMs;
+
+  const arm = (chatId: number): NodeJS.Timeout =>
+    setTimeout(() => void flush(deps, batches, chatId), windowMs);
+
+  bot.on("message:text", async (ctx) => {
+    const text = ctx.message.text;
+    if (!text.trim()) return;
+    const chatId = ctx.chat.id;
+
+    const batch = batches.get(chatId);
+    if (batch) {
+      clearTimeout(batch.timer);
+      batch.parts.push(text);
+      batch.timer = arm(chatId);
+      return;
+    }
+    batches.set(chatId, { parts: [text], timer: arm(chatId) });
+  });
+}
+
+/** Coalesce a chat's buffered parts into one prompt and submit it once. */
+async function flush(deps: BotDeps, batches: Map<number, TextBatch>, chatId: number): Promise<void> {
+  const batch = batches.get(chatId);
+  if (!batch) return;
+  batches.delete(chatId);
+
+  // Telegram splits at 4096 chars, almost always on a line boundary, so
+  // rejoining with a newline reconstructs the original text faithfully.
+  const combined = batch.parts.join("\n").trim();
+  if (!combined) return;
+
+  // A lone, single-line "/something" is an unknown-command typo — guide the
+  // user instead of forwarding it to the agent. Split content never trips
+  // this: it arrives as multiple parts, and multi-line text is never a command.
+  if (batch.parts.length === 1 && !combined.includes("\n") && combined.startsWith("/")) {
+    await send(deps, chatId, "Unknown command. Type /help to see what I can do.");
+    return;
+  }
+
+  const rt = deps.registry.get(chatId);
+  const note = batch.parts.length > 1 ? ` (combined ${batch.parts.length} messages)` : "";
+  try {
+    const outcome = await rt.submit(textPrompt(combined));
+    if (outcome === "queued") {
+      await send(
+        deps,
+        chatId,
+        `\u{1F4E5} Queued (position ${rt.queueLength})${note} \u2014 I'm still working on the previous task. It'll run next.`,
+      );
+    }
+  } catch (err) {
+    log.warn(`submit failed for chat ${chatId}: ${(err as Error).message}`);
+    await send(deps, chatId, `\u274C Couldn't start your message: ${(err as Error).message}`);
+  }
+}
+
+async function send(deps: BotDeps, chatId: number, text: string): Promise<void> {
+  try {
+    await deps.api.sendMessage(chatId, text);
+  } catch {
+    /* non-fatal */
+  }
+}

package/src/bot/handlers/photo.ts

@@ -0,0 +1,108 @@
+/**
+ * Photo & image-document handler. Downloads images (including multi-image
+ * albums / media groups) and submits them to Kiro as ACP image content blocks
+ * alongside the caption text.
+ */
+import type { Bot, Context } from "grammy";
+import type { PromptImage } from "../../app/types.js";
+import { createLogger } from "../../logger.js";
+import type { BotDeps } from "../deps.js";
+
+const log = createLogger("photo");
+const GROUP_DEBOUNCE_MS = 900;
+
+interface GroupBuffer {
+  chatId: number;
+  caption: string;
+  images: PromptImage[];
+  timer: NodeJS.Timeout;
+}
+
+export function registerPhotos(bot: Bot, deps: BotDeps): void {
+  const groups = new Map<string, GroupBuffer>();
+
+  const onMedia = async (ctx: Context, image: PromptImage | undefined, caption: string): Promise<void> => {
+    if (!image) return;
+    const chatId = ctx.chat!.id;
+
+    // Don't hijack the task wizard.
+    if (deps.wizard.isActive(chatId)) {
+      await ctx.reply("Finish or /cancel the current task wizard before sending images.");
+      return;
+    }
+
+    const groupId = ctx.message?.media_group_id;
+    if (!groupId) {
+      await submit(deps, chatId, caption, [image]);
+      return;
+    }
+
+    // Buffer album items and submit once the group settles.
+    const existing = groups.get(groupId);
+    if (existing) {
+      clearTimeout(existing.timer);
+      existing.images.push(image);
+      if (caption) existing.caption = caption;
+      existing.timer = setTimeout(() => flush(groups, groupId, deps), GROUP_DEBOUNCE_MS);
+    } else {
+      groups.set(groupId, {
+        chatId,
+        caption,
+        images: [image],
+        timer: setTimeout(() => flush(groups, groupId, deps), GROUP_DEBOUNCE_MS),
+      });
+    }
+  };
+
+  bot.on("message:photo", async (ctx) => {
+    const photos = ctx.message.photo;
+    const largest = photos[photos.length - 1];
+    const image = largest ? await download(ctx, largest.file_id, "image/jpeg", deps.cfg.token) : undefined;
+    await onMedia(ctx, image, ctx.message.caption ?? "");
+  });
+
+  bot.on("message:document", async (ctx, next) => {
+    const doc = ctx.message.document;
+    if (!doc.mime_type?.startsWith("image/")) return next(); // let document-handler logic pass
+    const image = await download(ctx, doc.file_id, doc.mime_type, deps.cfg.token);
+    await onMedia(ctx, image, ctx.message.caption ?? "");
+  });
+}
+
+async function flush(groups: Map<string, GroupBuffer>, groupId: string, deps: BotDeps): Promise<void> {
+  const buf = groups.get(groupId);
+  if (!buf) return;
+  groups.delete(groupId);
+  await submit(deps, buf.chatId, buf.caption, buf.images);
+}
+
+async function submit(deps: BotDeps, chatId: number, caption: string, images: PromptImage[]): Promise<void> {
+  const rt = deps.registry.get(chatId);
+  const outcome = await rt.submit({ text: caption, images });
+  if (outcome === "queued") {
+    await deps.api.sendMessage(
+      chatId,
+      `\u{1F4E5} Queued ${images.length} image${images.length > 1 ? "s" : ""} \u2014 will run after the current task.`,
+    );
+  }
+}
+
+async function download(
+  ctx: Context,
+  fileId: string,
+  mimeType: string,
+  token: string,
+): Promise<PromptImage | undefined> {
+  try {
+    const file = await ctx.api.getFile(fileId);
+    if (!file.file_path) return undefined;
+    const url = `https://api.telegram.org/file/bot${token}/${file.file_path}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    return { data: buf.toString("base64"), mimeType };
+  } catch (e) {
+    log.warn("image download failed:", (e as Error).message);
+    return undefined;
+  }
+}