grok-telegram-bot 2.0.0

package/src/bot/file-ingest.ts

@@ -0,0 +1,190 @@
+/**
+ * Document ingestion helpers.
+ *
+ * Telegram delivers non-photo attachments as *documents*. The most common case
+ * for this bot is a **long message that a Telegram client turned into a `.txt`
+ * file** (Desktop does this when you paste more than a few thousand characters),
+ * but users also drop code, logs, JSON, CSV, etc. We want the agent to actually
+ * *read* those, so this module:
+ *   • decides whether a downloaded file is text (mime + extension hints, plus a
+ *     content sniff so mislabeled `application/octet-stream` code files work),
+ *   • decodes text (stripping BOMs), and
+ *   • formats a clear prompt for either a text or a binary attachment.
+ *
+ * Image documents are handled separately (see handlers/photo.ts).
+ */
+
+/** MIME prefixes that are always textual. */
+const TEXT_MIME_PREFIXES = ["text/"];
+
+/** Exact MIME types that are textual despite an `application/*` namespace. */
+const TEXT_MIME_EXACT = new Set([
+  "application/json",
+  "application/ld+json",
+  "application/xml",
+  "application/javascript",
+  "application/x-javascript",
+  "application/typescript",
+  "application/x-typescript",
+  "application/x-yaml",
+  "application/yaml",
+  "application/toml",
+  "application/x-toml",
+  "application/x-sh",
+  "application/x-shellscript",
+  "application/x-httpd-php",
+  "application/sql",
+  "application/graphql",
+  "application/x-ndjson",
+  "application/csv",
+  "application/x-tex",
+  "application/x-latex",
+  "image/svg+xml",
+]);
+
+/** File extensions we treat as text (used when the MIME type is missing/generic). */
+const TEXT_EXTENSIONS = new Set([
+  "txt", "text", "md", "markdown", "mdx", "rst", "adoc", "log", "csv", "tsv",
+  "json", "json5", "jsonl", "ndjson", "xml", "yaml", "yml", "toml", "ini", "cfg",
+  "conf", "config", "env", "properties", "editorconfig", "gitignore", "gitattributes",
+  "js", "mjs", "cjs", "jsx", "ts", "tsx", "mts", "cts", "py", "pyi", "rb", "php",
+  "java", "kt", "kts", "go", "rs", "c", "h", "cpp", "cxx", "cc", "hpp", "hxx", "cs",
+  "swift", "m", "mm", "sh", "bash", "zsh", "fish", "ps1", "psm1", "bat", "cmd",
+  "sql", "graphql", "gql", "html", "htm", "xhtml", "css", "scss", "sass", "less",
+  "vue", "svelte", "astro", "gradle", "groovy", "lua", "pl", "pm", "r", "dart",
+  "scala", "clj", "cljs", "edn", "ex", "exs", "erl", "hrl", "hs", "ml", "mli",
+  "fs", "fsx", "vb", "asm", "s", "proto", "tf", "tfvars", "hcl", "svg", "patch",
+  "diff", "tex", "bib", "csv", "cmake", "dockerfile", "makefile", "rake", "gemfile",
+]);
+
+/** Extensions that are always binary even if the sniff is inconclusive. */
+const BINARY_EXTENSIONS = new Set([
+  "zip", "gz", "tar", "tgz", "rar", "7z", "bz2", "xz", "pdf", "doc", "docx",
+  "xls", "xlsx", "ppt", "pptx", "png", "jpg", "jpeg", "gif", "bmp", "webp",
+  "ico", "tiff", "mp3", "wav", "ogg", "flac", "mp4", "mkv", "mov", "avi", "webm",
+  "exe", "dll", "so", "dylib", "bin", "dat", "db", "sqlite", "class", "jar",
+  "woff", "woff2", "ttf", "otf", "eot", "psd", "ai", "sketch",
+]);
+
+const MAX_SNIFF_BYTES = 8192;
+
+/** Lowercased extension (or a bare well-known filename like `dockerfile`). */
+function extensionOf(name?: string): string {
+  if (!name) return "";
+  const base = name.toLowerCase().replace(/^.*[\\/]/, "");
+  if (base === "dockerfile" || base === "makefile" || base === "gemfile" || base === "rakefile") return base;
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot + 1) : "";
+}
+
+/**
+ * Content sniff: NUL byte or a high proportion of control characters marks a
+ * buffer as binary. UTF-8 multibyte bytes (>= 0x80) are allowed, so
+ * non-English text is not misclassified.
+ */
+function sniff(buf: Buffer): "text" | "binary" {
+  const n = Math.min(buf.length, MAX_SNIFF_BYTES);
+  let control = 0;
+  for (let i = 0; i < n; i++) {
+    const b = buf[i]!;
+    if (b === 0) return "binary";
+    // Allow TAB(9), LF(10), CR(13), FF(12), and everything from 0x20 up.
+    if ((b < 9 || (b > 13 && b < 32)) && b !== 27 /* ESC, common in logs */) control++;
+  }
+  return control / n > 0.1 ? "binary" : "text";
+}
+
+/**
+ * Decide whether a downloaded document is text we can inline. Combines MIME and
+ * extension hints with a content sniff; the sniff is authoritative for NUL
+ * bytes so a `.txt` full of binary can't slip through.
+ */
+export function looksLikeText(buf: Buffer, mimeType?: string, fileName?: string): boolean {
+  if (buf.length === 0) return true; // empty file — harmless to inline as ""
+  const mime = (mimeType ?? "").toLowerCase();
+  const ext = extensionOf(fileName);
+
+  const hintedText =
+    TEXT_MIME_PREFIXES.some((p) => mime.startsWith(p)) || TEXT_MIME_EXACT.has(mime) || TEXT_EXTENSIONS.has(ext);
+  const hintedBinary =
+    mime.startsWith("image/") ||
+    mime.startsWith("audio/") ||
+    mime.startsWith("video/") ||
+    mime.startsWith("font/") ||
+    BINARY_EXTENSIONS.has(ext);
+
+  const content = sniff(buf);
+  if (content === "binary") return false; // NUL / control-heavy → never text
+  if (hintedText) return true;
+  if (hintedBinary) return false;
+  // Unknown type (e.g. application/octet-stream with no extension): trust sniff.
+  return content === "text";
+}
+
+/** Decode a text buffer as UTF-8 / UTF-16, stripping a leading BOM. */
+export function decodeText(buf: Buffer): string {
+  if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+    return buf.subarray(3).toString("utf8");
+  }
+  if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+    return buf.subarray(2).toString("utf16le");
+  }
+  if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+    // UTF-16 BE — swap to LE for Node's decoder.
+    return buf.subarray(2).swap16().toString("utf16le");
+  }
+  return buf.toString("utf8");
+}
+
+/** A fenced block that won't collide with backticks already in the content. */
+function pickFence(content: string): string {
+  let fence = "```";
+  while (content.includes(fence)) fence += "`";
+  return fence;
+}
+
+/** Format a human-readable byte count. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB"];
+  let v = bytes / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(v < 10 ? 1 : 0)} ${units[i]}`;
+}
+
+/**
+ * Build the prompt text for a text document. With a caption the file is framed
+ * as an attachment to act on; without one it's treated as the user's message
+ * itself (the "long message became a .txt" case).
+ */
+export function formatTextFilePrompt(name: string, content: string, caption: string, truncated: boolean): string {
+  const fence = pickFence(content);
+  const block = `${fence}\n${content}\n${fence}`;
+  const note = truncated ? "\n\n(Note: the file was long and has been truncated above.)" : "";
+  const cap = caption.trim();
+  if (cap) {
+    return `${cap}\n\nAttached file "${name}":\n${block}${note}`;
+  }
+  return `The user's message was sent as a file "${name}" (Telegram turns long messages into files). Its contents:\n${block}${note}`;
+}
+
+/** Build the prompt text for a binary document we can't inline. */
+export function formatBinaryFilePrompt(
+  name: string,
+  mimeType: string | undefined,
+  size: number,
+  caption: string,
+  savedPath: string | undefined,
+): string {
+  const meta = `name "${name}", type ${mimeType || "unknown"}, ${formatBytes(size)}`;
+  const loc = savedPath
+    ? ` It has been saved to: ${savedPath} — open it with your file tools if that helps.`
+    : "";
+  const cap = caption.trim();
+  const head = cap ? `${cap}\n\n` : "";
+  return `${head}The user sent a binary file (${meta}) whose contents can't be shown as text.${loc}`;
+}

