grok-telegram-bot 2.0.0

package/src/bot/bot.ts

@@ -0,0 +1,225 @@
+/**
+ * Assemble the grammY bot: dependencies, middleware, handlers, persistent menu,
+ * status panel, and the task scheduler. Handler registration order matters:
+ *   auth -> menu buttons -> wizard input -> commands -> photos -> text prompt.
+ */
+import { Bot } from "grammy";
+import type { GrokClient } from "../grok/client.js";
+import { AccountManager } from "../app/accounts.js";
+import { AccountRotatorImpl } from "./account-rotator.js";
+import { SettingsStore } from "../app/settings-store.js";
+import { SttService } from "../app/stt.js";
+import { Updater } from "../app/updater.js";
+import { UsageService } from "../app/usage.js";
+import type { AppConfig } from "../config.js";
+import { INSTANCE_DIR } from "../config.js";
+import { createLogger } from "../logger.js";
+import { ProjectManager } from "../projects/manager.js";
+import { SessionStore } from "../sessions/store.js";
+import { TaskRunner } from "../tasks/runner.js";
+import { Scheduler } from "../tasks/scheduler.js";
+import { TaskStore } from "../tasks/store.js";
+import { createAuthMiddleware } from "./auth.js";
+import { COMMANDS } from "./commands.js";
+import { type BotDeps, MenuCache } from "./deps.js";
+import { registerControl } from "./handlers/control.js";
+import { registerDocuments } from "./handlers/document.js";
+import { registerHistory } from "./handlers/history.js";
+import { registerKill } from "./handlers/kill.js";
+import { registerMcp } from "./handlers/mcp.js";
+import { registerMenu } from "./handlers/menu.js";
+import { registerMessages } from "./handlers/message.js";
+import { registerPhotos } from "./handlers/photo.js";
+import { registerProjects } from "./handlers/projects.js";
+import { registerRunning, switchAndShow } from "./handlers/running.js";
+import { registerSessions } from "./handlers/sessions.js";
+import { registerSessionKill } from "./handlers/session-kill.js";
+import { registerAccounts } from "./handlers/accounts.js";
+import { registerReauth } from "./handlers/auth.js";
+import { registerSystem } from "./handlers/system.js";
+import { registerTasks, registerWizardInput } from "./handlers/tasks.js";
+import { registerUsage } from "./handlers/usage.js";
+import { registerVoice } from "./handlers/voice.js";
+import { StatusPanel } from "./menu/status-panel.js";
+import { sendMarkdownDoc } from "./telegram-io.js";
+import { Ephemeral } from "./menu/ephemeral.js";
+import { BAR_LABELS } from "./menu/keyboard.js";
+import { PermissionService } from "./permission-service.js";
+import { RuntimeRegistry } from "./registry.js";
+import { TaskWizard } from "./wizard/task-wizard.js";
+
+const log = createLogger("bot");
+
+/** Telegram methods that support disable_notification (silenced in quiet mode). */
+const SILENCEABLE = new Set([
+  "sendMessage",
+  "sendPhoto",
+  "sendDocument",
+  "sendAudio",
+  "sendVoice",
+  "sendVideo",
+  "sendAnimation",
+  "sendMediaGroup",
+  "copyMessage",
+  "forwardMessage",
+]);
+
+export interface BotBundle {
+  bot: Bot;
+  registry: RuntimeRegistry;
+  scheduler: Scheduler;
+  updater: Updater;
+}
+
+export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBundle> {
+  const bot = new Bot(cfg.token);
+
+  // Quiet mode (default): silence every outgoing message unless the caller
+  // explicitly set disable_notification:false (turn completion, permission
+  // prompts, task results). Edits never notify, so they're unaffected.
+  if (cfg.quietNotifications) {
+    bot.api.config.use(async (prev, method, payload, signal) => {
+      if (SILENCEABLE.has(method)) {
+        const p = payload as { disable_notification?: boolean };
+        if (p.disable_notification === undefined) p.disable_notification = true;
+      }
+      return prev(method, payload, signal);
+    });
+  }
+
+  const settings = new SettingsStore(cfg.dataDir);
+  const store = new SessionStore(cfg.sessionsDir);
+  const registry = new RuntimeRegistry(bot.api, acp, cfg, settings, store);
+  const tasks = new TaskStore(cfg.dataDir);
+  const taskRunner = new TaskRunner(bot.api, acp);
+  const wizard = new TaskWizard(tasks);
+  const statusPanel = new StatusPanel(bot.api, settings, registry);
+  registry.setRefresher((chatId) => void statusPanel.refresh(chatId));
+
+  const deps: BotDeps = {
+    api: bot.api,
+    cfg,
+    acp,
+    registry,
+    store,
+    projects: new ProjectManager(cfg.projectRoots),
+    menuCache: new MenuCache(),
+    settings,
+    statusPanel,
+    ephemeral: new Ephemeral(bot.api, cfg.dataDir),
+    tasks,
+    taskRunner,
+    wizard,
+    stt: new SttService({
+      apiUrl: cfg.sttApiUrl,
+      apiKey: cfg.sttApiKey,
+      model: cfg.sttModel,
+      language: cfg.sttLanguage,
+    }),
+    usage: new UsageService(cfg.grokCliPath),
+    accounts: new AccountManager(cfg.dataDir),
+  };
+
+  // Auto-rotate-on-give-up: let a stuck turn cycle through other saved logins.
+  registry.setAccountRotator(new AccountRotatorImpl(deps.accounts, acp));
+
+  // Inline approvals: when NOT in trust-all mode, Grok asks before risky tools.
+  const permissions = new PermissionService(bot.api, registry);
+  acp.permissionHandler = (p) => permissions.handle(p);
+
+  // The bot pins/unpins the status panel, and Telegram emits a "pinned a
+  // message" service message for each pin. Delete those so the chat stays clean
+  // — registered BEFORE auth so these bot-authored updates never reach the gate.
+  bot.on("message:pinned_message", (ctx) => void ctx.deleteMessage().catch(() => {}));
+
+  bot.use(createAuthMiddleware(cfg));
+
+  // Keep history clean: after handling, delete the user's command (/…) and
+  // persistent-bar button taps. Plain prompts and wizard input are kept.
+  bot.on("message:text", async (ctx, next) => {
+    await next();
+    const text = ctx.message?.text ?? "";
+    if (text.startsWith("/") || BAR_LABELS.includes(text)) {
+      await ctx.deleteMessage().catch(() => {});
+    }
+  });
+
+  bot.callbackQuery(/^perm:(\d+):(\d+)$/, async (ctx) => {
+    const label = permissions.resolveChoice(ctx.match![1]!, Number(ctx.match![2]));
+    await ctx.answerCallbackQuery({ text: label ?? "Expired" });
+    await ctx.editMessageText(label ? `\u{1F510} ${label}` : "\u{1F510} (expired)").catch(() => {});
+  });
+
+  bot.callbackQuery(/^permsw:(\d+)$/, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const sid = permissions.sessionFor(ctx.match![1]!);
+    if (sid) await switchAndShow(ctx, deps, sid);
+  });
+
+  registerMenu(bot, deps); // persistent-keyboard buttons (hears)
+  registerWizardInput(bot, deps); // wizard text input (before commands)
+  registerControl(bot, deps);
+  registerProjects(bot, deps);
+  registerSessions(bot, deps);
+  registerSessionKill(bot, deps);
+  registerRunning(bot, deps);
+  registerHistory(bot, deps);
+  registerSystem(bot, deps);
+  registerReauth(bot, deps);
+  registerAccounts(bot, deps);
+  registerUsage(bot, deps);
+  registerKill(bot, deps);
+  registerMcp(bot, deps);
+  registerTasks(bot, deps);
+  registerPhotos(bot, deps); // photos & image documents
+  registerDocuments(bot, deps); // non-image files (text inlined, binaries saved)
+  registerVoice(bot, deps); // voice / audio -> transcription -> prompt
+  registerMessages(bot, deps); // catch-all text prompt — keep last
+
+  bot.catch((err) => {
+    log.error("unhandled bot error:", err.error instanceof Error ? err.error.message : err.error);
+  });
+
+  try {
+    await bot.api.setMyCommands(COMMANDS);
+  } catch (e) {
+    log.warn("setMyCommands failed:", (e as Error).message);
+  }
+
+  const updater = new Updater({
+    enabled: cfg.autoUpdate,
+    intervalMs: cfg.updateCheckMs,
+    projectRoot: cfg.projectRoot,
+    instanceDir: INSTANCE_DIR,
+    dataDir: cfg.dataDir,
+    isPromptInFlight: () => acp.hasInflightPrompt(),
+    otherActiveSessions: () => store.listActive().filter((s) => s.lockPid !== acp.pid).length,
+    announce: async (text, markdown) => {
+      for (const id of settings.chatIds()) {
+        try {
+          if (markdown) await sendMarkdownDoc(bot.api, id, text, { loud: true });
+          else await bot.api.sendMessage(id, text, { disable_notification: false });
+        } catch {
+          /* per-chat best-effort */
+        }
+      }
+    },
+    shutdown: async () => {
+      try {
+        await bot.stop();
+      } catch {
+        /* ignore */
+      }
+      try {
+        acp.stop();
+      } catch {
+        /* ignore */
+      }
+    },
+  });
+
+  // Remove any navigation surface left over from before a restart.
+  void deps.ephemeral.cleanupAll().catch(() => {});
+
+  return { bot, registry, scheduler: new Scheduler(tasks, taskRunner), updater };
+}

