kiro-telegram-bot 1.5.1

package/src/bot/handlers/usage.ts

@@ -0,0 +1,33 @@
+/**
+ * /usage — show account info and the current session's context usage.
+ */
+import type { Bot, Context } from "grammy";
+import type { BotDeps } from "../deps.js";
+
+export async function showUsage(ctx: Context, deps: BotDeps): Promise<void> {
+  await ctx.replyWithChatAction("typing").catch(() => {});
+  const rt = deps.registry.get(ctx.chat!.id);
+  const acct = await deps.usage.account();
+  const meta = rt.contextInfo();
+  const ctx100 = meta?.contextUsagePercentage;
+
+  const lines = [
+    "\u{1F4CA} Usage & account",
+    acct?.email ? `\u{1F464} ${acct.email}` : "",
+    acct?.accountType ? `\u{1F511} ${acct.accountType}${acct.region ? ` \u00B7 ${acct.region}` : ""}` : "",
+    "",
+    `\u{1F9F5} Session: ${rt.sessionId ? rt.sessionId.slice(0, 8) : "none"}`,
+    `\u{1F9E9} Model: ${rt.model || "default"}`,
+    `\u{1F4CA} Context used: ${ctx100 !== undefined ? `${ctx100.toFixed(0)}%` : "\u2014"}`,
+    meta?.effort ? `\u{1F9E0} Effort: ${meta.effort}` : "",
+    "",
+    "\u2139\uFE0F Full billing/quota lives in the Kiro app, or run /usage inside `kiro-cli chat`.",
+  ].filter(Boolean);
+
+  if (!acct) lines.splice(1, 0, "(account info unavailable \u2014 is kiro-cli logged in?)");
+  await ctx.reply(lines.join("\n"));
+}
+
+export function registerUsage(bot: Bot, deps: BotDeps): void {
+  bot.command("usage", (ctx) => showUsage(ctx, deps));
+}

package/src/bot/handlers/voice.ts

