grok-telegram-bot 2.0.0

package/src/bot/handlers/document.ts

@@ -0,0 +1,112 @@
+/**
+ * Document handler — non-image file attachments.
+ *
+ * The photo handler (registered earlier) claims image documents and passes
+ * everything else through to here. We download the file and either:
+ *   • inline its text (the common "long message became a .txt" case, plus code,
+ *     logs, JSON, CSV, …), truncated to `DOC_MAX_CHARS`, or
+ *   • for a binary file, save it under `<dataDir>/downloads` and tell the agent
+ *     the path so it can open it with its own tools.
+ *
+ * Like photos/voice, submissions respect the follow-up queue and any reply
+ * context (see reply-context.ts).
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import type { Bot, Context } from "grammy";
+import { textPrompt } from "../../app/types.js";
+import { createLogger } from "../../logger.js";
+import type { BotDeps } from "../deps.js";
+import {
+  decodeText,
+  formatBinaryFilePrompt,
+  formatTextFilePrompt,
+  looksLikeText,
+} from "../file-ingest.js";
+import { extractReplyContext } from "../reply-context.js";
+
+const log = createLogger("document");
+
+export function registerDocuments(bot: Bot, deps: BotDeps): void {
+  bot.on("message:document", async (ctx) => {
+    const doc = ctx.message.document;
+    // Image documents are downloaded & attached by the photo handler; it only
+    // forwards non-image documents here. This guard is a defensive no-op.
+    if (doc.mime_type?.startsWith("image/")) return;
+
+    const chatId = ctx.chat.id;
+    if (deps.wizard.isActive(chatId)) {
+      await ctx.reply("Finish or /cancel the current task wizard before sending files.");
+      return;
+    }
+
+    const name = doc.file_name?.trim() || "file";
+    await ctx.replyWithChatAction("typing").catch(() => {});
+
+    let buf: Buffer;
+    try {
+      buf = await download(ctx, doc.file_id, deps.cfg.token);
+    } catch (e) {
+      log.warn(`download failed for "${name}":`, (e as Error).message);
+      await ctx.reply(
+        `\u274C I couldn't download "${name}": ${(e as Error).message}. ` +
+          `(Telegram bots can fetch files up to 20 MB.)`,
+      );
+      return;
+    }
+
+    const caption = ctx.message.caption ?? "";
+    const quoted = extractReplyContext(ctx);
+    const replyTo = ctx.message.message_id;
+
+    let promptText: string;
+    if (looksLikeText(buf, doc.mime_type, name)) {
+      const full = decodeText(buf);
+      const max = deps.cfg.docMaxChars;
+      const truncated = max > 0 && full.length > max;
+      const content = truncated ? full.slice(0, max) : full;
+      promptText = formatTextFilePrompt(name, content, caption, truncated);
+    } else {
+      const savedPath = await persistBinary(deps.cfg.dataDir, name, buf).catch((e) => {
+        log.warn("saving binary failed:", (e as Error).message);
+        return undefined;
+      });
+      promptText = formatBinaryFilePrompt(name, doc.mime_type, buf.length, caption, savedPath);
+    }
+
+    try {
+      const rt = deps.registry.get(chatId);
+      const outcome = await rt.submit(textPrompt(promptText, replyTo, quoted));
+      if (outcome === "queued") {
+        await ctx.reply(`\u{1F4E5} Queued "${name}" \u2014 will run after the current task.`);
+      }
+    } catch (e) {
+      log.warn(`submit failed for "${name}":`, (e as Error).message);
+      await ctx.reply(`\u274C Couldn't process "${name}": ${(e as Error).message}`);
+    }
+  });
+}
+
+/** Download a Telegram file to a Buffer (subject to the 20 MB Bot API limit). */
+async function download(ctx: Context, fileId: string, token: string): Promise<Buffer> {
+  const file = await ctx.api.getFile(fileId);
+  if (!file.file_path) throw new Error("no file path returned");
+  const res = await fetch(`https://api.telegram.org/file/bot${token}/${file.file_path}`);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/** Persist a binary attachment under `<dataDir>/downloads`, returning its path. */
+async function persistBinary(dataDir: string, name: string, buf: Buffer): Promise<string> {
+  const dir = join(dataDir, "downloads");
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, `${Date.now()}-${sanitize(name)}`);
+  await writeFile(path, buf);
+  return path;
+}
+
+/** basename() strips any directory components; then keep only safe characters. */
+function sanitize(name: string): string {
+  const safe = basename(name).replace(/[^\w.\-]+/g, "_").slice(0, 120);
+  return safe.replace(/^\.+/, "") || "file";
+}