package/src/bot/handlers/accounts.ts

@@ -0,0 +1,220 @@
+/**
+ * /accounts — manage several Grok sign-ins and switch between them.
+ *
+ * Grok has one active sign-in (`~/.grok/auth.json`); this menu snapshots the
+ * current login as a named account, imports a login already on the machine, and
+ * swaps the active identity in one tap (copies the saved snapshot back and
+ * restarts the agent so sessions re-bind). Switching is serialised with the
+ * shared agent and refused while a prompt is in flight.
+ */
+import { type Bot, type Context, InlineKeyboard } from "grammy";
+import { AuthService } from "../../app/auth-service.js";
+import type { StoredAccount } from "../../app/accounts.js";
+import { UNSUPPORTED_LOGIN_HELP } from "../../app/grok-credentials.js";
+import { createLogger } from "../../logger.js";
+import type { BotDeps } from "../deps.js";
+
+const log = createLogger("accounts");
+
+function accountLine(a: StoredAccount, active: boolean): string {
+  const mark = active ? "\u2705 " : "\u{1F464} ";
+  return `${mark}${a.label}`;
+}
+
+async function view(deps: BotDeps, note?: string): Promise<{ text: string; keyboard: InlineKeyboard }> {
+  const list = deps.accounts.list();
+  const acct = await deps.usage.account().catch(() => undefined);
+  const active = deps.accounts.activeAccountId();
+  const loggedIn = await deps.usage.isLoggedIn().catch(() => false);
+
+  const lines = ["\u{1F465} Grok accounts", ""];
+  if (loggedIn && acct?.email && !active) {
+    lines.push(`\u{1F7E2} Signed in as ${acct.email}`);
+    lines.push("  \u2514 Not saved yet — tap \u201C\u{1F4BE} Save current login\u201D to keep it.", "");
+  } else if (!loggedIn) {
+    lines.push("\u{1F534} Not signed in — sign in via /reauth.", "");
+  }
+  if (list.length === 0) {
+    lines.push("No saved accounts yet.", "", "Save the current login below, or sign in via /reauth.");
+  } else {
+    for (const a of list) lines.push(accountLine(a, a.id === active));
+  }
+  const rotate = deps.accounts.autoRotateEnabled();
+  lines.push(
+    "",
+    `\u{1F501} Auto-rotate on errors: ${rotate ? "ON" : "OFF"}`,
+    rotate ? "  \u2514 If a turn gives up, it cycles through the other accounts once." : "  \u2514 Turns stay on the active account.",
+  );
+  if (note) lines.push("", note);
+
+  const kb = new InlineKeyboard();
+  for (const a of list) {
+    const sw = a.id === active ? `\u2705 ${trim(a.label)} (active)` : `\u{1F504} ${trim(a.label)}`;
+    kb.text(sw, a.id === active ? "acct:noop" : `acct:switch:${a.id}`)
+      .text("\u270F\uFE0F", `acct:rename:${a.id}`)
+      .text("\u{1F5D1}", `acct:del:${a.id}`)
+      .row();
+  }
+  kb.text("\u{1F4BE} Save current login", "acct:save").text("\u270F\uFE0F Save as\u2026", "acct:saveas").row();
+  kb.text("\u{1F4E5} Import existing", "acct:import").text("\u{1F511} Sign in\u2026", "acct:login").row();
+  kb.text(`\u{1F501} Auto-rotate: ${rotate ? "ON" : "OFF"}`, "acct:rotate").row();
+  kb.text("\u2716 Close", "acct:close");
+  return { text: lines.join("\n"), keyboard: kb };
+}
+
+function trim(s: string, n = 22): string {
+  return s.length > n ? `${s.slice(0, n - 1)}\u2026` : s;
+}
+
+export async function showAccounts(ctx: Context, deps: BotDeps): Promise<void> {
+  const { text, keyboard } = await view(deps);
+  await deps.ephemeral.open(ctx);
+  await deps.ephemeral.reply(ctx, text, { reply_markup: keyboard });
+}
+
+async function rerender(ctx: Context, deps: BotDeps, note?: string): Promise<void> {
+  const { text, keyboard } = await view(deps, note);
+  await ctx.editMessageText(text, { reply_markup: keyboard }).catch(() => {});
+}
+
+function busyReason(deps: BotDeps): string | undefined {
+  if (deps.acp.hasInflightPrompt()) return "\u23F3 Grok is running a turn — try again when idle (or /cancel first).";
+  return undefined;
+}
+
+export function registerAccounts(bot: Bot, deps: BotDeps): void {
+  const auth = new AuthService(deps.cfg.grokCliPath);
+  const pending = new Map<number, { mode: "save" | "rename"; id?: string }>();
+
+  const promptName = async (ctx: Context, mode: "save" | "rename", id?: string): Promise<void> => {
+    const chatId = ctx.chat?.id;
+    if (chatId === undefined) return;
+    const ask =
+      mode === "save"
+        ? "\u270F\uFE0F Send a name for the current login (e.g. \u201CWork\u201D or \u201CPersonal\u201D)."
+        : "\u270F\uFE0F Send a new name for this account.";
+    await deps.ephemeral.reply(ctx, ask);
+    pending.set(chatId, { mode, id });
+  };
+
+  bot.on("message:text", async (ctx, next) => {
+    const chatId = ctx.chat.id;
+    const p = pending.get(chatId);
+    if (!p) return next();
+    const text = ctx.message.text;
+    if (text.startsWith("/")) return next();
+    pending.delete(chatId);
+    await ctx.deleteMessage().catch(() => {});
+    const name = text.trim().slice(0, 60);
+    let note: string;
+    try {
+      if (p.mode === "rename" && p.id) {
+        const meta = deps.accounts.rename(p.id, name);
+        note = meta ? `\u270F\uFE0F Renamed to ${meta.label}` : "That account is no longer saved.";
+      } else if (!(await deps.usage.isLoggedIn())) {
+        note = `\u274C ${UNSUPPORTED_LOGIN_HELP}`;
+      } else {
+        const saved = await deps.accounts.captureCurrent(undefined, name);
+        note = `\u{1F4BE} Saved: ${saved.label}`;
+      }
+    } catch (e) {
+      note = `\u274C ${(e as Error).message}`;
+    }
+    await deps.ephemeral.open(ctx);
+    const { text: t, keyboard } = await view(deps, note);
+    await deps.ephemeral.reply(ctx, t, { reply_markup: keyboard });
+  });
+
+  bot.command("accounts", (ctx) => showAccounts(ctx, deps));
+
+  bot.callbackQuery("acct:noop", (ctx) => ctx.answerCallbackQuery({ text: "Already active" }));
+
+  bot.callbackQuery("acct:saveas", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await promptName(ctx, "save");
+  });
+
+  bot.callbackQuery("acct:rotate", async (ctx) => {
+    const on = deps.accounts.setAutoRotate();
+    await ctx.answerCallbackQuery({ text: `Auto-rotate ${on ? "on" : "off"}` });
+    await rerender(ctx, deps, on ? "\u{1F501} Auto-rotate enabled." : "\u{1F501} Auto-rotate disabled.");
+  });
+
+  bot.callbackQuery(/^acct:rename:(.+)$/, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await promptName(ctx, "rename", ctx.match![1]!);
+  });
+
+  bot.callbackQuery("acct:close", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await deps.ephemeral.drop(ctx);
+  });
+
+  bot.callbackQuery("acct:save", async (ctx) => {
+    if (!(await deps.usage.isLoggedIn())) {
+      await ctx.answerCallbackQuery({ text: "Not signed in", show_alert: true });
+      return void rerender(ctx, deps, `\u274C ${UNSUPPORTED_LOGIN_HELP}`);
+    }
+    try {
+      const saved = await deps.accounts.captureCurrent();
+      await ctx.answerCallbackQuery({ text: `Saved ${saved.label}` });
+      await rerender(ctx, deps, `\u{1F4BE} Saved: ${saved.label}`);
+    } catch (e) {
+      await ctx.answerCallbackQuery({ text: (e as Error).message.slice(0, 190), show_alert: true });
+    }
+  });
+
+  bot.callbackQuery("acct:login", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await rerender(ctx, deps, "\u{1F511} Run /reauth to sign in, then tap \u201CSave current login\u201D.");
+  });
+
+  bot.callbackQuery("acct:import", async (ctx) => {
+    const reason = busyReason(deps);
+    if (reason) return void ctx.answerCallbackQuery({ text: reason, show_alert: true });
+    await ctx.answerCallbackQuery({ text: "Importing…" });
+    const res = await auth.importExisting();
+    if (!res.ok) return void rerender(ctx, deps, `\u274C ${res.error ?? "Import failed."}`);
+    try {
+      await deps.acp.restart();
+    } catch (e) {
+      return void rerender(ctx, deps, `\u26A0\uFE0F Imported, but re-bind failed: ${(e as Error).message}`);
+    }
+    let note = `\u2705 Imported the current login${res.label ? ` (${res.label})` : ""}.`;
+    try {
+      const saved = await deps.accounts.captureCurrent();
+      note = `\u2705 Imported & saved ${saved.label}.`;
+    } catch {
+      /* best-effort */
+    }
+    await rerender(ctx, deps, note);
+  });
+
+  bot.callbackQuery(/^acct:switch:(.+)$/, async (ctx) => {
+    const id = ctx.match![1]!;
+    const reason = busyReason(deps);
+    if (reason) return void ctx.answerCallbackQuery({ text: reason, show_alert: true });
+    await ctx.answerCallbackQuery({ text: "Switching…" });
+    try {
+      await deps.accounts.captureCurrent().catch(() => {}); // don't lose the current login
+      const meta = await deps.accounts.switchTo(id);
+      await ctx.editMessageText(`\u{1F504} Switching to ${meta.label}\u2026 restarting agent`).catch(() => {});
+      await deps.acp.restart();
+      const note = (await deps.usage.isLoggedIn())
+        ? `\u2705 Now signed in as ${meta.label}. Your next message runs on this account.`
+        : `\u26A0\uFE0F Switched to ${meta.label}, but no usable login is active. ${UNSUPPORTED_LOGIN_HELP}`;
+      await rerender(ctx, deps, note);
+    } catch (e) {
+      log.warn("account switch failed:", (e as Error).message);
+      await rerender(ctx, deps, `\u274C ${(e as Error).message}`);
+    }
+  });
+
+  bot.callbackQuery(/^acct:del:(.+)$/, async (ctx) => {
+    const id = ctx.match![1]!;
+    const meta = deps.accounts.get(id);
+    await deps.accounts.forget(id);
+    await ctx.answerCallbackQuery({ text: meta ? `Removed ${meta.label}` : "Removed" });
+    await rerender(ctx, deps);
+  });
+}

