grok-telegram-bot 2.0.0

package/src/bot/handlers/message.ts

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

package/src/bot/handlers/photo.ts

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

package/src/bot/handlers/projects.ts

@@ -0,0 +1,183 @@
+/**
+ * /projects (alias /project) — browse, search, open any folder, or create.
+ *   /projects                list/pick projects (freshest first)
+ *   /projects <query>        filter projects by name
+ *   /projects <path>         open any existing folder (e.g. C:\x, /home/x, ~/x);
+ *                            errors if the path doesn't exist (never created)
+ *   /projects new <name>     create a folder under the first root + open it;
+ *                            errors if it already exists
+ * Exposes a reusable project menu used by the menu button and the task wizard.
+ */
+import { type Context, InlineKeyboard } from "grammy";
+import type { Bot } from "grammy";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import type { ProjectEntry } from "../../projects/manager.js";
+import type { BotDeps } from "../deps.js";
+import { refreshMenu } from "../menu/refresh.js";
+
+const PAGE = 10; // projects per page
+const FETCH = 300; // how many projects to load before paging
+
+/** Build the inline keyboard for one page of projects + a Prev/Next nav row. */
+function projectPage(list: ProjectEntry[], page: number, itemPrefix: string, kind: "p" | "w"): InlineKeyboard {
+  const totalPages = Math.max(1, Math.ceil(list.length / PAGE));
+  const p = Math.min(Math.max(0, page), totalPages - 1);
+  const start = p * PAGE;
+  const kb = new InlineKeyboard();
+  list.slice(start, start + PAGE).forEach((entry, i) => {
+    kb.text(`\u{1F4C1} ${entry.name}`, `${itemPrefix}${start + i}`).row();
+  });
+  if (totalPages > 1) {
+    if (p > 0) kb.text("\u25C0 Prev", `pp:${kind}:${p - 1}`);
+    kb.text(`${p + 1}/${totalPages}`, "noop");
+    if (p < totalPages - 1) kb.text("Next \u25B6", `pp:${kind}:${p + 1}`);
+  }
+  return kb;
+}
+
+/** Send a project picker. `prefix` is the callback-data prefix (e.g. "proj:"). */
+export async function sendProjectMenu(
+  ctx: Context,
+  deps: BotDeps,
+  prefix: string,
+  title: string,
+  entries?: ProjectEntry[],
+): Promise<void> {
+  const chatId = ctx.chat!.id;
+  await deps.ephemeral.open(ctx);
+  const list = sortByRecency(entries ?? deps.projects.list(FETCH), deps);
+  deps.menuCache.setProjects(chatId, list);
+  if (list.length === 0) {
+    await deps.ephemeral.reply(ctx, "No matching projects. Try `/projects new <name>` to create one.");
+    return;
+  }
+  const kind = prefix === "wiz:proj:" ? "w" : "p";
+  await deps.ephemeral.reply(ctx, title, { reply_markup: projectPage(list, 0, prefix, kind) });
+}
+
+/** Refine project order with Grok session recency: a project's effective
+ *  "last used" is the latest of its directory mtime and the newest session
+ *  opened in it, so the project you worked in most recently floats to the top. */
+function sortByRecency(entries: ProjectEntry[], deps: BotDeps): ProjectEntry[] {
+  const recencyByCwd = new Map<string, number>();
+  for (const s of deps.store.list(300)) {
+    const key = normCwd(s.cwd);
+    if (!key) continue;
+    const ms = Date.parse(s.updatedAt);
+    if (!Number.isFinite(ms)) continue;
+    const prev = recencyByCwd.get(key) ?? 0;
+    if (ms > prev) recencyByCwd.set(key, ms);
+  }
+  return entries
+    .map((p) => ({ ...p, lastUsed: Math.max(p.lastUsed, recencyByCwd.get(normCwd(p.path)) ?? 0) }))
+    .sort((a, b) => b.lastUsed - a.lastUsed || a.name.localeCompare(b.name));
+}
+
+/** Normalise a path for cwd ↔ project matching (case/separator/trailing slash). */
+function normCwd(p: string): string {
+  return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+
+export async function showProjects(ctx: Context, deps: BotDeps, query?: string): Promise<void> {
+  const arg = (query ?? "").trim();
+
+  // Create: /projects new <name>
+  const create = /^new\s+(.+)$/i.exec(arg);
+  if (create) {
+    try {
+      const entry = deps.projects.create(create[1]!);
+      await deps.registry.controller(ctx.chat!.id).addNew(entry.path, entry.name);
+      await refreshMenu(ctx, deps, `\u2705 Created and opened ${entry.name}\n${entry.path} \u2014 send a message.`);
+    } catch (e) {
+      await deps.ephemeral.open(ctx);
+      await deps.ephemeral.reply(ctx, `\u274C Could not create project: ${(e as Error).message}`);
+    }
+    return;
+  }
+
+  // Switch to an explicit path: /projects C:\path  ·  /projects /home/x  ·  ~/x
+  if (arg && looksLikePath(arg)) {
+    await openProjectPath(ctx, deps, arg);
+    return;
+  }
+
+  // Search: /projects <query>
+  if (arg) {
+    const found = deps.projects.search(arg, FETCH);
+    await sendProjectMenu(ctx, deps, "proj:", `Projects matching "${arg}":`, found);
+    return;
+  }
+
+  await sendProjectMenu(ctx, deps, "proj:", "Choose a project:");
+}
+
+/** True when the argument looks like a filesystem path rather than a name. */
+function looksLikePath(s: string): boolean {
+  return /[\\/]/.test(s) || /^[a-zA-Z]:/.test(s) || s.startsWith("~");
+}
+
+/** Open a session in an explicit folder (any path, even outside PROJECT_ROOTS).
+ *  The folder must already exist — we never create it here. */
+async function openProjectPath(ctx: Context, deps: BotDeps, raw: string): Promise<void> {
+  const dir = resolvePath(raw);
+  if (!deps.projects.isDirectory(dir)) {
+    await deps.ephemeral.open(ctx);
+    await deps.ephemeral.reply(
+      ctx,
+      `\u274C Path not found: ${dir}\nI won't create it \u2014 use \`/projects new <name>\` to make a new project.`,
+    );
+    return;
+  }
+  await deps.ephemeral.open(ctx);
+  const name = basename(dir) || dir;
+  try {
+    await deps.registry.controller(ctx.chat!.id).addNew(dir, name);
+    await refreshMenu(ctx, deps, `\u{1F4C1} Now working in ${name}\n${dir} \u2014 send a message.`);
+  } catch (e) {
+    await deps.ephemeral.reply(ctx, `\u274C Could not open ${dir}: ${(e as Error).message}`);
+  }
+}
+
+/** Resolve `~` and normalise a user-supplied path (e.g. `c://lucru` → `C:\lucru`). */
+function resolvePath(p: string): string {
+  let s = p.trim();
+  if (s === "~") s = homedir();
+  else if (s.startsWith("~/") || s.startsWith("~\\")) s = join(homedir(), s.slice(2));
+  return resolve(s);
+}
+
+export function registerProjects(bot: Bot, deps: BotDeps): void {
+  bot.command(["projects", "project"], (ctx) => showProjects(ctx, deps, ctx.match?.toString()));
+
+  // Page-indicator buttons do nothing but acknowledge the tap.
+  bot.callbackQuery("noop", (ctx) => ctx.answerCallbackQuery());
+
+  // Project picker pagination: pp:<p|w>:<page> edits the keyboard in place.
+  bot.callbackQuery(/^pp:(p|w):(\d+)$/, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const list = deps.menuCache.getProjects(ctx.chat!.id);
+    if (!list) return;
+    const kind = ctx.match![1] as "p" | "w";
+    const itemPrefix = kind === "w" ? "wiz:proj:" : "proj:";
+    const kb = projectPage(list, Number(ctx.match![2]), itemPrefix, kind);
+    await ctx.editMessageReplyMarkup({ reply_markup: kb }).catch(() => {});
+  });
+
+  bot.callbackQuery(/^proj:(\d+)$/, async (ctx) => {
+    const index = Number(ctx.match![1]);
+    const entry = deps.menuCache.getProject(ctx.chat!.id, index);
+    if (!entry) {
+      await ctx.answerCallbackQuery({ text: "Selection expired, run /projects again." });
+      return;
+    }
+    await ctx.answerCallbackQuery();
+    await deps.ephemeral.clear(ctx.chat!.id); // remove the project picker
+    try {
+      await deps.registry.controller(ctx.chat!.id).addNew(entry.path, entry.name);
+      await refreshMenu(ctx, deps, `\u{1F4C1} Now working in ${entry.name} \u2014 send a message.`);
+    } catch (err) {
+      await ctx.reply(`\u274C Could not open ${entry.name}: ${(err as Error).message}`);
+    }
+  });
+}

