grok-telegram-bot 2.4.0 → 2.6.0

package/src/bot/bot.ts

@@ -22,7 +22,7 @@ import { Scheduler } from "../tasks/scheduler.js";
 import { TaskStore } from "../tasks/store.js";
 import { createAuthMiddleware } from "./auth.js";
 import { isStaleCallbackError, safeCallbackMiddleware } from "./callback.js";
-import { COMMANDS } from "./commands.js";
+import { COMMANDS, GROUP_COMMANDS } from "./commands.js";
 import { type BotDeps, MenuCache } from "./deps.js";
 import { registerControl } from "./handlers/control.js";
 import { registerDocuments } from "./handlers/document.js";
@@ -43,6 +43,7 @@ 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 { registerForum } from "./handlers/forum.js";
 import { StatusPanel } from "./menu/status-panel.js";
 import { sendMarkdownDoc } from "./telegram-io.js";
 import { Ephemeral } from "./menu/ephemeral.js";
@@ -50,6 +51,8 @@ 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";
+import { ForumManager } from "../forum/manager.js";
+import { TelegramBotService } from "./telegram-bots.js";
 
 const log = createLogger("bot");
 
@@ -99,13 +102,81 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
   const statusPanel = new StatusPanel(bot.api, settings, registry);
   registry.setRefresher((chatId) => void statusPanel.refresh(chatId));
 
+  const projects = new ProjectManager(cfg.projectRoots);
+  const forum =
+    cfg.topicGroupId !== undefined
+      ? new ForumManager(bot.api, cfg, projects)
+      : undefined;
+
+  // Sibling bots + memory/topic actions for the agent telegram JSON bridge.
+  const telegramBots = new TelegramBotService(bot.api, cfg);
+  telegramBots.attachToBot(bot);
+  registry.setBridge({
+    store,
+    forum,
+    bots: telegramBots,
+    // Cross-topic orchestration: General can create a topic and send_prompt there.
+    // sessionId resumes a specific Grok session (memory follow-up) instead of
+    // dumping into whatever is currently open in that topic.
+    submitTopicPrompt: async ({
+      threadId,
+      cwd,
+      projectName,
+      prompt,
+      newSession,
+      sessionId,
+      reportBack,
+    }) => {
+      if (cfg.topicGroupId === undefined) {
+        throw new Error("TOPIC_GROUP_ID unset");
+      }
+      const groupId = cfg.topicGroupId;
+      const controller = registry.forumController(groupId, threadId, cwd, projectName);
+      // Explicit resume wins over newSession / foreground.
+      if (sessionId) {
+        const sw = await controller.addResume(sessionId, cwd, projectName);
+        if (reportBack) sw.rt.setReportBack(reportBack);
+        const outcome = await sw.rt.submit(textPrompt(prompt));
+        return { outcome, sessionId: sw.rt.sessionId ?? sessionId };
+      }
+      if (newSession) {
+        const rt = await controller.addNew(cwd, projectName);
+        if (reportBack) rt.setReportBack(reportBack);
+        const outcome = await rt.submit(textPrompt(prompt));
+        return { outcome, sessionId: rt.sessionId };
+      }
+      const rt = controller.foreground();
+      if (reportBack) rt.setReportBack(reportBack);
+      const outcome = await rt.submit(textPrompt(prompt));
+      return { outcome, sessionId: rt.sessionId };
+    },
+    // Child topic Done → wake General manager with a WORK REPORT.
+    wakeManager: async ({ originChatId, originThreadId, prompt }) => {
+      if (cfg.topicGroupId === undefined) {
+        throw new Error("TOPIC_GROUP_ID unset");
+      }
+      const groupId = cfg.topicGroupId;
+      // origin is always General in manager mode; bind workspace.
+      const controller = registry.forumController(
+        originChatId || groupId,
+        originThreadId,
+        cfg.workspace,
+        "General",
+      );
+      const rt = controller.foreground();
+      await rt.submit(
+        textPrompt(prompt, undefined, undefined, { skipSelfRecheck: true }),
+      );
+    },
+  });
+
   const deps: BotDeps = {
     api: bot.api,
     cfg,
     acp,
     registry,
     store,
-    projects: new ProjectManager(cfg.projectRoots),
+    projects,
     menuCache: new MenuCache(),
     settings,
     statusPanel,
@@ -121,6 +192,7 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
     }),
     usage: new UsageService(cfg.grokCliPath),
     accounts: new AccountManager(cfg.dataDir),