@@ -0,0 +1,53 @@
+/**
+ * Voice & audio handler — transcribes Telegram voice notes / audio files to
+ * text (any language) and submits them as prompts.
+ */
+import type { Bot, Context } from "grammy";
+import { textPrompt } from "../../app/types.js";
+import { createLogger } from "../../logger.js";
+import type { BotDeps } from "../deps.js";
+
+const log = createLogger("voice");
+
+export function registerVoice(bot: Bot, deps: BotDeps): void {
+  const handle = async (ctx: Context, fileId: string, mime: string, name: string): Promise<void> => {
+    const chatId = ctx.chat!.id;
+    if (deps.wizard.isActive(chatId)) {
+      await ctx.reply("Finish or /cancel the task wizard before sending voice.");
+      return;
+    }
+    if (!deps.stt.enabled) {
+      await ctx.reply("\u{1F399} Voice isn't configured. Set STT_API_URL (and STT_API_KEY) in .env.");
+      return;
+    }
+    await ctx.replyWithChatAction("typing").catch(() => {});
+    try {
+      const bytes = await download(ctx, fileId, deps.cfg.token);
+      if (!bytes) throw new Error("could not download the audio");
+      const text = await deps.stt.transcribe(bytes, mime, name);
+      if (!text) {
+        await ctx.reply("\u{1F399} I couldn't make out any speech.");
+        return;
+      }
+      await ctx.reply(`\u{1F399} \u201C${text}\u201D`);
+      const rt = deps.registry.get(chatId);
+      const outcome = await rt.submit(textPrompt(text));
+      if (outcome === "queued") await ctx.reply("\u{1F4E5} Queued \u2014 will run after the current task.");
+    } catch (e) {
+      log.warn("voice failed:", (e as Error).message);
+      await ctx.reply(`\u274C Voice transcription failed: ${(e as Error).message}`);
+    }
+  };
+
+  bot.on("message:voice", (ctx) => handle(ctx, ctx.message.voice.file_id, ctx.message.voice.mime_type || "audio/ogg", "voice.ogg"));
+  bot.on("message:audio", (ctx) => handle(ctx, ctx.message.audio.file_id, ctx.message.audio.mime_type || "audio/mpeg", ctx.message.audio.file_name || "audio.mp3"));
+  bot.on("message:video_note", (ctx) => handle(ctx, ctx.message.video_note.file_id, "video/mp4", "note.mp4"));
+}
+
+async function download(ctx: Context, fileId: string, token: string): Promise<Buffer | undefined> {
+  const file = await ctx.api.getFile(fileId);
+  if (!file.file_path) return undefined;
+  const res = await fetch(`https://api.telegram.org/file/bot${token}/${file.file_path}`);
+  if (!res.ok) throw new Error(`download HTTP ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}

package/src/bot/image-return.ts

@@ -0,0 +1,69 @@
+/**
+ * Agent image return — detects image files the agent produced this turn
+ * (screenshots, diagrams…) from its output and tool inputs, and sends them
+ * back to Telegram. Only fresh files (modified during the turn) are sent.
+ */
+import { type Api, InputFile } from "grammy";
+import { existsSync, statSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("image-return");
+
+const PATH_RE = /[^\s"'`<>|()*\[\]]+\.(?:png|jpe?g|gif|webp|bmp)/gi;
+const PHOTO_EXT = new Set(["png", "jpg", "jpeg", "webp"]);
+const MAX_PHOTO_BYTES = 10 * 1024 * 1024;
+const MAX_FILE_BYTES = 45 * 1024 * 1024;
+
+/** Pull candidate image paths out of arbitrary text, resolved against cwd. */
+export function extractImagePaths(text: string, cwd: string): string[] {
+  const out = new Set<string>();
+  for (const m of text.matchAll(PATH_RE)) {
+    const raw = m[0].replace(/[).,;:]+$/, "");
+    out.add(isAbsolute(raw) ? raw : join(cwd, raw));
+  }
+  return [...out];
+}
+
+export interface SendImagesOptions {
+  /** Only send files modified at/after this epoch ms (fresh this turn). */
+  since: number;
+  /** Paths already sent (mutated to dedupe). */
+  already: Set<string>;
+  /** Max images to send in this call. */
+  max: number;
+}
+
+/** Send the valid, fresh, not-yet-sent images. Returns how many were sent. */
+export async function sendImages(
+  api: Api,
+  chatId: number,
+  paths: string[],
+  opts: SendImagesOptions,
+): Promise<number> {
+  let sent = 0;
+  for (const path of paths) {
+    if (sent >= opts.max) break;
+    if (opts.already.has(path)) continue;
+    let st: ReturnType<typeof statSync>;
+    try {
+      st = statSync(path);
+    } catch {
+      continue;
+    }
+    if (!st.isFile() || st.size === 0 || st.size > MAX_FILE_BYTES) continue;
+    if (st.mtimeMs < opts.since - 2000) continue; // skip pre-existing files
+    opts.already.add(path);
+    try {
+      const ext = path.toLowerCase().split(".").pop() ?? "";
+      const asPhoto = PHOTO_EXT.has(ext) && st.size <= MAX_PHOTO_BYTES;
+      const file = new InputFile(path);
+      if (asPhoto) await api.sendPhoto(chatId, file, { caption: basename(path) });
+      else await api.sendDocument(chatId, file, { caption: basename(path) });
+      sent++;
+    } catch (e) {
+      log.debug(`failed to send ${path}:`, (e as Error).message);
+    }
+  }
+  return sent;
+}

package/src/bot/menu/keyboard.ts