package/src/bot/handlers/running.ts

@@ -0,0 +1,181 @@
+/**
+ * /running — the sessions this chat controls. Tap one to switch to it; on
+ * switch you see a header + the target's unread messages (what happened while
+ * you were away) or its recent history the first time.
+ */
+import { type Bot, type Context, InlineKeyboard } from "grammy";
+import type { RunningSession, SwitchResult } from "../chat-controller.js";
+import type { BotDeps } from "../deps.js";
+import type { HistoryEntry } from "../../sessions/types.js";
+import { jsonlMtimeMs, readFirstPrompt } from "../../sessions/history.js";
+import { progressBar } from "../../render/progress.js";
+import { refreshMenu } from "../menu/refresh.js";
+import { sendMarkdownDoc } from "../telegram-io.js";
+
+const UUID = "([0-9a-fA-F-]{36})";
+const ROLE_ICON: Record<string, string> = {
+  user: "\u{1F464}",
+  assistant: "\u{1F916}",
+  tool: "\u{1F527}",
+  system: "\u2139\uFE0F",
+};
+const ENTRY_MAX = 700;
+/** Max session cards to send for one /running (avoids flooding the chat). */
+const CARD_LIMIT = 12;
+
+function trunc(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n - 1) + "\u2026" : s;
+}
+
+/** Compact "time ago" label from an elapsed-milliseconds value. */
+function timeAgo(ms: number): string {
+  const s = Math.round(ms / 1000);
+  if (s < 45) return "just now";
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  if (h < 24) return `${h}h ago`;
+  return `${Math.round(h / 24)}d ago`;
+}
+
+/** Reduce a stored first prompt to a clean one-liner: drop the leading reasoning
+ *  directive and any fork-priming preamble, then collapse whitespace. */
+function cleanPrompt(raw: string): string {
+  let t = raw.trim().replace(/^\([^)]*\)\s*/, "");
+  const marker = "User's new message:";
+  const i = t.lastIndexOf(marker);
+  if (i !== -1) t = t.slice(i + marker.length);
+  return t.replace(/\s+/g, " ").trim();
+}
+
+/** Build a rich card (plain text, no MarkdownV2) + buttons for one controlled
+ *  session: Switch / History / Close. */
+function buildRunningCard(s: RunningSession, deps: BotDeps, now: number): { text: string; kb: InlineKeyboard } {
+  const dot = s.foreground ? "\u25B6\uFE0F" : s.busy ? "\u{1F7E0}" : "\u26AA";
+  const state = s.foreground ? "foreground" : s.busy ? "working" : "idle";
+
+  let when = "new";
+  let prompt = "";
+  if (s.sessionId) {
+    const path = deps.store.jsonlPath(s.sessionId);
+    const mtime = jsonlMtimeMs(path);
+    if (mtime) when = timeAgo(now - mtime);
+    prompt = cleanPrompt(readFirstPrompt(path));
+  }
+
+  const meta = [when, state];
+  if (s.busy) meta.push("\u23F3");
+  if (s.unread > 0) meta.push(`${s.unread} \u{1F4EC} unread`);
+
+  const lines = [
+    `${dot} ${s.projectName}`,
+    prompt ? `\u{1F4AC} \u201C${trunc(prompt, 120)}\u201D` : "\u{1F4AC} (no messages yet)",
+    `\u{1F552} ${meta.join(" \u00B7 ")}`,
+  ];
+  if (s.progress !== undefined) lines.push(`\u{1F4C8} ${progressBar(s.progress)}`);
+  if (s.sessionId) lines.push(`\u{1F194} ${s.sessionId.slice(0, 8)}`);
+
+  const kb = new InlineKeyboard();
+  if (!s.sessionId) {
+    kb.text("\u23F3 starting\u2026", "run:noop");
+    return { text: lines.join("\n"), kb };
+  }
+  if (s.foreground) kb.text("\u25B6\uFE0F Current", "run:noop");
+  else kb.text("\u{1F500} Switch", `run:switch:${s.sessionId}`);
+  kb.text("\u{1F4DC} History", `hist:${s.sessionId}`).text("\u2716 Close", `run:close:${s.sessionId}`);
+  return { text: lines.join("\n"), kb };
+}
+
+export async function showRunning(ctx: Context, deps: BotDeps): Promise<void> {
+  await deps.ephemeral.open(ctx);
+  const list = dedupeBySession(deps.registry.controller(ctx.chat!.id).list());
+  if (list.length === 0) {
+    await deps.ephemeral.reply(ctx, "No sessions controlled yet. Use \u{1F4C1} Project or /new to start one.");
+    return;
+  }
+  const now = Date.now();
+  const shown = list.slice(0, CARD_LIMIT);
+  await deps.ephemeral.reply(ctx, `\u{1F9ED} Sessions controlled by this chat (${list.length}) \u2014 tap \u{1F500} Switch on a card:`);
+  for (const s of shown) {
+    const { text, kb } = buildRunningCard(s, deps, now);
+    await deps.ephemeral.reply(ctx, text, { reply_markup: kb });
+  }
+  if (list.length > shown.length) {
+    await deps.ephemeral.reply(ctx, `\u2026and ${list.length - shown.length} more.`);
+  }
+}
+
+/** Collapse any cards that share a session id (defensive — the controller
+ *  already prunes duplicate runtimes, but never show the same session twice). */
+function dedupeBySession(list: RunningSession[]): RunningSession[] {
+  const seen = new Set<string>();
+  return list.filter((s) => {
+    if (!s.sessionId) return true;
+    if (seen.has(s.sessionId)) return false;
+    seen.add(s.sessionId);
+    return true;
+  });
+}
+
+/** Switch the chat to a session and show its summary + unread. */
+export async function switchAndShow(ctx: Context, deps: BotDeps, sessionId: string): Promise<void> {
+  const res = await deps.registry.controller(ctx.chat!.id).switchTo(sessionId);
+  if (!res) {
+    await ctx.reply("Session not found (it may have been closed).");
+    return;
+  }
+  await deliverSwitch(ctx, deps, res);
+}
+
+export function registerRunning(bot: Bot, deps: BotDeps): void {
+  bot.command("running", (ctx) => showRunning(ctx, deps));
+
+  bot.callbackQuery("run:noop", (ctx) => ctx.answerCallbackQuery({ text: "Already in foreground" }));
+
+  bot.callbackQuery(new RegExp(`^run:switch:${UUID}$`), async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await deps.ephemeral.clear(ctx.chat!.id); // remove the /running cards; 🔀 Switched stays
+    await switchAndShow(ctx, deps, ctx.match![1]!);
+  });
+
+  bot.callbackQuery(new RegExp(`^run:close:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    await deps.registry.controller(ctx.chat!.id).close(id);
+    await ctx.answerCallbackQuery({ text: "Closed" });
+    await ctx.deleteMessage().catch(() => {}); // remove just this card
+  });
+}
+
+async function deliverSwitch(ctx: Context, deps: BotDeps, res: SwitchResult): Promise<void> {
+  const proj = res.projectName ?? "session";
+  const sid = res.sessionId ? res.sessionId.slice(0, 8) : "?";
+  if (res.alreadyForeground) {
+    await ctx.reply(`You're already on ${proj} (${sid}).`);
+    return;
+  }
+  const working = res.busy ? " \u00B7 \u23F3 still working (live updates follow)" : "";
+  await refreshMenu(ctx, deps, `\u{1F500} Switched to ${proj} (${sid})${working}`);
+
+  if (res.unread.length === 0) {
+    if (!res.busy) await ctx.reply(res.firstView ? "No earlier messages here." : "\u2705 Nothing new while you were away.");
+    return;
+  }
+  const header = res.firstView
+    ? `\u{1F4DC} **Recent history** \u2014 ${proj}`
+    : `\u{1F4EC} **${res.unread.length} message(s) while away** \u2014 ${proj}`;
+  const body = res.unread.map(fmtEntry).join("\n\n");
+  await sendMarkdownDoc(deps.api, ctx.chat!.id, `${header}\n\n${body}\n\n${res.rt.tags}`);
+
+  // Replay how the session's last turn ended (Done + file summary) — this isn't
+  // in the .jsonl, so it's the footer you'd have seen had you been watching.
+  if (!res.busy && res.rt.lastTurnSummary) {
+    await ctx.reply(res.rt.lastTurnSummary);
+  }
+}
+
+function fmtEntry(e: HistoryEntry): string {
+  const icon = ROLE_ICON[e.role] ?? "\u2022";
+  if (e.role === "tool") return `${icon} ${e.tool ? `\`${e.tool}\`` : "tool"}`;
+  const text = e.text.length > ENTRY_MAX ? e.text.slice(0, ENTRY_MAX) + " \u2026" : e.text;
+  return `${icon} ${text}`;
+}

package/src/bot/handlers/session-card.ts

@@ -0,0 +1,81 @@
+/**
+ * Builds a rich, readable "card" for a single Grok session: a plain-text body
+ * (no MarkdownV2 so Windows paths and titles never need escaping) plus an
+ * inline keyboard with Connect / History / Watch actions.
+ *
+ * Callback data is unchanged (`sess:` / `hist:` / `watch:` + UUID) so the
+ * existing handlers in sessions.ts keep working.
+ */
+import { InlineKeyboard } from "grammy";
+import { basename } from "node:path";
+import { progressBar } from "../../render/progress.js";
+import type { SessionMeta } from "../../sessions/types.js";
+
+export interface SessionCardExtras {
+  /** Context-usage %, when the session is loaded in the current ACP process. */
+  contextPct?: number;
+  /**
+   * PID of the bot's own `grok acp` process. A session locked by this PID
+   * powers the bot itself, so its card omits the Kill button (killing it would
+   * take the bot down). Other live sessions get a 🛑 Kill button.
+   */
+  selfPid?: number;
+  /** Latest task-completion % (0–100) for this session, if this chat runs it. */
+  progress?: number;
+}
+
+export interface SessionCard {
+  text: string;
+  keyboard: InlineKeyboard;
+}
+
+/** Build the card body + buttons for one session. */
+export function buildSessionCard(m: SessionMeta, extra: SessionCardExtras = {}): SessionCard {
+  const dot = m.active ? "\u{1F7E2}" : "\u26AA";
+  const state = m.active ? `running${m.lockPid ? ` \u00B7 pid ${m.lockPid}` : ""}` : "idle";
+  const proj = m.cwd ? basename(m.cwd) : "(no project)";
+
+  const lines = [`${dot} ${m.title}`, `\u{1F4C1} ${proj}`];
+  if (m.cwd) lines.push(`   ${m.cwd}`);
+  lines.push(`\u{1F552} updated ${relTime(m.updatedAt)} \u00B7 created ${relTime(m.createdAt)}`);
+  const ctx = typeof extra.contextPct === "number" ? ` \u00B7 \u{1F9E0} ctx ${Math.round(extra.contextPct)}%` : "";
+  lines.push(`\u{1F4CA} ${state} \u00B7 \u{1F4DC} history ${humanSize(m.historyBytes)}${ctx}`);
+  if (typeof extra.progress === "number") lines.push(`\u{1F4C8} ${progressBar(extra.progress)}`);
+  lines.push(`\u{1F194} ${m.sessionId.slice(0, 8)}`);
+
+  const connect = m.active ? "\u{1F374} Continue (fork)" : "\u{1F517} Resume";
+  const keyboard = new InlineKeyboard()
+    .text(connect, `sess:${m.sessionId}`)
+    .text("\u{1F4DC} History", `hist:${m.sessionId}`)
+    .text("\u{1F4E1} Watch", `watch:${m.sessionId}`);
+
+  // A live session running in another process can be terminated by PID. The
+  // bot's own agent (selfPid) is never offered — killing it would stop the bot.
+  if (m.active && typeof m.lockPid === "number" && m.lockPid !== extra.selfPid) {
+    keyboard.row().text(`\u{1F6D1} Kill \u00B7 pid ${m.lockPid}`, `killsess:${m.sessionId}`);
+  }
+
+  return { text: lines.join("\n"), keyboard };
+}
+
+/** Compact relative time, e.g. "42s ago", "5m ago", "3h ago", "2d ago". */
+export function relTime(iso: string): string {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return "unknown";
+  const s = Math.max(0, Math.round((Date.now() - t) / 1000));
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  return `${d}d ago`;
+}
+
+/** Human-readable byte size, e.g. "812 B", "42.3 KB", "1.2 MB". */
+export function humanSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}