grok-telegram-bot 2.0.0

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

@@ -0,0 +1,95 @@
+/**
+ * Per-session kill — terminate the OS process holding a live session's `.lock`
+ * straight from its card in /sessions or /active.
+ *
+ * Flow (callback data, UUID-keyed so it survives bot restarts):
+ *   killsess:<id>          a tap on the card's 🛑 Kill button → ask to confirm
+ *   killsess:do:<id>       confirmed → kill the lockPid, report the outcome
+ *   killsess:cancel:<id>   abort → restore the card's normal buttons
+ *
+ * Guards: the bot's own agent (acp.pid) is never killable here (its card never
+ * shows the button, and the handlers re-check), and state is re-read from disk
+ * at every step so a session that already stopped can't be "killed" twice.
+ */
+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";
+import { buildSessionCard } from "./session-card.js";
+
+const UUID = "([0-9a-fA-F-]{36})";
+
+/** Rebuild the standard card keyboard for the freshest on-disk session state. */
+function cardKeyboard(deps: BotDeps, meta: SessionMeta): InlineKeyboard {
+  const contextPct = deps.acp.metadataFor(meta.sessionId)?.contextUsagePercentage;
+  return buildSessionCard(meta, { contextPct, selfPid: deps.acp.pid }).keyboard;
+}
+
+/** Re-read the session and decide whether its PID may be killed right now. */
+function killable(
+  deps: BotDeps,
+  id: string,
+): { ok: true; meta: SessionMeta; pid: number } | { ok: false; meta?: SessionMeta; reason: string } {
+  const meta = deps.store.get(id);
+  if (!meta) return { ok: false, reason: "Session not found." };
+  if (!meta.active || typeof meta.lockPid !== "number") {
+    return { ok: false, meta, reason: "Session is no longer running." };
+  }
+  if (meta.lockPid === deps.acp.pid) {
+    return { ok: false, meta, reason: "That's the bot's own agent — can't kill it." };
+  }
+  return { ok: true, meta, pid: meta.lockPid };
+}
+
+export function registerSessionKill(bot: Bot, deps: BotDeps): void {
+  // Step 1 — ask to confirm. Swap the card's buttons for a Kill/Cancel row.
+  bot.callbackQuery(new RegExp(`^killsess:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    const check = killable(deps, id);
+    if (!check.ok) {
+      await ctx.answerCallbackQuery({ text: check.reason });
+      // The button is stale (session stopped); refresh it to the normal card.
+      if (check.meta) await ctx.editMessageReplyMarkup({ reply_markup: cardKeyboard(deps, check.meta) }).catch(() => {});
+      return;
+    }
+    await ctx.answerCallbackQuery();
+    const kb = new InlineKeyboard()
+      .text(`\u{1F6D1} Kill pid ${check.pid}`, `killsess:do:${id}`)
+      .text("\u21A9 Cancel", `killsess:cancel:${id}`);
+    await ctx.editMessageReplyMarkup({ reply_markup: kb }).catch(() => {});
+  });
+
+  // Step 2a — confirmed. Re-validate (it may have died meanwhile), then kill.
+  bot.callbackQuery(new RegExp(`^killsess:do:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    const check = killable(deps, id);
+    if (!check.ok) {
+      await ctx.answerCallbackQuery({ text: check.reason });
+      await appendStatus(ctx, check.reason);
+      return;
+    }
+    const title = check.meta.title;
+    const ok = killPid(check.pid);
+    await ctx.answerCallbackQuery({ text: ok ? "Killed" : "Kill failed" });
+    const note = ok
+      ? `\u{1F6D1} Killed ${title} (pid ${check.pid}).`
+      : `\u26A0\uFE0F Could not kill pid ${check.pid} (already gone, or not permitted).`;
+    await appendStatus(ctx, note);
+  });
+
+  // Step 2b — cancelled. Put the card's normal buttons back.
+  bot.callbackQuery(new RegExp(`^killsess:cancel:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    await ctx.answerCallbackQuery({ text: "Cancelled" });
+    const meta = deps.store.get(id);
+    if (meta) await ctx.editMessageReplyMarkup({ reply_markup: cardKeyboard(deps, meta) }).catch(() => {});
+    else await ctx.editMessageReplyMarkup().catch(() => {});
+  });
+}
+
+/** Append a one-line status under the card and drop its keyboard. */
+async function appendStatus(ctx: Context, note: string): Promise<void> {
+  const body = ctx.callbackQuery?.message?.text;
+  const text = body ? `${body}\n\n${note}` : note;
+  await ctx.editMessageText(text).catch(() => {});
+}

package/src/bot/handlers/sessions.ts

@@ -0,0 +1,148 @@
+/**
+ * /sessions — list recent Grok sessions and connect to one.
+ * /active   — list sessions currently running on this PC.
+ * /unwatch  — stop following a live session.
+ *
+ * Each session is shown as its own card (status, project + path, times, history
+ * size, context %), with Connect (resume, or fork if the session is locked/live),
+ * 📜 History (static view), and 📡 Watch (live read-only follow) buttons.
+ */
+import { type Bot, type Context, InlineKeyboard } from "grammy";
+import { basename } from "node:path";
+import type { BotDeps } from "../deps.js";
+import { readHistory } from "../../sessions/history.js";
+import type { SessionMeta } from "../../sessions/types.js";
+import { refreshMenu } from "../menu/refresh.js";
+import { showHistory } from "./history.js";
+import { buildSessionCard } from "./session-card.js";
+
+/** How many session cards per page. */
+const PAGE_SIZE = 10;
+const UUID = "([0-9a-fA-F-]{36})";
+
+export async function showSessions(ctx: Context, deps: BotDeps, query?: string): Promise<void> {
+  const q = (query ?? "").trim().toLowerCase();
+  let metas = deps.store.list(q ? 400 : 200);
+  if (q) {
+    metas = metas.filter((m) => `${m.title} ${m.cwd} ${m.sessionId}`.toLowerCase().includes(q));
+  }
+  if (metas.length === 0) {
+    await deps.ephemeral.open(ctx);
+    await deps.ephemeral.reply(ctx, q ? `No sessions match "${q}".` : "No saved sessions found in ~/.grok/sessions/cli.");
+    return;
+  }
+  deps.menuCache.setSessions(ctx.chat!.id, metas, q ? `Sessions matching "${q}"` : "Recent sessions");
+  await renderSessionPage(ctx, deps, 0);
+}
+
+/** Render one page of session cards: header + up to PAGE_SIZE cards + nav footer. */
+async function renderSessionPage(ctx: Context, deps: BotDeps, page: number): Promise<void> {
+  await deps.ephemeral.open(ctx);
+  const cached = deps.menuCache.getSessions(ctx.chat!.id);
+  if (!cached) return;
+  const { metas, heading } = cached;
+  const totalPages = Math.max(1, Math.ceil(metas.length / PAGE_SIZE));
+  const p = Math.min(Math.max(0, page), totalPages - 1);
+  const slice = metas.slice(p * PAGE_SIZE, p * PAGE_SIZE + PAGE_SIZE);
+
+  const live = slice.filter((m) => m.active).length;
+  const liveStr = live ? ` \u00B7 \u{1F7E2} ${live} live` : "";
+  const pageStr = totalPages > 1 ? ` \u00B7 page ${p + 1}/${totalPages}` : "";
+  await deps.ephemeral.reply(ctx, `\u{1F5C2} ${heading} \u2014 ${metas.length} total${liveStr}${pageStr}`);
+
+  for (const m of slice) {
+    const contextPct = deps.acp.metadataFor(m.sessionId)?.contextUsagePercentage;
+    const progress = deps.registry.controller(ctx.chat!.id).progressFor(m.sessionId);
+    const { text, keyboard } = buildSessionCard(m, { contextPct, selfPid: deps.acp.pid, progress });
+    await deps.ephemeral.reply(ctx, text, { reply_markup: keyboard });
+  }
+
+  if (totalPages > 1) {
+    const nav = new InlineKeyboard();
+    if (p > 0) nav.text("\u25C0 Prev", `sp:${p - 1}`);
+    nav.text(`${p + 1}/${totalPages}`, "noop");
+    if (p < totalPages - 1) nav.text("Next \u25B6", `sp:${p + 1}`);
+    await deps.ephemeral.reply(ctx, `\u{1F4C4} Page ${p + 1}/${totalPages}`, { reply_markup: nav });
+  }
+}
+
+export function registerSessions(bot: Bot, deps: BotDeps): void {
+  bot.command("sessions", (ctx) => showSessions(ctx, deps, ctx.match?.toString()));
+
+  bot.command("active", async (ctx) => {
+    const metas = deps.store.listActive();
+    if (metas.length === 0) {
+      await deps.ephemeral.open(ctx);
+      await deps.ephemeral.reply(ctx, "No sessions are currently running on this PC.");
+      return;
+    }
+    deps.menuCache.setSessions(ctx.chat!.id, metas, "Live sessions running now");
+    await renderSessionPage(ctx, deps, 0);
+  });
+
+  bot.callbackQuery(/^sp:(\d+)$/, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await renderSessionPage(ctx, deps, Number(ctx.match![1]));
+  });
+
+  bot.command("unwatch", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    await ctx.reply(rt.stopWatch() ? "\u{1F6D1} Stopped watching." : "Not watching anything.");
+  });
+
+  bot.callbackQuery(new RegExp(`^sess:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    const meta = deps.store.get(id);
+    if (!meta) {
+      await ctx.answerCallbackQuery({ text: "Session not found." });
+      return;
+    }
+    await ctx.answerCallbackQuery();
+    await deps.ephemeral.clear(ctx.chat!.id); // remove the session cards
+    const fgCwd = deps.registry.get(ctx.chat!.id).cwd;
+    const cwd = meta.cwd || fgCwd;
+    const projectName = basename(meta.cwd || fgCwd) || "session";
+    const prior = readHistory(deps.store.jsonlPath(id), 24);
+    try {
+      const { result, alreadyControlled } = await deps.registry
+        .controller(ctx.chat!.id)
+        .addAttach(id, cwd, projectName, prior);
+      await ctx.reply(alreadyControlled ? `\u{1F500} Switched to ${meta.title}` : connectMessage(result, meta));
+      await refreshMenu(ctx, deps, `\u{1F4C2} ${meta.title}`);
+      await showHistory(deps, ctx.chat!.id, id, meta);
+    } catch (err) {
+      await ctx.reply(`\u274C Could not connect: ${(err as Error).message}`);
+    }
+  });
+
+  bot.callbackQuery(new RegExp(`^hist:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    await ctx.answerCallbackQuery();
+    const meta = deps.store.get(id);
+    await showHistory(deps, ctx.chat!.id, id, meta);
+  });
+
+  bot.callbackQuery(new RegExp(`^watch:${UUID}$`), async (ctx) => {
+    const id = ctx.match![1]!;
+    await ctx.answerCallbackQuery();
+    const meta = deps.store.get(id);
+    const rt = deps.registry.get(ctx.chat!.id);
+    rt.startWatch(deps.store.jsonlPath(id));
+    await ctx.reply(
+      `\u{1F4E1} Watching live: ${meta?.title ?? id.slice(0, 8)}\nNew activity streams here. Send /unwatch to stop.`,
+    );
+  });
+}
+
+function connectMessage(result: "resumed" | "forked", meta: SessionMeta): string {
+  if (result === "resumed") {
+    return `\u2705 Resumed: ${meta.title}\n${meta.cwd}\n\nSend a message to continue.`;
+  }
+  return [
+    `\u26A0\uFE0F ${meta.title} is live on your PC right now, so Grok keeps it locked.`,
+    `I opened a linked continuation here in the same project with its recent context.`,
+    `${meta.cwd}`,
+    ``,
+    `Send a message to keep going \u2014 or tap \u{1F4E1} to watch the original live.`,
+  ].join("\n");
+}

package/src/bot/handlers/system.ts

@@ -0,0 +1,51 @@
+/**
+ * System commands: /queue /clearqueue /model /restart.
+ */
+import type { Bot } from "grammy";
+import type { BotDeps } from "../deps.js";
+
+export function registerSystem(bot: Bot, deps: BotDeps): void {
+  bot.command("queue", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    if (rt.queueLength === 0) {
+      await ctx.reply("Queue is empty. Send a message while I'm busy, or use /btw <text>.");
+      return;
+    }
+    await ctx.reply(`\u{1F4E5} ${rt.queueLength} follow-up(s) queued. They run automatically after the current turn, or use /flush.`);
+  });
+
+  bot.command("clearqueue", async (ctx) => {
+    const rt = deps.registry.get(ctx.chat.id);
+    const n = rt.clearQueue();
+    await ctx.reply(n > 0 ? `\u{1F5D1} Cleared ${n} queued message(s).` : "Queue was already empty.");
+  });
+
+  bot.command("model", async (ctx) => {
+    const modelId = (ctx.match || "").toString().trim();
+    const rt = deps.registry.get(ctx.chat.id);
+    if (!modelId) {
+      await ctx.reply("Usage: /model <model-id>  (changes the model for the current session)");
+      return;
+    }
+    if (!rt.sessionId) {
+      await ctx.reply("No active session yet. Send a message or pick a /projects folder first.");
+      return;
+    }
+    try {
+      await deps.acp.setModel(rt.sessionId, modelId);
+      await ctx.reply(`\u2705 Model set to \`${modelId}\` for this session.`, { parse_mode: "Markdown" });
+    } catch (err) {
+      await ctx.reply(`\u274C Could not set model: ${(err as Error).message}`);
+    }
+  });
+
+  bot.command("restart", async (ctx) => {
+    await ctx.reply("\u{1F501} Restarting the Grok agent\u2026");
+    try {
+      await deps.acp.restart();
+      await ctx.reply("\u2705 Grok agent restarted. Your session will re-bind on the next message.");
+    } catch (err) {
+      await ctx.reply(`\u274C Restart failed: ${(err as Error).message}`);
+    }
+  });
+}