@@ -0,0 +1,47 @@
+/**
+ * Menu surfaces:
+ *  - a tiny PERSISTENT bar (☰ Menu · 🧭 Running · ⏹ Stop) — minimal footprint;
+ *  - a full, organized INLINE menu opened on demand (and hideable).
+ * Live state (project/agent/model/reasoning/context) lives in the pinned panel,
+ * so the bar stays clean.
+ */
+import { InlineKeyboard, Keyboard } from "grammy";
+
+export const MENU_BTN = "\u2630 Menu"; // ☰
+export const RUNNING_BTN = "\u{1F9ED} Running";
+export const STOP_BTN = "\u23F9 Stop";
+export const BAR_LABELS = [MENU_BTN, RUNNING_BTN, STOP_BTN];
+
+/** The always-visible compact bar. */
+export function compactKeyboard(): Keyboard {
+  return new Keyboard().text(MENU_BTN).text(RUNNING_BTN).text(STOP_BTN).resized().persistent();
+}
+
+/** The full, grouped inline menu (opened via ☰ Menu or /menu). */
+export function mainMenuInline(state: { agent: string; model: string; reasoning: string }): InlineKeyboard {
+  const t = (s: string, n: number): string => (s.length > n ? s.slice(0, n - 1) + "\u2026" : s);
+  return new InlineKeyboard()
+    .text("\u{1F4C1} Project", "m:project")
+    .text("\u{1F195} New", "m:new")
+    .row()
+    .text("\u{1F9ED} Running", "m:running")
+    .text("\u{1F5C2} Sessions", "m:sessions")
+    .row()
+    .text(`\u{1F916} Agent \u00B7 ${t(state.agent, 24)}`, "m:agent")
+    .row()
+    .text(`\u{1F9E9} Model \u00B7 ${t(state.model, 24)}`, "m:model")
+    .row()
+    .text(`\u{1F9E0} Reasoning \u00B7 ${t(state.reasoning, 24)}`, "m:reasoning")
+    .row()
+    .text("\u2705 Tasks", "m:tasks")
+    .text("\u{1F4CA} Status", "m:status")
+    .text("\u{1F4B3} Usage", "m:usage")
+    .row()
+    .text("\u{1F9E9} MCP", "m:mcp")
+    .text("\u23F9 Stop", "m:stop")
+    .text("\u{1F6D1} Kill all", "m:killall")
+    .row()
+    .text("\u2328\uFE0F Show bar", "m:showbar")
+    .text("\u{1F648} Hide bar", "m:hidebar")
+    .text("\u2716 Close", "m:close");
+}

package/src/bot/menu/refresh.ts

@@ -0,0 +1,13 @@
+/**
+ * Sends a short message that (re)shows the compact bar and refreshes the pinned
+ * status panel (where the live project/agent/model/reasoning state is shown).
+ */
+import type { Context } from "grammy";
+import type { BotDeps } from "../deps.js";
+import { compactKeyboard } from "./keyboard.js";
+
+export async function refreshMenu(ctx: Context, deps: BotDeps, text: string): Promise<void> {
+  const chatId = ctx.chat!.id;
+  await ctx.reply(text, { reply_markup: compactKeyboard() });
+  await deps.statusPanel.refresh(chatId);
+}

package/src/bot/menu/status-panel.ts

@@ -0,0 +1,78 @@
+/**
+ * Status panel — a pinned message that always shows the current project,
+ * agent, reasoning effort, model, session and activity. Updated whenever the
+ * runtime's state changes. The pinned message id is persisted per chat.
+ */
+import { type Api, GrammyError } from "grammy";
+import { basename } from "node:path";
+import { reasoningLabel } from "../../app/reasoning.js";
+import type { SettingsStore } from "../../app/settings-store.js";
+import { createLogger } from "../../logger.js";
+import type { RuntimeRegistry } from "../registry.js";
+
+const log = createLogger("status-panel");
+
+export class StatusPanel {
+  constructor(
+    private readonly api: Api,
+    private readonly settings: SettingsStore,
+    private readonly registry: RuntimeRegistry,
+  ) {}
+
+  /** Build the status text from settings + live runtime state. */
+  render(chatId: number): string {
+    const s = this.settings.get(chatId);
+    const rt = this.registry.get(chatId);
+    // Project comes from the live foreground runtime — not the persisted single
+    // session — so it always matches the session id shown below, even right
+    // after switching between controlled sessions in different projects.
+    const project = rt.projectName || (rt.cwd ? basename(rt.cwd) : "(none)");
+    const session = rt.sessionId ? rt.sessionId.slice(0, 8) : "none";
+    const state = rt.isBusy ? "\u23F3 working" : "\u2705 idle";
+    const watch = rt.isWatching ? "  \u{1F4E1} watching" : "";
+    const meta = rt.contextInfo();
+    const ctx = meta?.contextUsagePercentage !== undefined ? `${meta.contextUsagePercentage.toFixed(0)}%` : "\u2014";
+    const running = this.registry.controller(chatId).count();
+    const sessionLine = running > 1 ? `${session}   \u{1F9ED} ${running} controlled` : session;
+    const lines = [
+      "\u{1F4CA} Kiro \u2014 Status",
+      `\u{1F4C1} Project:   ${project}`,
+      `\u{1F916} Agent:     ${s.agent || "default"}`,
+      `\u{1F9E0} Reasoning: ${reasoningLabel(s.reasoning)}`,
+      `\u{1F9E9} Model:     ${s.model || "default"}`,
+      `\u{1F9F5} Session:   ${sessionLine}`,
+      `\u{1F4CA} Context:   ${ctx} used`,
+      `\u2699\uFE0F State:     ${state}   \u{1F4E5} Queue: ${rt.queueLength}${watch}`,
+    ];
+    const subagents = this.registry.subagentSummaryForChat(chatId);
+    if (subagents) lines.push(`\u{1F465} Subagents: ${subagents}`);
+    return lines.join("\n");
+  }
+
+  /** Refresh (or create + pin) the status message for a chat. */
+  async refresh(chatId: number): Promise<void> {
+    const text = this.render(chatId);
+    const id = this.settings.get(chatId).statusMessageId;
+
+    if (id) {
+      try {
+        await this.api.editMessageText(chatId, id, text);
+        return;
+      } catch (err) {
+        if (err instanceof GrammyError && /not modified/i.test(err.description)) return;
+        log.debug("status edit failed, recreating:", (err as Error).message);
+      }
+    }
+    await this.create(chatId, text);
+  }
+
+  private async create(chatId: number, text: string): Promise<void> {
+    try {
+      const msg = await this.api.sendMessage(chatId, text, { disable_notification: true });
+      this.settings.update(chatId, { statusMessageId: msg.message_id });
+      await this.api.pinChatMessage(chatId, msg.message_id, { disable_notification: true });
+    } catch (err) {
+      log.debug("status create/pin failed:", (err as Error).message);
+    }
+  }
+}