package/src/bot/handlers/auth.ts

@@ -0,0 +1,64 @@
+/**
+ * /reauth — sign in to Grok from chat. Shows Sign in (runs `grok login`,
+ * streaming any URL/code) or Import existing, then re-binds the agent. Guarded:
+ * refused while a turn is in flight.
+ */
+import type { Bot } from "grammy";
+import type { BotDeps } from "../deps.js";
+import { ReauthController } from "../reauth-controller.js";
+
+export function registerReauth(bot: Bot, deps: BotDeps): void {
+  const controller = new ReauthController(
+    deps.api,
+    deps.acp,
+    deps.cfg.grokCliPath,
+    () => deps.usage.account(),
+    () => deps.usage.isLoggedIn(),
+  );
+
+  bot.command("reauth", async (ctx) => {
+    if (controller.isBusy(ctx.chat.id)) {
+      await ctx.reply("\u{1F510} A sign-in is already in progress.");
+      return;
+    }
+    if (deps.acp.hasInflightPrompt()) {
+      await ctx.reply("\u23F3 Grok is busy running a turn — try /reauth when idle (or /cancel first).");
+      return;
+    }
+    await controller.chooseMethod(ctx.chat.id);
+  });
+
+  bot.callbackQuery("reauth:login", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Signing in…" });
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) await controller.beginLogin(chatId, messageId);
+  });
+
+  bot.callbackQuery("reauth:import", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Importing…" });
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) await controller.importExisting(chatId, messageId);
+  });
+
+  bot.callbackQuery("reauth:choose-cancel", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Cancelled" });
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) await controller.cancelChoice(chatId, messageId);
+  });
+
+  bot.callbackQuery("reauth:cancel", async (ctx) => {
+    const chatId = ctx.chat?.id;
+    const ok = chatId !== undefined && controller.cancel(chatId);
+    await ctx.answerCallbackQuery({ text: ok ? "Cancelling…" : "Nothing to cancel" });
+  });
+
+  bot.callbackQuery("reauth:retry", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Retry" });
+    const chatId = ctx.chat?.id;
+    const messageId = ctx.callbackQuery.message?.message_id;
+    if (chatId !== undefined && messageId !== undefined) await controller.retry(chatId, messageId);
+  });
+}