package/src/bot/handlers/history.ts

@@ -0,0 +1,63 @@
+/**
+ * /history — show the latest messages of the current (or a chosen) session.
+ */
+import type { Bot } from "grammy";
+import { basename } from "node:path";
+import type { BotDeps } from "../deps.js";
+import { readHistory } from "../../sessions/history.js";
+import { sessionHashtags } from "../../render/hashtags.js";
+import type { SessionMeta } from "../../sessions/types.js";
+import { sendMarkdownDoc } from "../telegram-io.js";
+
+const ENTRY_MAX = 700;
+const ROLE_ICON: Record<string, string> = {
+  user: "\u{1F464}",
+  assistant: "\u{1F916}",
+  tool: "\u{1F527}",
+  system: "\u2139\uFE0F",
+};
+
+export function registerHistory(bot: Bot, deps: BotDeps): void {
+  bot.command("history", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    if (!rt.sessionId) {
+      await ctx.reply("No active session. Use /sessions or send a message first.");
+      return;
+    }
+    const meta = deps.store.get(rt.sessionId);
+    await showHistory(deps, ctx.chat.id, rt.sessionId, meta, 16, rt.tags);
+  });
+}
+
+/** Render and send the recent history of a session. */
+export async function showHistory(
+  deps: BotDeps,
+  chatId: number,
+  sessionId: string,
+  meta?: SessionMeta,
+  count = 16,
+  tags?: string,
+): Promise<void> {
+  const entries = readHistory(deps.store.jsonlPath(sessionId), count);
+  if (entries.length === 0) {
+    await deps.api.sendMessage(chatId, "No history found for this session yet.");
+    return;
+  }
+  const title = meta?.title || sessionId.slice(0, 8);
+  const proj = meta?.cwd ? basename(meta.cwd) : "";
+  const header = `\u{1F4DC} **History** \u2014 ${title}${proj ? ` (${proj})` : ""}`;
+
+  const body = entries
+    .map((e) => {
+      const icon = ROLE_ICON[e.role] ?? "\u2022";
+      let text = e.text.length > ENTRY_MAX ? e.text.slice(0, ENTRY_MAX) + " …" : e.text;
+      if (e.role === "tool" && e.tool) text = `\`${e.tool}\` ${text}`;
+      return `${icon} ${text}`;
+    })
+    .join("\n\n");
+
+  // Every AI-output surface carries the session's searchable hashtags. A static
+  // view (no live runtime) tags at least project + session id.
+  const footer = tags ?? sessionHashtags({ cwd: meta?.cwd, sessionId });
+  await sendMarkdownDoc(deps.api, chatId, `${header}\n\n${body}\n\n${footer}`);
+}

package/src/bot/handlers/kill.ts