package/src/bot/permission-service.ts

@@ -0,0 +1,149 @@
+/**
+ * PermissionService — turns Kiro's ACP `session/request_permission` into inline
+ * Approve/Deny buttons. It names the session that needs approval, sends the
+ * prompt WITH sound (it requires interaction), and — when the request belongs to
+ * a *background* session — adds a "🔀 Switch to it" button. The Allow/Deny
+ * buttons resolve the request in place, without switching.
+ */
+import type { Api } from "grammy";
+import { InlineKeyboard } from "grammy";
+import type { PermissionOutcome, RequestPermissionParams } from "../acp/types.js";
+import { createLogger } from "../logger.js";
+import type { RuntimeRegistry } from "./registry.js";
+
+const log = createLogger("permissions");
+const TIMEOUT_MS = 10 * 60 * 1000;
+
+const KIND_ICON: Record<string, string> = {
+  read: "\u{1F4D6}",
+  edit: "\u270F\uFE0F",
+  execute: "\u{1F4BB}",
+  delete: "\u{1F5D1}\uFE0F",
+  move: "\u{1F4E6}",
+  fetch: "\u{1F310}",
+};
+
+interface Pending {
+  resolve: (o: PermissionOutcome) => void;
+  options: RequestPermissionParams["options"];
+  chatId: number;
+  sessionId: string;
+  messageId?: number;
+  timer: NodeJS.Timeout;
+}
+
+export class PermissionService {
+  private readonly pending = new Map<string, Pending>();
+  private seq = 0;
+
+  constructor(
+    private readonly api: Api,
+    private readonly registry: RuntimeRegistry,
+  ) {}
+
+  /** Handle a permission request: ask the owning chat, or auto-allow if none. */
+  async handle(params: RequestPermissionParams): Promise<PermissionOutcome> {
+    const desc = this.registry.describeSession(params.sessionId);
+    const chatId = desc.chatId;
+    if (chatId === undefined) return autoDecide(params); // unattended (e.g. scheduled task / orphan subagent)
+
+    const reqId = String(++this.seq);
+    const isForeground = !desc.subagent && this.registry.get(chatId).sessionId === params.sessionId;
+    // A "Switch to it" button only makes sense for a real, controlled background
+    // session — never for the foreground, and never for a subagent (which the
+    // chat doesn't control directly).
+    const canSwitch = desc.controlled && !isForeground;
+    const label = desc.subagent
+      ? desc.subagentName || "subagent"
+      : desc.projectName || params.sessionId.slice(0, 8);
+
+    const kb = new InlineKeyboard();
+    params.options.forEach((o, i) => kb.text(buttonLabel(o), `perm:${reqId}:${i}`));
+    kb.row();
+    if (canSwitch) kb.text(`\u{1F500} Switch to ${label}`, `permsw:${reqId}`);
+
+    let messageId: number | undefined;
+    try {
+      const msg = await this.api.sendMessage(
+        chatId,
+        describe(params, { label: isForeground ? undefined : label, subagent: desc.subagent, canSwitch }),
+        {
+          reply_markup: kb,
+          disable_notification: false, // requires interaction → always with sound
+        },
+      );
+      messageId = msg.message_id;
+    } catch (e) {
+      log.warn("failed to send permission prompt:", (e as Error).message);
+      return autoDecide(params);
+    }
+
+    return new Promise<PermissionOutcome>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(reqId);
+        void this.api.editMessageText(chatId, messageId!, "\u231B Approval timed out \u2014 denied.").catch(() => {});
+        resolve({ outcome: { outcome: "cancelled" } });
+      }, TIMEOUT_MS);
+      this.pending.set(reqId, { resolve, options: params.options, chatId, sessionId: params.sessionId, messageId, timer });
+    });
+  }
+
+  /** Resolve a pending request from a button tap; returns the chosen label. */
+  resolveChoice(reqId: string, index: number): string | undefined {
+    const p = this.pending.get(reqId);
+    if (!p) return undefined;
+    clearTimeout(p.timer);
+    this.pending.delete(reqId);
+    const opt = p.options[index];
+    if (!opt) {
+      p.resolve({ outcome: { outcome: "cancelled" } });
+      return undefined;
+    }
+    p.resolve({ outcome: { outcome: "selected", optionId: opt.optionId } });
+    return opt.name;
+  }
+
+  /** The session a pending request belongs to (for the Switch button). */
+  sessionFor(reqId: string): string | undefined {
+    return this.pending.get(reqId)?.sessionId;
+  }
+}
+
+function describe(
+  params: RequestPermissionParams,
+  ctx: { label?: string; subagent: boolean; canSwitch: boolean },
+): string {
+  const tc = params.toolCall;
+  const kind = (tc?.kind || "other").toLowerCase();
+  const icon = KIND_ICON[kind] ?? "\u{1F527}";
+  const title = tc?.title || kind;
+  const raw = (tc?.rawInput || {}) as Record<string, unknown>;
+  const cmd = typeof raw.command === "string" ? raw.command : undefined;
+  const path = typeof raw.path === "string" ? raw.path : undefined;
+  const detail = cmd ? `\n\n$ ${cmd}` : path ? `\n\n${path}` : "";
+  const who = ctx.subagent
+    ? `\u{1F916}\u{1F510} Subagent "${ctx.label}" needs approval to run a tool:`
+    : ctx.label
+      ? `\u{1F510} Session "${ctx.label}" needs approval to run a tool:`
+      : "\u{1F510} Kiro wants to run a tool:";
+  const tail = ctx.canSwitch
+    ? "\n\nApprove here (no switch), or \u{1F500} switch to that session."
+    : ctx.subagent
+      ? "\n\nApprove for the subagent to continue?"
+      : "\n\nApprove?";
+  return `${who}\n${icon} ${title}${detail}${tail}`;
+}
+
+function buttonLabel(o: { name: string; kind?: string }): string {
+  const k = `${o.kind ?? ""} ${o.name}`.toLowerCase();
+  const icon = /reject|deny|no|cancel/.test(k) ? "\u26D4" : /always|all/.test(k) ? "\u2705\u267E\uFE0F" : "\u2705";
+  return `${icon} ${o.name}`;
+}
+
+/** Pick an allow option when nobody can be asked (otherwise cancel). */
+function autoDecide(params: RequestPermissionParams): PermissionOutcome {
+  const allow = params.options.find((o) => /allow|approve|yes|once/i.test(`${o.kind ?? ""} ${o.name}`));
+  return allow
+    ? { outcome: { outcome: "selected", optionId: allow.optionId } }
+    : { outcome: { outcome: "cancelled" } };
+}