package/src/bot/chat-controller.ts

@@ -0,0 +1,317 @@
+/**
+ * ChatController — manages the set of Grok sessions a single Telegram chat is
+ * controlling, with exactly one "foreground" session streaming live. Other
+ * (background) sessions keep running quietly; their output lands in the
+ * session's .jsonl and is replayed as "unread" when you switch to them.
+ */
+import { basename } from "node:path";
+import type { Api } from "grammy";
+import type { GrokClient } from "../grok/client.js";
+import type { SettingsStore } from "../app/settings-store.js";
+import type { AppConfig } from "../config.js";
+import { jsonlSize, readEntriesFrom, readHistory } from "../sessions/history.js";
+import type { SessionStore } from "../sessions/store.js";
+import type { HistoryEntry } from "../sessions/types.js";
+import type { AccountRotator } from "./account-rotator.js";
+import { SessionRuntime } from "./session-runtime.js";
+
+export interface RunningSession {
+  sessionId?: string;
+  projectName: string;
+  busy: boolean;
+  foreground: boolean;
+  unread: number;
+  /** Latest task-completion % (0–100) for this session, if known. */
+  progress?: number;
+}
+
+export interface SwitchResult {
+  rt: SessionRuntime;
+  sessionId?: string;
+  projectName?: string;
+  busy: boolean;
+  unread: HistoryEntry[];
+  firstView: boolean;
+  alreadyForeground: boolean;
+}
+
+export class ChatController {
+  private readonly runtimes: SessionRuntime[] = [];
+  private fg: SessionRuntime | undefined;
+  private readonly lastRead = new Map<string, number>();
+  private restored = false;
+
+  constructor(
+    private readonly api: Api,
+    private readonly chatId: number,
+    private readonly acp: GrokClient,
+    private readonly cfg: AppConfig,
+    private readonly settings: SettingsStore,
+    private readonly store: SessionStore,
+    private readonly refresh: (chatId: number) => void,
+    private readonly notifyActivity: (busy: boolean) => void,
+    private readonly getRotator?: () => AccountRotator | undefined,
+  ) {}
+
+  /** The current foreground runtime (created/restored lazily). */
+  foreground(): SessionRuntime {
+    this.ensureRestored();
+    if (!this.fg) {
+      const s = this.settings.get(this.chatId);
+      const rt = this.create({ cwd: s.projectPath ?? this.cfg.workspace, projectName: s.projectName, sessionId: s.sessionId });
+      this.runtimes.push(rt);
+      this.fg = rt;
+    }
+    return this.fg;
+  }
+
+  /** List the controlled sessions (for /running). */
+  list(): RunningSession[] {
+    this.ensureRestored();
+    this.pruneDuplicates();
+    return this.runtimes.map((rt) => ({
+      sessionId: rt.sessionId,
+      projectName: rt.projectName ?? basename(rt.cwd),
+      busy: rt.isBusy,
+      foreground: rt.isForeground,
+      unread: this.unreadCount(rt),
+      progress: rt.taskProgress,
+    }));
+  }
+
+  /** Start a brand-new session and bring it to the foreground. */
+  async addNew(cwd: string, projectName?: string): Promise<SessionRuntime> {
+    this.ensureRestored();
+    const prevFg = this.fg;
+    const rt = this.create({ cwd, projectName });
+    this.runtimes.push(rt);
+    this.fg = rt;
+    await this.background(prevFg);
+    await rt.startNewSession(cwd, projectName);
+    this.markSeen(rt);
+    this.persist();
+    return rt;
+  }
+
+  /**
+   * Connect to a session with resume-or-fork semantics (used by /sessions),
+   * adding it as a controlled session and bringing it to the foreground.
+   */
+  async addAttach(
+    sessionId: string,
+    cwd: string,
+    projectName: string | undefined,
+    priorEntries: HistoryEntry[],
+  ): Promise<{ rt: SessionRuntime; result: "resumed" | "forked"; alreadyControlled: boolean }> {
+    this.ensureRestored();
+    if (this.runtimes.some((r) => r.sessionId === sessionId)) {
+      const sw = await this.switchTo(sessionId);
+      return { rt: sw!.rt, result: "resumed", alreadyControlled: true };
+    }
+    // Reserve the runtime synchronously (before any await) so a concurrent tap
+    // on the same session finds it and switches instead of creating a duplicate.
+    const prevFg = this.fg;
+    const rt = this.create({ cwd, projectName, sessionId });
+    this.runtimes.push(rt);
+    this.fg = rt;
+    await this.background(prevFg);
+    const result = await rt.attach(sessionId, cwd, projectName, priorEntries);
+    this.markSeen(rt);
+    this.persist();
+    return { rt, result, alreadyControlled: false };
+  }
+
+  /** Connect to an existing session: switch if already controlled, else add it. */
+  async addResume(sessionId: string, cwd: string, projectName?: string): Promise<SwitchResult> {
+    this.ensureRestored();
+    if (this.runtimes.some((r) => r.sessionId === sessionId)) {
+      return (await this.switchTo(sessionId))!;
+    }
+    const prevFg = this.fg;
+    const rt = this.create({ cwd, projectName, sessionId });
+    this.runtimes.push(rt);
+    this.fg = rt;
+    await this.background(prevFg);
+    await rt.prepare().catch(() => {});
+    const path = this.store.jsonlPath(sessionId);
+    const unread = readHistory(path, 12);
+    this.lastRead.set(sessionId, jsonlSize(path));
+    this.persist();
+    return { rt, sessionId, projectName, busy: rt.isBusy, unread, firstView: true, alreadyForeground: false };
+  }
+
+  /** Switch the foreground to an already-controlled session. */
+  async switchTo(sessionId: string): Promise<SwitchResult | undefined> {
+    this.ensureRestored();
+    const rt = this.runtimes.find((r) => r.sessionId === sessionId);
+    if (!rt) return undefined;
+    if (rt === this.fg) {
+      return { rt, sessionId, projectName: rt.projectName, busy: rt.isBusy, unread: [], firstView: false, alreadyForeground: true };
+    }
+    await this.background(this.fg);
+    this.fg = rt;
+    await rt.setForeground(true);
+    await rt.prepare().catch(() => {});
+
+    const path = this.store.jsonlPath(sessionId);
+    const seen = this.lastRead.get(sessionId);
+    let unread: HistoryEntry[] = [];
+    let firstView = false;
+    if (seen !== undefined) {
+      unread = readEntriesFrom(path, seen).entries;
+    } else {
+      unread = readHistory(path, 12);
+      firstView = true;
+    }
+    this.lastRead.set(sessionId, jsonlSize(path));
+    // No tail-watch here: setForeground(true) above already resumed RICH live
+    // streaming for the in-flight turn via the agent's own session/update
+    // events. Tailing the .jsonl too would double-render every update.
+    this.persist();
+    return { rt, sessionId, projectName: rt.projectName, busy: rt.isBusy, unread, firstView, alreadyForeground: false };
+  }
+
+  /** Stop controlling a session (does not kill it). */
+  async close(sessionId: string): Promise<boolean> {
+    this.ensureRestored();
+    const idx = this.runtimes.findIndex((r) => r.sessionId === sessionId);
+    if (idx === -1) return false;
+    const rt = this.runtimes[idx]!;
+    rt.dispose();
+    this.runtimes.splice(idx, 1);
+    this.lastRead.delete(sessionId);
+    if (this.fg === rt) {
+      this.fg = this.runtimes[0];
+      if (this.fg) await this.fg.setForeground(true);
+    }
+    this.persist();
+    return true;
+  }
+
+  count(): number {
+    this.ensureRestored();
+    return this.runtimes.length;
+  }
+
+  /** Latest task-progress % for a controlled session id, if this chat runs it. */
+  progressFor(sessionId?: string): number | undefined {
+    if (!sessionId) return undefined;
+    this.ensureRestored();
+    return this.runtimes.find((r) => r.sessionId === sessionId)?.taskProgress;
+  }
+
+  findBySession(sessionId: string): boolean {
+    return this.runtimes.some((r) => r.sessionId === sessionId);
+  }
+
+  dispose(): void {
+    for (const rt of this.runtimes) rt.dispose();
+    this.runtimes.length = 0;
+    this.fg = undefined;
+  }
+
+  // ── internals ──────────────────────────────────────────────────────────────
+
+  private ensureRestored(): void {
+    if (this.restored) return;
+    this.restored = true;
+    const s = this.settings.get(this.chatId);
+    const seen = new Set<string>();
+    for (const cs of s.controlledSessions ?? []) {
+      if (!cs.sessionId || seen.has(cs.sessionId)) continue; // never restore the same session twice
+      seen.add(cs.sessionId);
+      this.runtimes.push(this.create({ cwd: cs.projectPath, projectName: cs.projectName, sessionId: cs.sessionId }));
+    }
+    if (this.runtimes.length > 0) {
+      const fg = this.runtimes.find((r) => r.sessionId === s.foregroundSessionId) ?? this.runtimes[0]!;
+      for (const r of this.runtimes) void r.setForeground(r === fg);
+      this.fg = fg;
+    }
+  }
+
+  /** Drop any runtime that duplicates another's sessionId (keeping the
+   *  foreground one), healing a state where two runtimes wrap one session. */
+  private pruneDuplicates(): void {
+    const byId = new Map<string, SessionRuntime>();
+    const kept: SessionRuntime[] = [];
+    for (const rt of this.runtimes) {
+      const id = rt.sessionId;
+      if (!id) {
+        kept.push(rt);
+        continue;
+      }
+      const prev = byId.get(id);
+      if (!prev) {
+        byId.set(id, rt);
+        kept.push(rt);
+        continue;
+      }
+      const loser = prev.isForeground || !rt.isForeground ? rt : prev;
+      const winner = loser === rt ? prev : rt;
+      if (winner !== prev) {
+        byId.set(id, winner);
+        const i = kept.indexOf(prev);
+        if (i !== -1) kept[i] = winner;
+      }
+      if (this.fg === loser) this.fg = winner;
+      loser.dispose();
+    }
+    if (kept.length !== this.runtimes.length) {
+      this.runtimes.length = 0;
+      this.runtimes.push(...kept);
+      this.persist();
+    }
+  }
+
+  private create(init: { cwd: string; projectName?: string; sessionId?: string }): SessionRuntime {
+    const rt = new SessionRuntime(this.api, this.chatId, this.acp, this.cfg, this.settings, init);
+    rt.onStateChange = () => this.refresh(this.chatId);
+    rt.onActivity = (busy) => this.notifyActivity(busy);
+    rt.accountRotator = this.getRotator?.();
+    // A logical fork (auto-fork-on-error / lost-session recovery) swaps the
+    // runtime's session id in place — re-persist the controlled list with the
+    // new id and treat the fresh session as already-seen.
+    rt.onSessionChange = () => {
+      this.markSeen(rt);
+      this.persist();
+    };
+    return rt;
+  }
+
+  private async background(rt: SessionRuntime | undefined): Promise<void> {
+    if (!rt) return;
+    this.markSeen(rt);
+    await rt.setForeground(false);
+  }
+
+  private markSeen(rt: SessionRuntime): void {
+    if (rt.sessionId) this.lastRead.set(rt.sessionId, jsonlSize(this.store.jsonlPath(rt.sessionId)));
+  }
+
+  private unreadCount(rt: SessionRuntime): number {
+    if (!rt.sessionId || rt.isForeground) return 0;
+    const seen = this.lastRead.get(rt.sessionId);
+    if (seen === undefined) return 0;
+    return readEntriesFrom(this.store.jsonlPath(rt.sessionId), seen).entries.length;
+  }
+
+  private persist(): void {
+    const seen = new Set<string>();
+    const controlled: { sessionId?: string; projectPath: string; projectName?: string }[] = [];
+    for (const r of this.runtimes) {
+      if (!r.sessionId || seen.has(r.sessionId)) continue;
+      seen.add(r.sessionId);
+      controlled.push({ sessionId: r.sessionId, projectPath: r.cwd, projectName: r.projectName });
+    }
+    this.settings.update(this.chatId, {
+      controlledSessions: controlled,
+      foregroundSessionId: this.fg?.sessionId,
+      // Keep the single-session restore fields aligned with the foreground so
+      // the pinned status panel and a fresh restore never show a project that
+      // belongs to a different (previously-foreground) session.
+      sessionId: this.fg?.sessionId,
+      projectPath: this.fg?.cwd,
+      projectName: this.fg?.projectName,
+    });
+  }
+}