@@ -0,0 +1,54 @@
+/**
+ * /killall — terminate all active Grok sessions running on this PC (the ones
+ * holding a live session lock), excluding the bot's own agent process. Guarded
+ * by an inline confirmation since it kills processes.
+ */
+import { type Bot, type Context, InlineKeyboard } from "grammy";
+import { killPid } from "../../sessions/process.js";
+import type { SessionMeta } from "../../sessions/types.js";
+import type { BotDeps } from "../deps.js";
+
+function targets(deps: BotDeps): SessionMeta[] {
+  const self = deps.acp.pid;
+  return deps.store.listActive().filter((s) => s.lockPid && s.lockPid !== self);
+}
+
+export async function showKillConfirm(ctx: Context, deps: BotDeps): Promise<void> {
+  await deps.ephemeral.open(ctx);
+  const active = targets(deps);
+  if (active.length === 0) {
+    await deps.ephemeral.reply(ctx, "\u2705 No other active Grok sessions to kill.");
+    return;
+  }
+  const list = active
+    .slice(0, 12)
+    .map((s) => `\u2022 ${s.title.slice(0, 40)} (pid ${s.lockPid})`)
+    .join("\n");
+  const kb = new InlineKeyboard()
+    .text(`\u{1F6D1} Kill ${active.length}`, "killall:confirm")
+    .text("Cancel", "killall:cancel");
+  await deps.ephemeral.reply(
+    ctx,
+    `\u{1F6D1} Kill ${active.length} active session(s)?\n${list}\n\n(The bot's own session is excluded.)`,
+    { reply_markup: kb },
+  );
+}
+
+export function registerKill(bot: Bot, deps: BotDeps): void {
+  bot.command("killall", (ctx) => showKillConfirm(ctx, deps));
+
+  bot.callbackQuery("killall:cancel", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await ctx.editMessageText("Cancelled.").catch(() => {});
+  });
+
+  bot.callbackQuery("killall:confirm", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const active = targets(deps);
+    let killed = 0;
+    for (const s of active) {
+      if (s.lockPid && killPid(s.lockPid)) killed++;
+    }
+    await ctx.editMessageText(`\u{1F6D1} Killed ${killed} of ${active.length} active session(s).`).catch(() => {});
+  });
+}

package/src/bot/handlers/mcp.ts

@@ -0,0 +1,206 @@
+/**
+ * /mcp — inspect and control the Grok 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 ~/.grok/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 deps.ephemeral.open(ctx);
+  await deps.ephemeral.reply(ctx, 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 Grok 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,220 @@
+/**
+ * Menu handler — maps the persistent reply-keyboard buttons (matched by emoji
+ * prefix for stateful ones) to actions, and provides inline submenus for Agent
+ * (real Grok 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 { listAgents } from "../../agents/catalog.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 { showAccounts } from "./accounts.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> {
+  await deps.ephemeral.open(ctx);
+  const rt = deps.registry.get(ctx.chat!.id);
+  await deps.ephemeral.reply(ctx, "\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 Grok 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);
+      await deps.ephemeral.open(ctx);
+      return void deps.ephemeral.reply(ctx, deps.statusPanel.render(chatId));
+    case "usage":
+      await ctx.answerCallbackQuery();
+      return showUsage(ctx, deps);
+    case "accounts":
+      await ctx.answerCallbackQuery();
+      return showAccounts(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);
+  await deps.ephemeral.open(ctx);
+  const modes = deps.acp.availableModes.slice(0, 60);
+  if (modes.length === 0) {
+    // Grok has no headless agent switch; surface the sub-agents it can delegate
+    // to (built-ins + any custom ones in ~/.grok/user-settings.json) as info.
+    const subs = listAgents(rt.cwd).map((s) => s.name);
+    const info = subs.length
+      ? `Grok sub-agents available: ${subs.join(", ")}.\nGrok delegates to these automatically during a turn (via its task/delegate tools) — there's no headless agent switch. Use \u{1F9E9} Model to change the model.`
+      : "Grok delegates to built-in sub-agents automatically in headless mode; there's no agent to select. Use \u{1F9E9} Model to change the model.";
+    await deps.ephemeral.reply(ctx, `Current agent: ${rt.agent || "default"}\n${info}`);
+    return;
+  }
+  const kb = new InlineKeyboard();
+  modes.forEach((m, i) => kb.text(`${m.id === rt.agent ? "\u2713 " : ""}${m.name}`, `agent:set:${i}`).row());
+  await deps.ephemeral.reply(ctx, `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);
+  await deps.ephemeral.open(ctx);
+  const kb = new InlineKeyboard();
+  REASONING_LEVELS.forEach((l) => kb.text(`${l === rt.reasoning ? "\u2713 " : ""}${reasoningLabel(l)}`, `reason:${l}`));
+  await deps.ephemeral.reply(ctx, `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);
+  await deps.ephemeral.open(ctx);
+  const models = deps.acp.availableModels;
+  if (models.length === 0) {
+    await deps.ephemeral.reply(ctx, "No selectable models reported by Grok 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 deps.ephemeral.reply(ctx, `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 */
+  }
+}