package/src/bot/prompt-content.ts

@@ -0,0 +1,49 @@
+/**
+ * Build ACP prompt content blocks from a PromptInput (text + images), applying
+ * the reasoning directive and any fork-priming context. Also merges multiple
+ * queued inputs into one.
+ */
+import type { ContentBlock } from "../acp/types.js";
+import type { PromptInput } from "../app/types.js";
+
+export interface ContentOptions {
+  reasoning?: string;
+  priming?: string;
+}
+
+export function buildContentBlocks(input: PromptInput, opts: ContentOptions = {}): ContentBlock[] {
+  const blocks: ContentBlock[] = [];
+
+  for (const img of input.images) {
+    blocks.push({ type: "image", data: img.data, mimeType: img.mimeType });
+  }
+
+  let text = input.text.trim();
+  if (!text && input.images.length > 0) {
+    text = input.images.length === 1 ? "Please analyze the attached image." : "Please analyze the attached images.";
+  }
+  if (opts.priming) {
+    text = `${opts.priming}\n\n---\n\nUser's new message:\n${text}`;
+  }
+  if (opts.reasoning) {
+    text = `(${opts.reasoning})\n\n${text}`;
+  }
+
+  blocks.push({ type: "text", text });
+  return blocks;
+}
+
+/** Merge queued inputs into a single prompt (concatenated text, all images). */
+export function mergeInputs(inputs: PromptInput[]): PromptInput {
+  return {
+    text: inputs
+      .map((i) => i.text)
+      .filter((t) => t.trim().length > 0)
+      .join("\n\n"),
+    images: inputs.flatMap((i) => i.images),
+  };
+}
+
+export function imageSummary(input: PromptInput): string {
+  return input.images.length > 0 ? ` (+${input.images.length} image${input.images.length > 1 ? "s" : ""})` : "";
+}

