grok-telegram-bot 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -7,6 +7,76 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The latest section is published verbatim as the GitHub Release notes by
 `.github/workflows/release.yml` when a `vX.Y.Z` tag is pushed.
 
+## [2.6.0] - 2026-08-30
+
+General becomes a chat-like **manager** for the forum group: memory-first
+routing, `send_prompt` into project topics with job report-back, and **visible
+short replies** (the previous notify-only quiet path looked like the bot was
+dead). Also bumps runtime deps (`tsx`, `grammy`).
+
+### Added
+
+- **General manager mode.** The forum **General** topic (`thread id 1`) is an
+  OpenClaw-style orchestrator, not a coding workspace. It keeps user messages,
+  starts a **new parallel session** per message (reply-to continues the same
+  session), streams **prose only** (no tools / progress / Done spam), and
+  dispatches real work into project topics.
+- **Manager directive + auto context.** First General prompt injects how to
+  behave (delegate, memory-first, no git-first). Every user turn also gets a
+  capped **MANAGER CONTEXT** block: topic catalog, recent General chat, ranked
+  memory hits, and in-process manager jobs.
+- **Manager jobs + work reports.** `send_prompt` from General registers a job
+  (`list_jobs`). When the child topic turn finishes, General is woken with a
+  structured `MANAGER WORK REPORT` so the manager can tell you done / failed.
+- **Bridge: `notify`, `list_topics`, `list_jobs`, `session_id`.**
+  - `notify` — optional extra ping (not required in General; prose is shown).
+  - `list_topics` / `list_jobs` — catalog and dispatch status for the agent.
+  - `send_prompt.session_id` — resume a **specific** Grok session (full UUID or
+    short prefix from memory). Topic may be omitted; path → forum topic is
+    inferred. Placeholder topics (`…`) are rejected / inferred from memory.
+- **Group memory ranking.** `search_memory` scores **relevance + recency**
+  (newest session per project path wins) so “last modifications” does not
+  surface stale Done notes. Hits include `[Xm/h/d ago]` stamps.
+- **Outbound General thread helper.** Telegram rejects `message_thread_id: 1`.
+  Sends/edits to General omit that field (`outboundThreadExtra`); inbound
+  routing still treats missing thread id as General.
+
+### Changed
+
+- **General UX.** User messages are **kept** (not replaced by prompt anchors).
+  Replies thread to the user message. A `Starting…` / `Thinking…` bubble is
+  edited in place into the short answer. Independent General messages no longer
+  coalesce into one queued turn.
+- **Prose is the user-facing channel.** The manager is told the user **sees**
+  free-form chat text. `notify` is optional. Bridge-result follow-ups (after
+  `search_memory` / `list_topics`) stream the real answer instead of staying
+  silent. If the model emits no prose, the Thinking bubble is replaced with a
+  short fallback — never deleted leaving an empty chat.
+- **Streamer prose-only mode.** General streams agent text only (no thoughts,
+  tools, plan board, or progress bar), seeded on the Thinking placeholder.
+- **Forum send path.** `sendMessage` / stream edits / auth deny / prompt
+  anchors / photos / docs use `outboundThreadExtra` so General posts succeed.
+- **Dependencies.** `tsx` `^4.19.2` → `^4.23.13`; `grammy` and `@types/node`
+  updated to current 1.x / 22.x wanted versions.
+
+### Fixed
+
+- **Bot not responding in General after manager-mode work.** Notify-only +
+  deleting `Thinking…` when `search_memory` chained made every answer vanish.
+  General now streams short prose, keeps the status bubble across bridge
+  follow-ups, and never drops the placeholder without a visible line.
+- **`message_thread_id: 1` rejected by Telegram** (“message thread not found”)
+  on General sends — omit the field for General; keep it for real topics.
+- **Manager context path trap.** Recent General history no longer treats every
+  session under the workspace root as General chat (title + exact cwd only).
+
+### Docs
+
+- **[docs/GROUP.md](./docs/GROUP.md)** — General = manager, memory-first
+  dispatch, `session_id`, `list_jobs`, prose vs `notify`.
+- **AGENTS.md** — General manager conventions for future changes.
+- **README** — General manager + expanded bridge actions.
+
 ## [2.5.0] - 2026-08-05
 
 Forum project topics, cross-topic Telegram bridge, prompt anchors, and a more
@@ -931,6 +1001,7 @@ from a single chat and switch between them, on a redesigned, compact menu.
   diffs, MarkdownV2 rendering, scheduled tasks, multi-image prompts, and a
   cross-platform 24/7 background service.
 
