grok-telegram-bot 2.0.0

package/src/bot/menu/ephemeral.ts

@@ -0,0 +1,117 @@
+/**
+ * Ephemeral message tracker — keeps the chat history clean.
+ *
+ * Navigation surfaces (the inline menu, session/project cards, pickers, status
+ * snapshots, submenus) are *transient*: they're tracked per chat and removed
+ * when a new surface opens or an action resolves. Persistent messages
+ * (🔀 Switched / ✨ New session boundary markers, agent output, Done summaries,
+ * the pinned status panel) are simply never tracked, so they survive clear().
+ *
+ * Tracked ids are persisted to disk so a restart (manual, crash, or
+ * auto-update) doesn't orphan the last surface — it's cleaned on startup and by
+ * the next surface that opens.
+ */
+import { join } from "node:path";
+import { type Api, type Context, GrammyError } from "grammy";
+import { JsonStore } from "../../app/json-store.js";
+
+type TrackMap = Record<string, number[]>;
+
+export class Ephemeral {
+  private readonly store: JsonStore<TrackMap>;
+  /** Per-chat promise chain so open/clear/reply never interleave for one chat
+   *  (e.g. startup cleanupAll racing the first surface the user opens). */
+  private readonly locks = new Map<number, Promise<unknown>>();
+
+  constructor(
+    private readonly api: Api,
+    dataDir: string,
+  ) {
+    this.store = new JsonStore<TrackMap>(join(dataDir, "ephemeral.json"), {});
+  }
+
+  /** Run `fn` after any in-flight ephemeral op for this chat completes. */
+  private serialize<T>(chatId: number, fn: () => Promise<T>): Promise<T> {
+    const prev = this.locks.get(chatId) ?? Promise.resolve();
+    const run = prev.then(fn, fn);
+    this.locks.set(chatId, run.then(noop, noop));
+    return run;
+  }
+
+  /** Track a bot message id for later cleanup. */
+  remember(chatId: number, messageId: number | undefined): void {
+    if (!messageId) return;
+    this.store.update((m) => {
+      const k = String(chatId);
+      (m[k] ??= []).push(messageId);
+    });
+  }
+
+  /** Delete every tracked transient message for a chat (best-effort). */
+  async clear(chatId: number | undefined): Promise<void> {
+    if (chatId === undefined) return;
+    await this.serialize(chatId, () => this.doClear(chatId));
+  }
+
+  private async doClear(chatId: number): Promise<void> {
+    const k = String(chatId);
+    const ids = (this.store.get()[k] ?? []).slice();
+    if (ids.length === 0) return;
+    // A Telegram rejection (message gone / too old / not found) is final, so we
+    // forget that id. A transient/network failure is KEPT for the next sweep so
+    // a tracked card never becomes a permanent "ghost" (the duplicate-cards bug).
+    const keep: number[] = [];
+    await Promise.all(
+      ids.map(async (id) => {
+        try {
+          await this.api.deleteMessage(chatId, id);
+        } catch (err) {
+          if (!(err instanceof GrammyError)) keep.push(id);
+        }
+      }),
+    );
+    this.store.update((m) => {
+      if (keep.length > 0) m[k] = keep;
+      else delete m[k];
+    });
+  }
+
+  /** On startup, delete any surface left over from before a restart. */
+  async cleanupAll(): Promise<void> {
+    for (const k of Object.keys(this.store.get())) {
+      await this.clear(Number(k));
+    }
+  }
+
+  /**
+   * Open a fresh navigation surface: clear whatever transient surface was up.
+   * Call at the start of every menu/card/picker handler.
+   */
+  async open(ctx: Context): Promise<void> {
+    await this.clear(ctx.chat?.id);
+  }
+
+  /** Send a transient reply (tracked) — use for menus / cards / pickers. */
+  async reply(ctx: Context, text: string, extra: Record<string, unknown> = {}): Promise<number | undefined> {
+    const chatId = ctx.chat?.id;
+    if (chatId === undefined) return undefined;
+    return this.serialize(chatId, async () => {
+      try {
+        const msg = await ctx.reply(text, extra);
+        this.remember(chatId, msg.message_id);
+        return msg.message_id;
+      } catch {
+        return undefined;
+      }
+    });
+  }
+
+  /** Delete just one tracked message (e.g. closing a single card). */
+  async drop(ctx: Context): Promise<void> {
+    await ctx.deleteMessage().catch(() => {});
+  }
+}
+
+function noop(): void {
+  /* swallow chain errors so serialize() keeps flowing */
+}