package/src/bot/commands.ts

@@ -0,0 +1,52 @@
+/**
+ * Bot command definitions (for the Telegram command menu) and help text.
+ */
+export const COMMANDS: { command: string; description: string }[] = [
+  { command: "start", description: "Welcome, menu & status panel" },
+  { command: "menu", description: "Show the menu keyboard" },
+  { command: "projects", description: "Projects: list / search <q> / open <path> / new <name>" },
+  { command: "sessions", description: "List/resume sessions (active first) \u00b7 /sessions <q>" },
+  { command: "active", description: "Sessions running now on the PC" },
+  { command: "running", description: "Sessions this chat controls \u2014 switch between them" },
+  { command: "killall", description: "Kill all active sessions on the PC" },
+  { command: "mcp", description: "Inspect & toggle MCP servers \u00b7 health-check" },
+  { command: "tasks", description: "Manage scheduled tasks" },
+  { command: "newtask", description: "Create a scheduled task" },
+  { command: "history", description: "Show recent conversation history" },
+  { command: "new", description: "Start a fresh session here" },
+  { command: "status", description: "Current session, project & queue" },
+  { command: "usage", description: "Account & context usage" },
+  { command: "btw", description: "Run ASAP (now if idle, else next): /btw <text>" },
+  { command: "flush", description: "Send queued follow-ups now" },
+  { command: "queue", description: "Show queued follow-ups" },
+  { command: "cancel", description: "Stop the current turn" },
+  { command: "unwatch", description: "Stop following a live session" },
+  { command: "model", description: "Switch model: /model <id>" },
+  { command: "restart", description: "Restart the Grok agent" },
+  { command: "reauth", description: "Sign in to Grok (login or import)" },
+  { command: "accounts", description: "Switch between saved Grok accounts" },
+  { command: "help", description: "Show help" },
+];
+
+export const HELP_TEXT = [
+  "\u{1F916} Grok Telegram Bot",
+  "Drive Grok CLI from your phone \u2014 projects, resume, live sessions, diffs.",
+  "",
+  "HOW IT WORKS",
+  "\u2022 Just send a message to chat with Grok in the current project.",
+  "\u2022 While Grok is working, anything you send is queued and runs",
+  "  automatically when the current turn finishes.",
+  "",
+  "COMMANDS",
+  "/projects \u2014 choose which folder Grok works in",
+  "/sessions \u2014 resume one of your recent Grok sessions",
+  "/active \u2014 attach to a session currently running on the PC",
+  "/history \u2014 show the latest messages of the current session",
+  "/new \u2014 start a brand-new session in the current project",
+  "/btw <text> \u2014 run it now if idle, otherwise right after the current task",
+  "/flush \u2014 run queued follow-ups immediately",
+  "/cancel \u2014 stop the current turn",
+  "/status \u2014 show session, project and queue size",
+  "/reauth \u2014 sign in to Grok (grok login, or import an existing login)",
+  "/accounts \u2014 switch between saved Grok accounts",
+].join("\n");