package/src/bot/handlers/control.ts

@@ -0,0 +1,103 @@
+/**
+ * Control commands: /start /help /status /new /cancel /btw /flush.
+ */
+import type { Bot } from "grammy";
+import { basename } from "node:path";
+import { textPrompt } from "../../app/types.js";
+import type { BotDeps } from "../deps.js";
+import { HELP_TEXT } from "../commands.js";
+import { compactKeyboard } from "../menu/keyboard.js";
+import { refreshMenu } from "../menu/refresh.js";
+import { extractReplyContext } from "../reply-context.js";
+import { openMainMenu } from "./menu.js";
+
+export function registerControl(bot: Bot, deps: BotDeps): void {
+  bot.command("start", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    const agent = deps.acp.agentInfo;
+    const lines = [
+      "\u{1F44B} Welcome! I bridge Telegram to Grok Build over ACP.",
+      agent?.name ? `Connected to ${agent.name} ${agent.version ?? ""}`.trim() : "",
+      "",
+      "Tap \u2630 Menu for everything. A live status panel appears while I work",
+      "(\u2630 Menu \u2192 Status shows it anytime). Just send a message to start.",
+    ].filter(Boolean);
+    await ctx.reply(lines.join("\n"), { reply_markup: compactKeyboard() });
+    await deps.statusPanel.refresh(ctx.chat.id);
+  });
+
+  bot.command("menu", async (ctx) => {
+    await openMainMenu(ctx, deps);
+    await deps.statusPanel.refresh(ctx.chat.id);
+  });
+
+  bot.command("help", async (ctx) => {
+    await ctx.reply(HELP_TEXT);
+  });
+
+  bot.command("status", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    const lines = [
+      "\u{1F4CA} Status",
+      `Project: ${rt.projectName ?? (basename(rt.cwd) || rt.cwd)}`,
+      `Folder: ${rt.cwd}`,
+      `Session: ${rt.sessionId ?? "(none yet)"}`,
+      `State: ${rt.isBusy ? "\u23F3 working" : "\u2705 idle"}`,
+      `Queued follow-ups: ${rt.queueLength}`,
+    ];
+    const subagents = deps.registry.subagentSummaryForChat(ctx.chat.id);
+    if (subagents) lines.push(`Subagents: ${subagents}`);
+    await ctx.reply(lines.join("\n"));
+  });
+
+  bot.command("new", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    try {
+      await deps.registry.controller(ctx.chat.id).addNew(rt.cwd, rt.projectName);
+      await refreshMenu(ctx, deps, `\u2728 New session started in ${rt.projectName ?? rt.cwd}`);
+    } catch (err) {
+      await ctx.reply(`\u274C Could not start session: ${(err as Error).message}`);
+    }
+  });
+
+  bot.command("cancel", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    const cancelled = await rt.cancel();
+    await ctx.reply(cancelled ? "\u23F9 Cancelling current turn\u2026" : "Nothing is running.");
+  });
+
+  bot.command("btw", async (ctx) => {
+    const text = (ctx.match || "").toString().trim();
+    if (!text) {
+      await ctx.reply("Usage: /btw <something for the agent to do — now if idle, otherwise next>");
+      return;
+    }
+    const rt = deps.registry.get(ctx.chat.id);
+    // Run it right away when idle; otherwise queue it to run automatically the
+    // moment the current turn finishes (can't interrupt an in-flight agent turn).
+    const outcome = await rt.submit(textPrompt(text, undefined, extractReplyContext(ctx)));
+    if (outcome === "queued") {
+      await ctx.reply(
+        `\u{1F4E5} Queued (position ${rt.queueLength}) \u2014 it'll run automatically as soon as the current task finishes.`,
+      );
+    } else {
+      await ctx.reply("\u25B6\uFE0F On it\u2026");
+    }
+  });
+
+  bot.command("flush", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    if (rt.queueLength === 0) {
+      await ctx.reply("Queue is empty.");
+      return;
+    }
+    if (rt.isBusy) {
+      await ctx.reply(`\u23F3 ${rt.queueLength} queued \u2014 they'll run automatically when the current turn ends.`);
+      return;
+    }
+    // Idle: drain the queue by submitting an empty trigger that flushes.
+    await ctx.reply("\u25B6\uFE0F Running queued follow-ups\u2026");
+    const drained = rt.drainQueueToPrompt();
+    if (drained) await rt.submit(drained);
+  });
+}