package/src/bot/handlers/tasks.ts

@@ -0,0 +1,224 @@
+/**
+ * /tasks — manage scheduled tasks (create, list, view, edit, delete, run now).
+ * /newtask — start the creation wizard.
+ *
+ * A task is a prompt + a project + a schedule (once/daily/weekly/monthly/
+ * interval). The scheduler runs it and delivers the result here.
+ */
+import { type Bot, type Context, InlineKeyboard } from "grammy";
+import { basename } from "node:path";
+import type { BotDeps } from "../deps.js";
+import { describeSchedule } from "../../tasks/schedule.js";
+import type { Task } from "../../tasks/types.js";
+import type { ScheduleType } from "../../tasks/types.js";
+import type { WizardPrompt } from "../wizard/task-wizard.js";
+import { sendProjectMenu } from "./projects.js";
+
+const UUID = "([0-9a-fA-F-]{36})";
+
+export async function showTasks(ctx: Context, deps: BotDeps): Promise<void> {
+  await deps.ephemeral.open(ctx);
+  const { text, kb } = listView(deps, ctx.chat!.id);
+  await deps.ephemeral.reply(ctx, text, { reply_markup: kb });
+}
+
+export async function renderWizardPrompt(ctx: Context, deps: BotDeps, p: WizardPrompt): Promise<void> {
+  switch (p.kind) {
+    case "text":
+      await ctx.reply(p.text);
+      return;
+    case "project":
+      await sendProjectMenu(ctx, deps, "wiz:proj:", p.text);
+      return;
+    case "scheduleType": {
+      const kb = new InlineKeyboard()
+        .text("Once", "wiz:sched:once")
+        .text("Daily", "wiz:sched:daily")
+        .row()
+        .text("Weekly", "wiz:sched:weekly")
+        .text("Monthly", "wiz:sched:monthly")
+        .row()
+        .text("Every N minutes", "wiz:sched:interval");
+      await ctx.reply(p.text, { reply_markup: kb });
+      return;
+    }
+    case "confirm": {
+      const kb = new InlineKeyboard().text("\u2705 Save", "wiz:confirm").text("\u2716 Cancel", "wiz:cancel");
+      await ctx.reply(p.text, { reply_markup: kb });
+      return;
+    }
+    case "done":
+      await ctx.reply(p.text);
+      return;
+    case "aborted":
+      await ctx.reply("Cancelled.");
+      return;
+  }
+}
+
+/**
+ * Wizard text-input interceptor. Registered BEFORE command/prompt handlers so
+ * that, while a task wizard is active, free text feeds the wizard. A slash
+ * command aborts the wizard and is allowed through.
+ */
+export function registerWizardInput(bot: Bot, deps: BotDeps): void {
+  bot.on("message:text", async (ctx, next) => {
+    const chatId = ctx.chat.id;
+    if (!deps.wizard.isActive(chatId)) return next();
+    const text = ctx.message.text;
+    if (text.startsWith("/")) {
+      deps.wizard.abort(chatId);
+      return next();
+    }
+    const p = deps.wizard.handleText(chatId, text);
+    if (p) await renderWizardPrompt(ctx, deps, p);
+  });
+}
+
+export function registerTasks(bot: Bot, deps: BotDeps): void {
+  bot.command("tasks", (ctx) => showTasks(ctx, deps));
+  bot.command("newtask", async (ctx) => {
+    await renderWizardPrompt(ctx, deps, deps.wizard.startCreate(ctx.chat.id));
+  });
+
+  bot.callbackQuery("task:new", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await renderWizardPrompt(ctx, deps, deps.wizard.startCreate(ctx.chat!.id));
+  });
+
+  bot.callbackQuery(new RegExp(`^task:view:${UUID}$`), async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const task = deps.tasks.get(ctx.match![1]!);
+    if (!task) return void ctx.editMessageText("Task not found.");
+    const { text, kb } = detailView(task);
+    await ctx.editMessageText(text, { reply_markup: kb });
+  });
+
+  bot.callbackQuery("task:list", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const { text, kb } = listView(deps, ctx.chat!.id);
+    await ctx.editMessageText(text, { reply_markup: kb });
+  });
+
+  bot.callbackQuery(new RegExp(`^task:toggle:${UUID}$`), async (ctx) => {
+    const task = deps.tasks.get(ctx.match![1]!);
+    if (!task) return void ctx.answerCallbackQuery({ text: "Not found" });
+    const updated = deps.tasks.update(task.id, { enabled: !task.enabled });
+    await ctx.answerCallbackQuery({ text: updated?.enabled ? "Enabled" : "Disabled" });
+    if (updated) {
+      const { text, kb } = detailView(updated);
+      await ctx.editMessageText(text, { reply_markup: kb });
+    }
+  });
+
+  bot.callbackQuery(new RegExp(`^task:run:${UUID}$`), async (ctx) => {
+    const task = deps.tasks.get(ctx.match![1]!);
+    if (!task) return void ctx.answerCallbackQuery({ text: "Not found" });
+    await ctx.answerCallbackQuery({ text: "Running now\u2026" });
+    void deps.taskRunner.run(task);
+  });
+
+  bot.callbackQuery(new RegExp(`^task:del:${UUID}$`), async (ctx) => {
+    deps.tasks.delete(ctx.match![1]!);
+    await ctx.answerCallbackQuery({ text: "Deleted" });
+    const { text, kb } = listView(deps, ctx.chat!.id);
+    await ctx.editMessageText(text, { reply_markup: kb });
+  });
+
+  bot.callbackQuery(new RegExp(`^task:editmenu:${UUID}$`), async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const task = deps.tasks.get(ctx.match![1]!);
+    if (!task) return;
+    await ctx.editMessageText(`Edit "${task.name}" — choose what to change:`, {
+      reply_markup: editMenu(task.id),
+    });
+  });
+
+  bot.callbackQuery(new RegExp(`^task:edit:(name|prompt|project|schedule):${UUID}$`), async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const field = ctx.match![1] as "name" | "prompt" | "project" | "schedule";
+    const p = deps.wizard.startEdit(ctx.chat!.id, ctx.match![2]!, field);
+    if (p) await renderWizardPrompt(ctx, deps, p);
+    else await ctx.reply("Task not found.");
+  });
+
+  // ── wizard inline steps ────────────────────────────────────────────────
+  bot.callbackQuery(/^wiz:proj:(\d+)$/, async (ctx) => {
+    const entry = deps.menuCache.getProject(ctx.chat!.id, Number(ctx.match![1]));
+    if (!entry) return void ctx.answerCallbackQuery({ text: "Expired, restart the task." });
+    await ctx.answerCallbackQuery();
+    const p = deps.wizard.setProject(ctx.chat!.id, entry.path, entry.name);
+    if (p) await renderWizardPrompt(ctx, deps, p);
+  });
+
+  bot.callbackQuery(/^wiz:sched:(once|daily|weekly|monthly|interval)$/, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const p = deps.wizard.setScheduleType(ctx.chat!.id, ctx.match![1] as ScheduleType);
+    if (p) await renderWizardPrompt(ctx, deps, p);
+  });
+
+  bot.callbackQuery("wiz:confirm", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const p = deps.wizard.confirm(ctx.chat!.id);
+    if (p) await renderWizardPrompt(ctx, deps, p);
+  });
+
+  bot.callbackQuery("wiz:cancel", async (ctx) => {
+    await ctx.answerCallbackQuery();
+    deps.wizard.abort(ctx.chat!.id);
+    await ctx.editMessageText("Cancelled.");
+  });
+}
+
+// ── views ────────────────────────────────────────────────────────────────
+
+function listView(deps: BotDeps, chatId: number): { text: string; kb: InlineKeyboard } {
+  const tasks = deps.tasks.forChat(chatId);
+  const kb = new InlineKeyboard();
+  if (tasks.length === 0) {
+    kb.text("\u2795 New task", "task:new");
+    return { text: "You have no scheduled tasks yet.", kb };
+  }
+  for (const t of tasks) {
+    const dot = t.enabled ? "\u{1F7E2}" : "\u26AA";
+    const name = t.name.length > 24 ? t.name.slice(0, 24) + "\u2026" : t.name;
+    kb.text(`${dot} ${name} \u00B7 ${describeSchedule(t.schedule)}`, `task:view:${t.id}`).row();
+  }
+  kb.text("\u2795 New task", "task:new");
+  return { text: `\u{1F5D3} Your scheduled tasks (${tasks.length}):`, kb };
+}
+
+function detailView(t: Task): { text: string; kb: InlineKeyboard } {
+  const next = t.nextRun ? new Date(t.nextRun).toLocaleString() : "\u2014";
+  const last = t.lastRun ? `${new Date(t.lastRun).toLocaleString()} (${t.lastStatus ?? "?"})` : "never";
+  const prompt = t.prompt.length > 300 ? t.prompt.slice(0, 300) + "\u2026" : t.prompt;
+  const text = [
+    `\u{1F5D3} ${t.name}  ${t.enabled ? "\u{1F7E2} enabled" : "\u26AA disabled"}`,
+    `\u{1F4C1} Project: ${t.projectName || basename(t.projectPath)}`,
+    `\u{1F501} Schedule: ${describeSchedule(t.schedule)}`,
+    `\u23ED Next run: ${next}`,
+    `\u23EE Last run: ${last}`,
+    "",
+    `\u{1F4AC} ${prompt}`,
+  ].join("\n");
+  const kb = new InlineKeyboard()
+    .text("\u25B6 Run now", `task:run:${t.id}`)
+    .text(t.enabled ? "\u23F8 Disable" : "\u25B6 Enable", `task:toggle:${t.id}`)
+    .row()
+    .text("\u270F\uFE0F Edit", `task:editmenu:${t.id}`)
+    .text("\u{1F5D1} Delete", `task:del:${t.id}`)
+    .row()
+    .text("\u2B05 Back", "task:list");
+  return { text, kb };
+}
+
+function editMenu(id: string): InlineKeyboard {
+  return new InlineKeyboard()
+    .text("Rename", `task:edit:name:${id}`)
+    .text("Prompt", `task:edit:prompt:${id}`)
+    .row()
+    .text("Project", `task:edit:project:${id}`)
+    .text("Schedule", `task:edit:schedule:${id}`)
+    .row()
+    .text("\u2B05 Back", `task:view:${id}`);
+}