package/src/bot/deps.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared dependencies passed to all handlers, plus a small per-chat cache for
+ * mapping inline-keyboard buttons back to long values (project paths).
+ */
+import type { Api } from "grammy";
+import type { GrokClient } from "../grok/client.js";
+import type { AccountManager } from "../app/accounts.js";
+import type { SettingsStore } from "../app/settings-store.js";
+import type { AppConfig } from "../config.js";
+import type { SttService } from "../app/stt.js";
+import type { UsageService } from "../app/usage.js";
+import type { ProjectEntry, ProjectManager } from "../projects/manager.js";
+import type { SessionMeta } from "../sessions/types.js";
+import type { SessionStore } from "../sessions/store.js";
+import type { TaskRunner } from "../tasks/runner.js";
+import type { TaskStore } from "../tasks/store.js";
+import type { StatusPanel } from "./menu/status-panel.js";
+import type { Ephemeral } from "./menu/ephemeral.js";
+import type { RuntimeRegistry } from "./registry.js";
+import type { TaskWizard } from "./wizard/task-wizard.js";
+
+export interface BotDeps {
+  api: Api;
+  cfg: AppConfig;
+  acp: GrokClient;
+  registry: RuntimeRegistry;
+  store: SessionStore;
+  projects: ProjectManager;
+  menuCache: MenuCache;
+  settings: SettingsStore;
+  statusPanel: StatusPanel;
+  ephemeral: Ephemeral;
+  tasks: TaskStore;
+  taskRunner: TaskRunner;
+  wizard: TaskWizard;
+  stt: SttService;
+  usage: UsageService;
+  accounts: AccountManager;
+}
+
+/** Caches the last project list shown per chat for callback resolution. */
+export class MenuCache {
+  private readonly projectLists = new Map<number, ProjectEntry[]>();
+  private readonly sessionLists = new Map<number, { metas: SessionMeta[]; heading: string }>();
+
+  setProjects(chatId: number, list: ProjectEntry[]): void {
+    this.projectLists.set(chatId, list);
+  }
+
+  getProject(chatId: number, index: number): ProjectEntry | undefined {
+    return this.projectLists.get(chatId)?.[index];
+  }
+
+  /** The full (sorted) project list, for paging the picker. */
+  getProjects(chatId: number): ProjectEntry[] | undefined {
+    return this.projectLists.get(chatId);
+  }
+
+  /** Remember the session set + heading currently being paged for a chat. */
+  setSessions(chatId: number, metas: SessionMeta[], heading: string): void {
+    this.sessionLists.set(chatId, { metas, heading });
+  }
+
+  getSessions(chatId: number): { metas: SessionMeta[]; heading: string } | undefined {
+    return this.sessionLists.get(chatId);
+  }
+}