+    forum,
   };
 
   // Auto-rotate-on-give-up: let a stuck turn cycle through other saved logins.
@@ -135,6 +207,11 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
     onUnpinned: (chatId) => statusPanel.ensurePinned(chatId),
   });
   acp.permissionHandler = (p) => permissions.handle(p);
+  // /stop and /cancel must cancel pending interactive permissions for that
+  // session only (ACP requires cancelled outcomes) — never kill the agent.
+  acp.onSessionCancel = (sessionId) => {
+    permissions.cancelForSession(sessionId);
+  };
 
   // 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
@@ -146,14 +223,16 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
   // handler forgets (prevents the loading spinner + unhandled 400 noise).
   bot.use(safeCallbackMiddleware());
 
-  // Keep history clean: after handling, delete the user's command (/…) and
-  // persistent-bar button taps. Plain prompts and wizard input are kept.
+  // Keep history clean: delete the user's command (/…) and persistent-bar
+  // button taps INSTANTLY (before handlers) so slow ACP/CLI work never leaves
+  // the raw slash sitting in chat. Handlers post bot status messages instead.
+  // Plain prompts are adopted separately (see prompt-anchor.ts).
   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(() => {});
+      void ctx.deleteMessage().catch(() => {});
     }
+    await next();
   });
 
   bot.callbackQuery(/^perm:(\d+):(\d+)$/, async (ctx) => {
@@ -187,27 +266,90 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
   bot.callbackQuery(/^sug:(\d+):(\d+)$/, async (ctx) => {
     const batchId = Number(ctx.match![1]);
     const index = Number(ctx.match![2]);
-    const rt = deps.registry.get(ctx.chat!.id);
-    const text = rt.takeSuggestion(batchId, index);
-    if (!text) {
+    const { resolveScope } = await import("./scope.js");
+    const { adoptUserPrompt } = await import("./prompt-anchor.js");
+    const { isGeneralThread } = await import("../forum/thread.js");
+    const scope = resolveScope(ctx, deps);
+    // General may have parallel sessions — find the runtime that owns this batch.
+    const hit =
+      scope.controller.takeSuggestionAnywhere(batchId, index) ??
+      (() => {
+        const t = scope.rt.takeSuggestion(batchId, index);
+        return t ? { rt: scope.rt, text: t } : undefined;
+      })();
+    if (!hit) {
       await ctx.answerCallbackQuery({ text: "Suggestion expired", show_alert: true });
       return;
     }
+    const { rt, text } = hit;
     await ctx.answerCallbackQuery({ text: "Sending\u2026" });
     // Dim the keyboard so double-taps don't re-fire.
     await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } }).catch(() => {});
     try {
-      const outcome = await rt.submit(textPrompt(text, ctx.callbackQuery.message?.message_id));
+      const chatId = ctx.chat?.id;
+      const isGeneral = isGeneralThread(scope.threadId);
+      const sugMsgId = ctx.callbackQuery.message?.message_id;
+      // General: keep chat clean — no anchor overwrite; continue same session
+      // and reply to the message that carried the buttons.
+      if (isGeneral) {
+        if (rt.sessionId && sugMsgId !== undefined) {
+          scope.controller.bindTelegramMessage(sugMsgId, rt.sessionId);
+        }
+        const outcome = await rt.submit(
+          textPrompt(text, sugMsgId, undefined, { promptId: undefined }),
+        );
+        if (outcome === "queued") {
+          const extra: Record<string, unknown> = { ...scope.threadExtra };
+          if (sugMsgId !== undefined) {
+            extra.reply_parameters = {
+              message_id: sugMsgId,
+              allow_sending_without_reply: true,
+            };
+          }
+          await deps.api
+            .sendMessage(chatId!, "\u{1F4E5} Queued on that thread.", extra)
+            .catch(() => {});
+        }
+        return;
+      }
+      const anchor =
+        chatId !== undefined
+          ? await adoptUserPrompt(deps.api, {
+              chatId,
+              text,
+              userMessageIds: [],
+              messageThreadId: scope.threadExtra.message_thread_id,
+              projectName: rt.projectName,
+              prefix: "\u{1F4A1} Suggestion",
+            })
+          : undefined;
+      const outcome = await rt.submit(
+        textPrompt(text, anchor?.replyTo ?? ctx.callbackQuery.message?.message_id, undefined, {
+          promptId: anchor?.promptId,
+        }),
+      );
       if (outcome === "queued") {
-        await ctx.reply(`\u{1F4E5} Queued suggestion (position ${rt.queueLength}).`).catch(() => {});
+        const extra: Record<string, unknown> = { ...scope.threadExtra };
+        if (anchor?.replyTo !== undefined) {
+          extra.reply_parameters = {
+            message_id: anchor.replyTo,
+            allow_sending_without_reply: true,
+          };
+        }
+        await ctx
+          .reply(`\u{1F4E5} Queued suggestion (position ${rt.queueLength}).`, extra)
+          .catch(() => {});
       }
     } catch (e) {
-      await ctx.reply(`\u274C Couldn't run suggestion: ${(e as Error).message}`).catch(() => {});
+      await ctx
+        .reply(`\u274C Couldn't run suggestion: ${(e as Error).message}`, scope.threadExtra)
+        .catch(() => {});
     }
   });
 
   registerMenu(bot, deps); // persistent-keyboard buttons (hears)
   registerWizardInput(bot, deps); // wizard text input (before commands)