package/src/bot/handlers/usage.ts

@@ -0,0 +1,38 @@
+/**
+ * /usage — show account info and the current session's context usage.
+ */
+import type { Bot, Context } from "grammy";
+import type { BotDeps } from "../deps.js";
+
+export async function showUsage(ctx: Context, deps: BotDeps): Promise<void> {
+  await ctx.replyWithChatAction("typing").catch(() => {});
+  const rt = deps.registry.get(ctx.chat!.id);
+  const acct = await deps.usage.account();
+  const meta = rt.contextInfo();
+  const ctx100 = meta?.contextUsagePercentage;
+  const savedCount = deps.accounts.list().length;
+
+  const lines = [
+    "\u{1F4CA} Usage & account",
+    acct?.email ? `\u{1F464} ${acct.email}` : "",
+    acct?.accountType ? `\u{1F511} ${acct.accountType}${acct.region ? ` \u00B7 ${acct.region}` : ""}` : "",
+    "",
+    `\u{1F9F5} Session: ${rt.sessionId ? rt.sessionId.slice(0, 8) : "none"}`,
+    `\u{1F9E9} Model: ${rt.model || "default"}`,
+    `\u{1F4CA} Context used: ${ctx100 !== undefined ? `${ctx100.toFixed(0)}%` : "\u2014"}`,
+    `\u{1F501} Turns this session: ${rt.turns}`,
+    meta?.credits !== undefined ? `\u{1FA99} Credits used: ${meta.credits.toLocaleString("en-US")}` : "",
+    meta?.effort ? `\u{1F9E0} Effort: ${meta.effort}` : "",
+    savedCount > 0 ? `\u{1F465} Saved accounts: ${savedCount} \u00B7 /accounts to switch` : "",
+    "",
+    "\u2139\uFE0F Full billing/quota lives in the Grok app; grok doesn't expose limits headlessly.",
+  ].filter(Boolean);
+
+  if (!acct) lines.splice(1, 0, "(account info unavailable \u2014 is grok logged in?)");
+  await deps.ephemeral.open(ctx);
+  await deps.ephemeral.reply(ctx, lines.join("\n"));
+}
+
+export function registerUsage(bot: Bot, deps: BotDeps): void {
+  bot.command("usage", (ctx) => showUsage(ctx, deps));
+}

package/src/bot/handlers/voice.ts

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

package/src/bot/image-return.ts

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