+[2.6.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.6.0
 [2.5.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.5.0
 [2.4.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.4.0
 [2.3.1]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.3.1

package/README.md

@@ -27,8 +27,9 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | Capability | What it does |
 |---|---|
 | 🗂 **Projects** | `/projects` browses your folders and runs Grok in the one you pick. |
-| 🏷 **Forum project topics** | Optional forum supergroup: one topic per project, **AI Chat** workspace, exact-name bind, `/forum_setup`. See **[docs/GROUP.md](./docs/GROUP.md)**. |
-| 🌉 **Telegram bridge** | Agent can `create_topic`, `set_path`, `send_prompt` across topics, `search_memory`, and call allowlisted sibling bots via JSON actions. |
+| 🏷 **Forum project topics** | Optional forum supergroup: **General** manager, **AI Chat** workspace, one topic per project, exact-name bind, `/forum_setup`. See **[docs/GROUP.md](./docs/GROUP.md)**. |
+| 🎛 **General manager** | Forum General is a chat-like orchestrator: memory-first, short replies, `send_prompt` into project topics, report-back when child work finishes. |
+| 🌉 **Telegram bridge** | Agent can `create_topic`, `set_path`, `send_prompt` (optional `session_id`), `notify`, `search_memory`, `list_topics` / `list_jobs`, and call allowlisted sibling bots via JSON actions. |
 | 🔖 **Prompt anchors** | Each user prompt is re-posted with a searchable `#prompt_…` tag; stream/Done messages reply to that anchor (media re-attached). |
 | 🆕 **New session** | `/new` or the bar **New** button starts a fresh session; forum topics keep New on the topic menu. |
 | 💡 **Post-turn suggestions** | After Done, 1–3 scored follow-ups as buttons; high-score items can auto-queue as one multi-step prompt. |
@@ -66,7 +67,8 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | Connect Grok CLI to Telegram (ACP) | ✅ | ✅ |
 | Switch between projects | ✅ | ❌ |
 | **Forum topics = projects** + AI Chat workspace | ✅ | ❌ |
-| **Cross-topic agent bridge** (create / bind / send_prompt) | ✅ | ❌ |
+| **General manager** (memory-first, dispatch + report-back) | ✅ | ❌ |
+| **Cross-topic agent bridge** (create / bind / send_prompt / session_id) | ✅ | ❌ |
 | Resume saved sessions | ✅ | ❌ |
 | Attach to **live** PC sessions (watch / fork) | ✅ | ❌ |
 | **Kill a session by PID** (or all at once) | ✅ | ❌ |

package/docs/GROUP.md

@@ -67,11 +67,24 @@ When the bot is later promoted to admin, it re-probes automatically (`my_chat_me
 
 | Topic | Working directory | Typical use |
 |---|---|---|
-| **General** / **AI Chat** | `GROK_WORKSPACE` | Orchestration, cross-project planning, agent bridge actions |
+| **General** | `GROK_WORKSPACE` | **Manager chat** (OpenClaw-style): routes work, memory-first, no coding spam |
+| **AI Chat** | `GROK_WORKSPACE` | Normal coding/conversation in the workspace |
 | **Project topic** | Bound project path | All coding work for that folder |
 | **User-created topic** | Bound after name/path match | Ad-hoc projects or new folders |
 
-Messages you send **inside a topic** are prompts for a session whose `cwd` is
+### General = manager
+
+Messages in **General** drive a chat-like orchestrator, not a coding agent:
+
+1. User asks in General (e.g. “fix login in MyApp”).
+2. Bot uses **memory + topic catalog** (auto-injected) and may call `search_memory` / `list_topics`.
+3. It replies briefly (“OK — I’ll start … in **MyApp**”) with **no progress bars / tool dumps**.
+4. It **dispatches** via `create_topic` / `set_path` / `send_prompt` into the right project topic.
+5. When that child turn finishes, the bridge **wakes General** with a `MANAGER WORK REPORT` so the manager summarizes success/fail for you.
+
+Real implementation stays in **project topics**. General should not edit app code.
+
+Messages you send **inside a project topic** are prompts for a session whose `cwd` is
 that topic’s path. Menus, model/reasoning picks, `/sessions`, `/running`, and
 Stop are **topic-scoped** so one project does not steal another’s session.
 
@@ -148,8 +161,11 @@ may feed results back as a quiet system turn (not a second Done).
 |---|---|
 | `create_topic` | New forum topic; optional `path` binds immediately |
 | `set_path` | Bind/rebind topic by title or `#threadId` |
-| `send_prompt` | Inject a prompt into another topic (`ran` / `queued`; optional `new_session`) |
-| `search_memory` | Search topic + session indexes |
+| `send_prompt` | Inject a prompt into another topic (`ran` / `queued`; optional `new_session`, **`session_id`** to resume a specific session) |
+| `notify` | Optional extra ping. In **General** the user already sees short chat prose; `notify` is not required. |
+| `search_memory` | Search topic + session indexes (memory-first) |
+| `list_topics` | List mapped forum topics (name, `#id`, path) |
+| `list_jobs` | List recent General → project dispatches |
 | `list_bots` | List allowlisted sibling bots |
 | `bot_command` | Call `/command@bot` and wait for that bot to settle |
 
@@ -174,6 +190,25 @@ Example (from General / AI Chat):
 
 `topic` may be the exact title, `#threadId`, `general`, or `ai chat`.
 
+To **resume a related session** found via memory (not the topic's currently open session):
+
+```json
+{
+  "telegram": [
+    {
+      "action": "send_prompt",
+      "topic": "MyApp",
+      "session_id": "019fc9ec",
+      "prompt": "Continue: apply the follow-up fix."
+    }
+  ]
+}
+```
+
+`session_id` may be a full UUID or a short prefix from memory hits. Without it, the bridge uses the topic's foreground session.
+
+`topic` must be an **exact** mapped title or `#threadId` (never placeholders like `…`). If only the session is known, omit `topic` — the bridge maps `session.cwd` → forum topic.
+
 ---
 
 ## Sibling bots (optional)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-telegram-bot",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Control the official Grok Build CLI from Telegram over the Agent Client Protocol (ACP). Sign in with your xAI account, switch projects, resume sessions, stream responses with diffs, queue follow-ups, manage multiple sign-ins, and run 24/7 as a cross-platform background service.",
   "type": "module",
   "main": "src/index.ts",
@@ -60,15 +60,15 @@
   "dependencies": {
     "diff": "^7.0.0",
     "dotenv": "^16.4.7",
-    "grammy": "^1.30.0",
-    "tsx": "^4.19.2"
+    "grammy": "^1.46.0",
+    "tsx": "^4.23.13"
   },
   "optionalDependencies": {
     "@homebridge/node-pty-prebuilt-multiarch": "0.13.1"
   },
   "devDependencies": {
     "@types/diff": "^7.0.0",
-    "@types/node": "^22.10.0",
+    "@types/node": "^22.20.1",
     "typescript": "^5.7.2"
   }
 }

package/src/app/types.ts

@@ -78,13 +78,37 @@ export interface PromptInput {
    * trigger another self-recheck — only real user prompts do (once each).
    */
   skipSelfRecheck?: boolean;
+  /**
+   * Manager dispatch metadata for this prompt only (General → project).
+   * Carried through the queue so concurrent send_prompt jobs do not steal
+   * each other's report-back. Shape matches bot/manager-jobs ReportBackMeta.
+   */
+  reportBack?: {
+    jobId: string;
+    originChatId: number;
+    originThreadId: number;
+    userAskPreview: string;
+    targetName: string;
+    targetPath: string;
+    dispatchPrompt: string;
+  };
+  /**
+   * Pre-posted status bubble (General: "Starting…") that the turn edits to
+   * "Thinking…" then streams the agent reply into.
+   */
+  seedMessageId?: number;
 }
 
 export function textPrompt(
   text: string,
   replyTo?: number,
   quotedText?: string,
-  opts?: { skipSelfRecheck?: boolean; promptId?: string },
+  opts?: {
+    skipSelfRecheck?: boolean;
+    promptId?: string;
+    reportBack?: PromptInput["reportBack"];
+    seedMessageId?: number;
+  },
 ): PromptInput {
   return {
     text,
@@ -94,5 +118,7 @@ export function textPrompt(
     promptId: opts?.promptId,
     quotedText,
     skipSelfRecheck: opts?.skipSelfRecheck,
+    reportBack: opts?.reportBack,
+    seedMessageId: opts?.seedMessageId,
   };
 }

package/src/bot/auth.ts

@@ -112,7 +112,11 @@ async function denyUnauthorized(
   }
   if (!ctx.chat || isGroupChat(ctx)) return; // groups: ignore quietly
   const threadId = m && "message_thread_id" in m ? m.message_thread_id : undefined;
-  const extra = threadId !== undefined ? { message_thread_id: threadId as number } : {};
+  // Omit General (1) — Bot API rejects message_thread_id=1.
+  const extra =
+    threadId !== undefined && threadId !== 1
+      ? { message_thread_id: threadId as number }
+      : {};
   await ctx
     .reply("\u26D4 Not authorized. Ask the bot owner to add your Telegram ID to ALLOWED_USERS.", extra)
     .catch(() => {});

package/src/bot/bot.ts

@@ -116,21 +116,58 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
     forum,
     bots: telegramBots,
     // Cross-topic orchestration: General can create a topic and send_prompt there.
-    submitTopicPrompt: async ({ threadId, cwd, projectName, prompt, newSession }) => {
+    // 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 = {
@@ -231,18 +268,50 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
     const index = Number(ctx.match![2]);
     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);
-    const rt = scope.rt;
-    const text = rt.takeSuggestion(batchId, index);
-    if (!text) {
+    // 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 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, {

package/src/bot/chat-controller.ts

@@ -63,6 +63,12 @@ export class ChatController {
   /** 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,
     private readonly chatId: number,
@@ -128,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.
@@ -410,6 +515,9 @@ export class ChatController {
       this.markSeen(rt);
       this.persist();
     };
+    rt.onTelegramMessageBound = (messageId, sessionId) => {
+      this.bindTelegramMessage(messageId, sessionId);
+    };
     return rt;
   }
 
@@ -466,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)
+  );
+}