+  if (forum) registerForum(bot, deps, forum);
   registerControl(bot, deps);
   registerProjects(bot, deps);
   registerSessions(bot, deps);
@@ -234,13 +376,40 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
       log.debug("stale callback query:", err.error instanceof Error ? err.error.message : err.error);
       return;
     }
-    log.error("unhandled bot error:", err.error instanceof Error ? err.error.message : err.error);
+    const e = err.error;
+    if (e instanceof Error) {
+      // Include Grammy error_code when present (429 / 403 / 409, etc.) for diagnosis.
+      const codeNum = (e as unknown as { error_code?: number }).error_code;
+      const code = typeof codeNum === "number" ? ` (code ${codeNum})` : "";
+      log.error(`unhandled bot error${code}:`, e.stack || e.message);
+    } else {
+      log.error("unhandled bot error:", e);
+    }
+    // Never rethrow — a middleware failure must not take down long polling.
   });
 
-  try {
-    await bot.api.setMyCommands(COMMANDS);
-  } catch (e) {
-    log.warn("setMyCommands failed:", (e as Error).message);
+  // Scoped command menus: private = full sorted list; groups = short list with
+  // cancel/menu first (reply keyboard is unreliable in forum topics).
+  const registerCommands = async (
+    commands: typeof COMMANDS,
+    scope?: { type: string; chat_id?: number },
+    label = "default",
+  ): Promise<void> => {
+    try {
+      await bot.api.setMyCommands(commands, scope ? { scope: scope as never } : undefined);
+    } catch (e) {
+      log.warn(`setMyCommands (${label}) failed:`, (e as Error).message);
+    }
+  };
+  await registerCommands(COMMANDS, undefined, "default");
+  await registerCommands(COMMANDS, { type: "all_private_chats" }, "private");
+  await registerCommands(GROUP_COMMANDS, { type: "all_group_chats" }, "groups");
+  if (cfg.topicGroupId !== undefined) {
+    await registerCommands(
+      GROUP_COMMANDS,
+      { type: "chat", chat_id: cfg.topicGroupId },
+      `chat:${cfg.topicGroupId}`,
+    );
   }
 
   const updater = new Updater({
@@ -278,5 +447,12 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
   // Remove any navigation surface left over from before a restart.
   void deps.ephemeral.cleanupAll().catch(() => {});
 
+  // Forum project topics: ensure AI Chat + optional catalog topics (best-effort).
+  if (forum) {
+    void forum.ensureSetup().catch((e) => {
+      log.warn(`forum setup failed: ${(e as Error).message}`);
+    });
+  }
+
   return { bot, registry, scheduler: new Scheduler(tasks, taskRunner), updater };
 }

package/src/bot/chat-controller.ts

@@ -23,10 +23,7 @@ export interface RunningSession {
   unread: number;
   /** Latest task-completion % (0–100) for this session, if known. */
   progress?: number;
-  /**
-   * Card comment: live step while working, chat summary when idle
-   * ("what is happening / what was done").
-   */
+  /** Card comment: last user prompt (+ last AI thinking while busy). */
   comment?: string;
 }
 
@@ -40,11 +37,37 @@ export interface SwitchResult {
   alreadyForeground: boolean;
 }
 
+export interface ChatControllerOpts {
+  /** Forum topic thread — all runtimes post into this topic. */
+  messageThreadId?: number;
+  /** Settings key (`chatId` or `chatId:t{thread}`). Defaults to String(chatId). */
+  settingsKey?: string;
+  /** Fixed project path (forum topics): never switch away via project picker. */
+  fixedCwd?: string;
+  fixedProjectName?: string;
+}
+
+/** Optional Telegram bridge services attached to every runtime in this chat. */
+export type ChatBridgeServices = SessionRuntime["bridge"];
+
 export class ChatController {
   private readonly runtimes: SessionRuntime[] = [];
   private fg: SessionRuntime | undefined;
   private readonly lastRead = new Map<string, number>();
   private restored = false;
+  readonly settingsKey: string;
+  readonly messageThreadId: number | undefined;
+  readonly fixedCwd: string | undefined;
+  readonly fixedProjectName: string | undefined;
+
+  /** Telegram bridge (forum / memory / sibling bots); set by the registry. */
+  bridge?: ChatBridgeServices;
+
+  /**
+   * General manager: map Telegram message ids (user + bot) → session id so a
+   * reply-to continues the same ACP session instead of spawning a new one.
+   */
+  private readonly telegramMsgSessions = new Map<number, string>();
 
   constructor(
     private readonly api: Api,
@@ -56,14 +79,22 @@ export class ChatController {
     private readonly refresh: (chatId: number) => void,
     private readonly notifyActivity: (busy: boolean) => void,
     private readonly getRotator?: () => AccountRotator | undefined,
-  ) {}
+    opts?: ChatControllerOpts,
+  ) {
+    this.messageThreadId = opts?.messageThreadId;
+    this.settingsKey = opts?.settingsKey ?? String(chatId);
+    this.fixedCwd = opts?.fixedCwd;
+    this.fixedProjectName = opts?.fixedProjectName;
+  }
 
   /** 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 });
+      const s = this.settings.getKey(this.settingsKey);
+      const cwd = this.fixedCwd ?? s.projectPath ?? this.cfg.workspace;
+      const name = this.fixedProjectName ?? s.projectName;
+      const rt = this.create({ cwd, projectName: name, sessionId: s.sessionId });
       this.runtimes.push(rt);
       this.fg = rt;
     }
@@ -103,6 +134,105 @@ export class ChatController {
     return rt;
   }
 
+  /**
+   * General manager: spawn a fresh session for one user message without
+   * killing an in-flight sibling's Telegram stream (parallel prompts).
+   */
+  async addParallel(cwd: string, projectName?: string): Promise<SessionRuntime> {
+    return this.addNew(cwd, projectName);
+  }
+
+  /** Remember that a Telegram message belongs to a Grok session (reply routing). */
+  bindTelegramMessage(messageId: number, sessionId: string): void {
+    if (!messageId || !sessionId) return;
+    this.telegramMsgSessions.set(messageId, sessionId);
+    // Cap map growth (keep newest ~500).
+    if (this.telegramMsgSessions.size > 500) {
+      const drop = this.telegramMsgSessions.size - 500;
+      let i = 0;
+      for (const k of this.telegramMsgSessions.keys()) {
+        this.telegramMsgSessions.delete(k);
+        if (++i >= drop) break;
+      }
+    }
+  }
+
+  /** Resolve a controlled runtime from a Telegram message id (reply-to). */
+  runtimeForTelegramMessage(messageId: number | undefined): SessionRuntime | undefined {
+    if (messageId === undefined) return undefined;
+    this.ensureRestored();
+    const sid = this.telegramMsgSessions.get(messageId);
+    if (sid) {
+      const byId = this.runtimes.find((r) => r.sessionId === sid);
+      if (byId) return byId;
+    }
+    return undefined;
+  }
+
+  /**
+   * Resolve session from `#sess_xxxxxxxx` in a replied-to bot message body
+   * (works across process restarts when the in-memory map is cold).
+   */
+  runtimeForSessionTag(text: string | undefined): SessionRuntime | undefined {
+    if (!text) return undefined;
+    this.ensureRestored();
+    const tag = parseSessTag(text);
+    if (!tag) return undefined;
+    return this.runtimes.find((r) => r.sessionId && sessionMatchesTag(r.sessionId, tag));
+  }
+
+  /**
+   * Cold-start / map-miss: resolve continue target from reply message id, #sess_
+   * tag on controlled runtimes, or disk session list (attach into this controller).
+   */
+  async resolveContinueFromReply(opts: {
+    replyToMessageId?: number;
+    replyToText?: string;
+    cwd: string;
+    projectName?: string;
+  }): Promise<SessionRuntime | undefined> {
+    this.ensureRestored();
+    const byMsg = this.runtimeForTelegramMessage(opts.replyToMessageId);
+    if (byMsg) return byMsg;
+    const byTag = this.runtimeForSessionTag(opts.replyToText);
+    if (byTag) return byTag;
+
+    const tag = parseSessTag(opts.replyToText);
+    if (!tag) return undefined;
+    // Disk fallback: find full session id, then resume into this controller.
+    let metas;
+    try {
+      metas = this.store.list(80);
+    } catch {
+      return undefined;
+    }
+    const meta = metas.find((m) => sessionMatchesTag(m.sessionId, tag));
+    if (!meta) return undefined;
+    try {
+      const sw = await this.addResume(
+        meta.sessionId,
+        meta.cwd || opts.cwd,
+        opts.projectName,
+      );
+      return sw.rt;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Find any runtime that still holds this suggestion batch (General parallel). */
+  takeSuggestionAnywhere(
+    batchId: number,
+    index: number,
+  ): { rt: SessionRuntime; text: string } | undefined {
+    this.ensureRestored();
+    for (const r of this.runtimes) {
+      const text = r.takeSuggestion(batchId, index);
+      if (text) return { rt: r, text };
+    }
+    return undefined;
+  }
+
   /**
    * Switch the chat to a project directory **without** waiting on ACP.
    * - Reuses an existing controlled runtime for the same path when possible.
@@ -279,7 +409,7 @@ export class ChatController {
     return this.runtimes.find((r) => r.sessionId === sessionId)?.taskProgress;
   }
 
-  /** Live step / chat summary for a controlled session id. */
+  /** Last user prompt (+ thinking when busy) for a controlled session id. */
   commentFor(sessionId?: string): string | undefined {
     if (!sessionId) return undefined;
     this.ensureRestored();
@@ -301,27 +431,31 @@ export class ChatController {
   private ensureRestored(): void {
     if (this.restored) return;
     this.restored = true;
-    const s = this.settings.get(this.chatId);
+    const s = this.settings.getKey(this.settingsKey);
     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);
+      // Forum topics only restore sessions for the fixed project path.
+      if (this.fixedCwd && normPath(cs.projectPath) !== normPath(this.fixedCwd)) continue;
       this.runtimes.push(this.create({ cwd: cs.projectPath, projectName: cs.projectName, sessionId: cs.sessionId }));
     }
     // Lazy project switches persist projectPath without a sessionId. If the
     // saved project is not among controlled sessions, recreate an unbound FG
     // so a restart lands on the project the user last chose.
-    if (s.projectPath) {
-      const key = normPath(s.projectPath);
+    const homePath = this.fixedCwd ?? s.projectPath;
+    const homeName = this.fixedProjectName ?? s.projectName;
+    if (homePath) {
+      const key = normPath(homePath);
       const hasProject = this.runtimes.some((r) => normPath(r.cwd) === key);
       if (!hasProject) {
-        this.runtimes.push(this.create({ cwd: s.projectPath, projectName: s.projectName }));
+        this.runtimes.push(this.create({ cwd: homePath, projectName: homeName, sessionId: s.sessionId }));
       }
     }
     if (this.runtimes.length > 0) {
       let fg = this.runtimes.find((r) => r.sessionId && r.sessionId === s.foregroundSessionId);
-      if (!fg && s.projectPath) {
-        const key = normPath(s.projectPath);
+      if (!fg && homePath) {
+        const key = normPath(homePath);
         fg = this.runtimes.find((r) => normPath(r.cwd) === key);
       }
       fg = fg ?? this.runtimes[0]!;
@@ -365,10 +499,15 @@ export class ChatController {
   }
 
   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);
+    const rt = new SessionRuntime(this.api, this.chatId, this.acp, this.cfg, this.settings, {
+      ...init,
+      messageThreadId: this.messageThreadId,
+      settingsKey: this.settingsKey,
+    });
     rt.onStateChange = () => this.refresh(this.chatId);
     rt.onActivity = (busy) => this.notifyActivity(busy);
     rt.accountRotator = this.getRotator?.();
+    rt.bridge = this.bridge;
     // 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.
@@ -376,6 +515,9 @@ export class ChatController {
       this.markSeen(rt);
       this.persist();
     };
+    rt.onTelegramMessageBound = (messageId, sessionId) => {
+      this.bindTelegramMessage(messageId, sessionId);
+    };
     return rt;
   }
 
@@ -415,15 +557,15 @@ export class ChatController {
       seen.add(r.sessionId);
       controlled.push({ sessionId: r.sessionId, projectPath: r.cwd, projectName: r.projectName });
     }
-    this.settings.update(this.chatId, {
+    this.settings.updateKey(this.settingsKey, {
       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,
+      projectPath: this.fixedCwd ?? this.fg?.cwd,
+      projectName: this.fixedProjectName ?? this.fg?.projectName,
     });
   }
 }
@@ -432,3 +574,24 @@ export class ChatController {
 function normPath(p: string): string {
   return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
 }
+
+/** Extract `#sess_xxxxxxxx` from bot message text/caption. */
+function parseSessTag(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  const m = text.match(/#sess_([a-z0-9]{6,12})/i);
+  return m?.[1]?.toLowerCase();
+}
+
+/** Match full session UUID (or short form) to a #sess_ tag body. */
+function sessionMatchesTag(sessionId: string, tag: string): boolean {
+  const compact = sessionId.replace(/-/g, "").toLowerCase();
+  const short = sessionId.slice(0, 8).replace(/[^a-z0-9]/gi, "").toLowerCase();
+  const t = tag.toLowerCase();
+  return (
+    short === t ||
+    short.startsWith(t) ||
+    t.startsWith(short) ||
+    compact.startsWith(t) ||
+    sessionId.toLowerCase().startsWith(t)
+  );
+}