package/src/bot/menu/keyboard.ts

@@ -0,0 +1,49 @@
+/**
+ * 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{1F465} Accounts", "m:accounts")
+    .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,173 @@
+/**
+ * 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 { progressBar } from "../../render/progress.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");
+
+/** Minimum gap between pinned-panel edits per chat (coalesces bursty updates). */
+const REFRESH_THROTTLE_MS = 1000;
+
+export class StatusPanel {
+  /** Per-chat coalescing + serialization: only ONE refresh runs at a time per
+   *  chat, so concurrent state changes (e.g. many subagents updating at once)
+   *  can't each create a duplicate pinned panel. `again` collapses a burst into
+   *  a single follow-up run; `lastRun` throttles edits. */
+  private readonly busy = new Map<number, boolean>();
+  private readonly again = new Map<number, boolean>();
+  private readonly lastRun = new Map<number, number>();
+
+  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 meta = rt.contextInfo();
+    const ctxPct = meta?.contextUsagePercentage;
+    const running = this.registry.controller(chatId).count();
+    const subagents = this.registry.subagentSummaryForChat(chatId);
+    const progress = rt.taskProgress;
+
+    const SEP = " | "; // pipe delimiter between inline fields
+    const lines: string[] = [];
+
+    // 1) Progress first — only while a turn is live (cleared when it ends), so
+    //    the collapsed pin preview shows how far along the current task is.
+    if (progress !== undefined) lines.push(`\u{1F4C8} ${progressBar(progress)}`);
+
+    // 2) Activity: state + only the counters that currently apply.
+    const activity: string[] = [rt.isBusy ? "\u23F3 Working" : "\u2705 Idle"];
+    if (rt.queueLength > 0) activity.push(`\u{1F4E5} ${rt.queueLength} queued`);
+    if (running > 1) activity.push(`\u{1F9ED} ${running} sessions`);
+    if (rt.isWatching) activity.push("\u{1F4E1} watching");
+    if (subagents) activity.push(`\u{1F465} ${subagents}`);
+    lines.push(activity.join(SEP));
+
+    // 3) Where: project | session | context usage.
+    const loc = [`\u{1F4C1} ${project}`, `\u{1F9F5} ${session}`];
+    if (ctxPct !== undefined) loc.push(`\u{1F4CA} ${ctxPct.toFixed(0)}% context`);
+    lines.push(loc.join(SEP));
+
+    // 4) How: agent | reasoning | model.
+    lines.push([`\u{1F916} ${s.agent || "default"}`, `\u{1F9E0} ${reasoningLabel(s.reasoning)}`, `\u{1F9E9} ${s.model || "default"}`].join(SEP));
+
+    return lines.join("\n");
+  }
+
+  /** Coalesced, serialized refresh: only ONE update runs per chat at a time, so
+   *  rapid state changes (many subagents, fast tool calls) can't each create a
+   *  duplicate pinned panel. Extra requests during a run collapse into a single
+   *  follow-up run, throttled so we don't hammer Telegram with edits. */
+  async refresh(chatId: number): Promise<void> {
+    if (this.busy.get(chatId)) {
+      this.again.set(chatId, true);
+      return;
+    }
+    this.busy.set(chatId, true);
+    try {
+      do {
+        this.again.set(chatId, false);
+        const since = Date.now() - (this.lastRun.get(chatId) ?? 0);
+        if (since < REFRESH_THROTTLE_MS) await sleep(REFRESH_THROTTLE_MS - since);
+        await this.doRefresh(chatId);
+        this.lastRun.set(chatId, Date.now());
+      } while (this.again.get(chatId));
+    } finally {
+      this.busy.set(chatId, false);
+    }
+  }
+
+  /** One render + send/edit/remove pass. Never spawns a duplicate panel: it only
+   *  (re)creates when there's no panel yet, or the existing one is truly gone. */
+  private async doRefresh(chatId: number): Promise<void> {
+    const rt = this.registry.get(chatId);
+    const id = this.settings.get(chatId).statusMessageId;
+
+    // The pinned panel exists only while there's live work — a running turn or a
+    // queued follow-up about to run. When the session is idle there's nothing to
+    // show, so remove the panel to keep the chat clean. (The on-demand /status
+    // still renders full state when explicitly requested.)
+    const active = rt.isBusy || rt.queueLength > 0;
+    if (!active) {
+      if (id) await this.remove(chatId, id);
+      return;
+    }
+
+    const text = this.render(chatId);
+    if (id) {
+      try {
+        await this.api.editMessageText(chatId, id, text);
+        return;
+      } catch (err) {
+        if (isNotModified(err)) return;
+        // Only recreate when the panel is genuinely gone — a transient failure
+        // (429 / network) must NOT spawn a duplicate; skip and retry next time.
+        if (!isMessageGone(err)) {
+          log.debug("status edit failed (transient), keeping panel:", (err as Error).message);
+          return;
+        }
+        log.debug("status panel gone, recreating:", (err as Error).message);
+      }
+    }
+    await this.create(chatId, text);
+  }
+
+  /** Remove the pinned panel (unpin + delete) and forget its id. */
+  private async remove(chatId: number, id: number): Promise<void> {
+    this.settings.update(chatId, { statusMessageId: undefined });
+    try {
+      await this.api.deleteMessage(chatId, id); // deleting a pinned message also unpins it
+    } catch {
+      try {
+        await this.api.unpinChatMessage(chatId, id);
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+
+  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);
+    }
+  }
+}
+
+function isNotModified(err: unknown): boolean {
+  return err instanceof GrammyError && /not modified/i.test(err.description);
+}
+
+/** True only when the panel message is genuinely gone (so recreating is the
+ *  right move) — never for transient errors like 429 or network blips. */
+function isMessageGone(err: unknown): boolean {
+  return (
+    err instanceof GrammyError &&
+    /message to edit not found|message can't be edited|message_id_invalid|message to be edited/i.test(err.description)
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/bot/permission-service.ts

@@ -0,0 +1,149 @@
+/**
+ * PermissionService — turns Grok'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 "../grok/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} Grok 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,64 @@
+/**
+ * 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 "../grok/types.js";
+import type { PromptInput } from "../app/types.js";
+
+export interface ContentOptions {
+  reasoning?: string;
+  priming?: string;
+  /** Appended at the very bottom so the agent emits a `{progress: N%}` marker. */
+  progress?: 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 (input.quotedText?.trim()) {
+    const quoted = input.quotedText.trim();
+    const body = text || "(the user's reply carried no additional text)";
+    text = `The user is replying to this earlier message:\n\n<<<\n${quoted}\n>>>\n\n${body}`;
+  }
+  if (opts.priming) {
+    text = `${opts.priming}\n\n---\n\nUser's new message:\n${text}`;
+  }
+  if (opts.reasoning) {
+    text = `(${opts.reasoning})\n\n${text}`;
+  }
+  if (opts.progress) {
+    text = `${text}\n\n${opts.progress}`;
+  }
+
+  blocks.push({ type: "text", text });
+  return blocks;
+}
+
+/** Merge queued inputs into a single prompt (concatenated text, all images). */
+export function mergeInputs(inputs: PromptInput[]): PromptInput {
+  const quotes = inputs
+    .map((i) => i.quotedText?.trim())
+    .filter((q): q is string => !!q);
+  return {
+    text: inputs
+      .map((i) => i.text)
+      .filter((t) => t.trim().length > 0)
+      .join("\n\n"),
+    images: inputs.flatMap((i) => i.images),
+    replyTo: inputs.find((i) => i.replyTo !== undefined)?.replyTo,
+    quotedText: quotes.length > 0 ? [...new Set(quotes)].join("\n\n---\n\n") : undefined,
+  };
+}
+
+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}`;
+}