package/src/bot/prompt-retry.ts

@@ -0,0 +1,70 @@
+/**
+ * Transient-prompt retry policy + the user-facing copy that goes with it.
+ *
+ * Policy: when a prompt fails with a *transient* agent error (e.g. "high volume
+ * of traffic" / -32603 "Internal error") **before any output streamed**, wait
+ * and retry with an exponential backoff that starts at 6s and doubles up to a
+ * 60s (1 minute) cap, then gives up with a summary. The user always sees the
+ * real error text on every attempt — we only add the retry/▶ summary line.
+ */
+
+/** First backoff delay (ms). */
+export const RETRY_BASE_MS = 6_000;
+/** Maximum backoff delay (ms) — "up to 1 minute". */
+export const RETRY_CAP_MS = 60_000;
+
+/**
+ * Backoff delays (ms) preceding each retry, doubling from {@link RETRY_BASE_MS}
+ * and capped at {@link RETRY_CAP_MS}. The schedule stops once it hits the cap,
+ * and never exceeds `maxRetries` entries.
+ *
+ * `maxRetries >= 5` ⇒ `[6000, 12000, 24000, 48000, 60000]`.
+ */
+export function backoffSchedule(maxRetries: number): number[] {
+  const out: number[] = [];
+  let delay = RETRY_BASE_MS;
+  for (let i = 0; i < maxRetries; i++) {
+    out.push(Math.min(delay, RETRY_CAP_MS));
+    if (delay >= RETRY_CAP_MS) break;
+    delay *= 2;
+  }
+  return out;
+}
+
+/** Human-friendly seconds label, e.g. 6000 → "6s", 90000 → "1m 30s". */
+export function fmtSeconds(ms: number): string {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rem = s % 60;
+  return rem ? `${m}m ${rem}s` : `${m}m`;
+}
+
+/**
+ * Message shown when an attempt fails but another retry is scheduled. Shows the
+ * real error verbatim so the user can act on it (e.g. switch model), plus when
+ * the next attempt runs.
+ */
+export function formatRetryNotice(
+  error: Error,
+  nextAttempt: number,
+  totalAttempts: number,
+  waitMs: number,
+): string {
+  return [
+    `\u26A0\uFE0F ${error.message}`,
+    "",
+    `\u{1F501} Retrying in ${fmtSeconds(waitMs)} \u2014 attempt ${nextAttempt} of ${totalAttempts}\u2026`,
+  ].join("\n");
+}
+
+/** Final summary shown after all retries are exhausted (or retry was unsafe). */
+export function formatErrorSummary(error: Error, elapsed: string, attempts: number, transient: boolean): string {
+  const tip = transient
+    ? "\n\n\u{1F4A1} Try a different model (tap \u{1F9E9} Model or /model <id>), or send again later."
+    : "";
+  if (attempts <= 1) {
+    return `\u274C Error after ${elapsed}: ${error.message}${tip}`;
+  }
+  return `\u274C Gave up after ${attempts} attempts over ${elapsed}.\nLast error: ${error.message}${tip}`;
+}