grok-telegram-bot 2.5.0 → 2.7.0

package/src/bot/group-memory.ts

@@ -2,6 +2,9 @@
  * Local "group memory" search across forum topics, session metadata, and
  * recent session history. Telegram bots have no general message-search API,
  * so this indexes what the bridge already stores on disk.
+ *
+ * Ranking is **relevance + recency**: newer sessions / history win over old
+ * matching text so "what was last worked on" does not surface stale Done notes.
  */
 import { join } from "node:path";
 import { readHistory } from "../sessions/history.js";
@@ -19,6 +22,8 @@ export interface MemoryHit {
   path?: string;
   sessionId?: string;
   threadId?: number;
+  /** Epoch ms for secondary sort / display (session or entry time). */
+  at?: number;
 }
 
 export interface GroupMemorySearchOpts {
@@ -29,6 +34,13 @@ export interface GroupMemorySearchOpts {
   topics?: ForumTopicBinding[];
   /** Max sessions whose JSONL tails are scanned. */
   maxSessions?: number;
+  /**
+   * Prefer sessions under these paths (e.g. workspace for General, then a
+   * project path). Earlier paths get a higher score boost.
+   */
+  preferPaths?: string[];
+  /** Boost history from sessions whose title/comment looks like General manager. */
+  preferGeneral?: boolean;
 }
 
 /** Tokenize a query into lowercase alphanumeric tokens (min length 2). */
@@ -62,72 +74,208 @@ export function scoreTokens(haystack: string, tokens: string[]): number {
   return score;
 }
 
+/**
+ * True when the user is asking what happened *recently* (last mods, last work).
+ * These queries weight recency much higher than pure text match.
+ * Avoid bare "work"/"done" — those appear in many normal asks and would
+ * over-prioritize recency over relevance.
+ */
+export function queryWantsRecency(query: string): boolean {
+  return /\b(last|latest|recent|newest|today|yesterday|modif(?:y|ied|ication|ications)?|changes?|changed|updated|what\s+was|what\s+did|last\s+work|recent\s+work|last\s+done)\b/i.test(
+    query,
+  );
+}
+
+/**
+ * Normalize epoch seconds vs milliseconds (or ISO string) to ms.
+ * Returns undefined when missing/invalid (never NaN).
+ */
+export function normalizeEpochMs(
+  value: string | number | undefined,
+): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  let t: number;
+  if (typeof value === "number") {
+    t = value;
+  } else {
+    t = Date.parse(value);
+  }
+  if (!Number.isFinite(t) || t <= 0) return undefined;
+  // Seconds since epoch (~1e9) → ms. ms since epoch is ~1e12+.
+  if (t > 0 && t < 1e11) t *= 1000;
+  if (!Number.isFinite(t) || t <= 0) return undefined;
+  return t;
+}
+
+/**
+ * Recency score 0–20 from an updatedAt ISO string or epoch ms/seconds.
+ * <1h:20, <6h:16, <24h:12, <3d:8, <7d:4, <30d:2, older:0.
+ */
+export function recencyBoost(updatedAt: string | number | undefined, now = Date.now()): number {
+  const t = normalizeEpochMs(updatedAt);
+  if (t === undefined) return 0;
+  const ageH = Math.max(0, (now - t) / 3_600_000);
+  if (ageH < 1) return 20;
+  if (ageH < 6) return 16;
+  if (ageH < 24) return 12;
+  if (ageH < 72) return 8;
+  if (ageH < 168) return 4;
+  if (ageH < 720) return 2;
+  return 0;
+}
+
+/** Human-ish age for snippets. */
+export function formatAge(at: number | undefined, now = Date.now()): string {
+  if (!at || !Number.isFinite(at)) return "";
+  const mins = Math.max(0, Math.round((now - at) / 60_000));
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.round(mins / 60);
+  if (hours < 48) return `${hours}h ago`;
+  const days = Math.round(hours / 24);
+  return `${days}d ago`;
+}
+
 /**
  * Search topics + session store + recent history. Pure ranking over provided
  * store; safe to call on the main bot thread (capped I/O).
+ *
+ * Sort key: score (relevance + recency) DESC, then `at` DESC (newest first).
  */
 export function searchGroupMemory(opts: GroupMemorySearchOpts): MemoryHit[] {
   const tokens = tokenizeQuery(opts.query);
   if (tokens.length === 0) return [];
   const limit = Math.max(1, Math.min(20, opts.limit ?? 8));
   const maxSessions = opts.maxSessions ?? 40;
+  const now = Date.now();
+  const wantsRecent = queryWantsRecency(opts.query);
+  /** Multiply recency when user asks for last/recent work. */
+  const recencyMul = wantsRecent ? 2.5 : 1.2;
   const hits: MemoryHit[] = [];
 
   for (const t of opts.topics ?? []) {
     const hay = [t.name, t.projectPath ?? "", t.kind, t.sessionId ?? ""].join("\n");
     const score = scoreTokens(hay, tokens);
     if (score <= 0) continue;
+    // Topic map updatedAt is already epoch ms.
+    const at = normalizeEpochMs(t.updatedAt);
+    // Mild recency on topics (routing), not full "last work" weight.
+    const r = recencyBoost(at, now) * Math.min(1.2, recencyMul);
     hits.push({
       kind: "topic",
       title: t.name,
       snippet: t.projectPath ? `path: ${t.projectPath}` : `kind: ${t.kind}`,
-      score: score + 2, // slight boost for topic map
+      score: score + 2 + r,
       path: t.projectPath ?? undefined,
       threadId: t.threadId,
       sessionId: t.sessionId,
+      at,
     });
   }
 
   let metas: SessionMeta[] = [];
   try {
+    // Store already returns most-recently-updated first.
     metas = opts.store.list(maxSessions);
   } catch {
     metas = [];
   }
 
+  const prefer = (opts.preferPaths ?? []).map((p) => p.replace(/\\/g, "/").toLowerCase());
+
+  // Per project path: which session is the newest (for "last work in X").
+  const newestByCwd = new Map<string, number>();
   for (const m of metas) {
+    const key = normPath(m.cwd);
+    if (!key) continue;
+    const t = normalizeEpochMs(m.updatedAt) ?? 0;
+    const prev = newestByCwd.get(key) ?? 0;
+    if (t > prev) newestByCwd.set(key, t);
+  }
+
+  for (const m of metas) {
+    const pathBoost = pathPreferenceBoost(m.cwd, prefer);
+    const generalBoost =
+      opts.preferGeneral &&
+      (/^general$/i.test(m.title || "") || /general/i.test(m.comment || ""))
+        ? 5
+        : 0;
+    const sessionAt = normalizeEpochMs(m.updatedAt);
+    const rBoost = recencyBoost(sessionAt, now) * recencyMul;
+    const newestBoost =
+      sessionAt !== undefined && newestByCwd.get(normPath(m.cwd)) === sessionAt ? 10 : 0;
+
     const hay = [m.title, m.comment ?? "", m.cwd, m.sessionId].join("\n");
-    const score = scoreTokens(hay, tokens);
-    if (score > 0) {
+    const base = scoreTokens(hay, tokens);
+    // Require text relevance — path/recency alone never invents a hit.
+    if (base <= 0) {
+      // Still scan history below if the session might contain matching tails.
+    }
+    const score = base + pathBoost + generalBoost + rBoost + newestBoost;
+    const age = formatAge(sessionAt, now);
+
+    if (base > 0 && Number.isFinite(score) && score > 0) {
       hits.push({
         kind: "session",
         title: m.title || m.sessionId.slice(0, 8),
         snippet: clamp(
-          [m.comment, m.cwd].filter(Boolean).join(" · ") || m.sessionId,
-          220,
+          [age ? `[${age}]` : "", m.comment, m.cwd].filter(Boolean).join(" · ") || m.sessionId,
+          240,
         ),
         score,
         path: m.cwd || undefined,
         sessionId: m.sessionId,
+        at: sessionAt,
       });
     }
 
-    // History tail (cheap): few entries, short text.
+    // History: deeper tail for recent or path-matched sessions.
+    const histDepth =
+      rBoost >= 12 || pathBoost + generalBoost > 0 || wantsRecent ? 28 : 14;
     if (m.historyBytes <= 0) continue;
     try {
       const path = join(opts.sessionsDir, `${m.sessionId}.jsonl`);
-      const entries = readHistory(path, 12);
-      for (const e of entries) {
+      const entries = readHistory(path, histDepth);
+      // Prefer newer entries: history is oldest→newest; weight later indices.
+      const n = entries.length;
+      for (let i = 0; i < n; i++) {
+        const e = entries[i]!;
         if (!e.text?.trim()) continue;
-        const s = scoreTokens(e.text, tokens);
-        if (s <= 0) continue;
+        // Skip meta dumps that pollute "last work" answers.
+        if (/MANAGER CONTEXT \(auto/i.test(e.text)) continue;
+        if (/^COMPLEXITY \(decide yourself/i.test(e.text)) continue;
+        if (/TELEGRAM BRIDGE \(how to work/i.test(e.text)) continue;
+
+        const textScore = scoreTokens(e.text, tokens);
+        if (textScore <= 0) continue;
+
+        // Prefer entry timestamp; fall back to session updatedAt (not 0/NaN).
+        const entryAt = normalizeEpochMs(e.timestamp) ?? sessionAt;
+        const entryRecency = recencyBoost(entryAt, now) * recencyMul;
+        // Position boost: last entries in the tail are newest.
+        const posBoost = n > 1 ? Math.round((i / (n - 1)) * 6) : 3;
+        // Prefer user prompts + assistant Done prose for "what was last done".
+        const roleBoost = e.role === "user" ? 3 : e.role === "assistant" ? 3 : 0;
+        const s =
+          textScore +
+          pathBoost +
+          generalBoost +
+          entryRecency +
+          posBoost +
+          roleBoost +
+          (newestBoost > 0 ? 4 : 0);
+        if (!Number.isFinite(s) || s <= 0) continue;
+        const eAge = formatAge(entryAt, now);
         hits.push({
           kind: "history",
           title: `${e.role} · ${(m.title || m.sessionId.slice(0, 8)).slice(0, 40)}`,
-          snippet: clamp(e.text.replace(/\s+/g, " ").trim(), 220),
+          snippet: clamp(
+            [eAge ? `[${eAge}]` : "", e.text.replace(/\s+/g, " ").trim()].filter(Boolean).join(" "),
+            240,
+          ),
           score: s,
           path: m.cwd || undefined,
           sessionId: m.sessionId,
+          at: entryAt,
         });
       }
     } catch {
@@ -135,7 +283,13 @@ export function searchGroupMemory(opts: GroupMemorySearchOpts): MemoryHit[] {
     }
   }
 
-  hits.sort((a, b) => b.score - a.score || a.kind.localeCompare(b.kind));
+  // Newest high scores first.
+  hits.sort(
+    (a, b) =>
+      b.score - a.score ||
+      (b.at ?? 0) - (a.at ?? 0) ||
+      a.kind.localeCompare(b.kind),
+  );
   // Dedupe near-identical snippets.
   const seen = new Set<string>();
   const out: MemoryHit[] = [];
@@ -157,3 +311,29 @@ function clamp(s: string, max: number): string {
 function escapeReg(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+
+function normPath(p: string | undefined): string {
+  if (!p) return "";
+  return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+
+/**
+ * Higher boost for earlier preferred paths.
+ * Index 0 is usually the workspace (General) — use **exact** match only so we
+ * do not treat every child project under Domains as "General memory".
+ * Later entries (project paths) allow prefix match.
+ */
+function pathPreferenceBoost(cwd: string | undefined, prefer: string[]): number {
+  if (!cwd || prefer.length === 0) return 0;
+  const n = cwd.replace(/\\/g, "/").toLowerCase();
+  for (let i = 0; i < prefer.length; i++) {
+    const p = prefer[i]!.replace(/\\/g, "/").toLowerCase();
+    if (!p) continue;
+    const exact = n === p;
+    const child = i > 0 && (n === p || n.startsWith(p + "/"));
+    if (exact || child) {
+      return 8 - Math.min(6, i * 2);
+    }
+  }
+  return 0;
+}

package/src/bot/handlers/forum.ts

@@ -5,7 +5,11 @@ import type { Bot } from "grammy";
 import { createLogger } from "../../logger.js";
 import type { ForumManager } from "../../forum/manager.js";
 import type { BotDeps } from "../deps.js";
-import { FORUM_GENERAL_THREAD_ID, forumThreadId } from "../../forum/thread.js";
+import {
+  FORUM_GENERAL_THREAD_ID,
+  forumThreadId,
+  outboundThreadExtra,
+} from "../../forum/thread.js";
 
 const log = createLogger("forum-handler");
 
@@ -89,8 +93,7 @@ export function registerForum(bot: Bot, deps: BotDeps, forum: ForumManager): voi
   // Optional: re-run setup command for admins in the group.
   bot.command("forum_setup", async (ctx) => {
     const threadId = ctx.message?.message_thread_id;
-    const replyOpts =
-      threadId !== undefined ? { message_thread_id: threadId } : {};
+    const replyOpts = outboundThreadExtra(threadId);
     if (ctx.chat?.id !== groupId) {
       await ctx.reply("Use this command inside the configured forum group.", replyOpts).catch(() => {});
       return;
@@ -167,7 +170,11 @@ export async function resolveForumRuntime(
         .sendMessage(
           chatId,
           `\u2705 Bound to project:\n\`${result.binding.projectPath}\`${iconNote}\n\nYou can chat here now.`,
-          { message_thread_id: tid, parse_mode: "Markdown", reply_parameters: { message_id: messageId } },
+          {
+            ...outboundThreadExtra(tid),
+            parse_mode: "Markdown",
+            reply_parameters: { message_id: messageId },
+          },
         )
         .catch(() => {});
       // Warm runtime; path-only message is not submitted as an agent prompt.
@@ -181,7 +188,10 @@ export async function resolveForumRuntime(
       .sendMessage(
         chatId,
         `\u2753 ${result.error}\n\n${BIND_HINT.replace(/\*\*/g, "")}`,
-        { message_thread_id: tid, reply_parameters: { message_id: messageId } },
+        {
+          ...outboundThreadExtra(tid),
+          reply_parameters: { message_id: messageId },
+        },
       )
       .catch(() => {});
     return "handled";
@@ -194,7 +204,7 @@ export async function resolveForumRuntime(
       .sendMessage(
         chatId,
         `\u2753 This topic is not linked to a project yet.\n${BIND_HINT.replace(/\*\*/g, "")}`,
-        { message_thread_id: tid },
+        outboundThreadExtra(tid),
       )
       .catch(() => {});
     return "handled";

package/src/bot/handlers/grok-slash.ts

@@ -0,0 +1,336 @@
+/**
+ * Forward Grok Build slash commands (e.g. /goal, /plan, /compact) into the
+ * active ACP session. Grok shell builtins are parsed from the prompt text by
+ * slash_exec — they never reached the agent before because the Telegram message
+ * handler treated unknown "/…" lines as typos.
+ *
+ * Bot-local commands (projects, sessions, reauth, …) stay reserved and are
+ * handled by their own `bot.command` registrations. Name collisions use
+ * non-colliding Telegram aliases that still send the correct Grok slash line.
+ */
+import type { Bot, Context } from "grammy";
+import { textPrompt } from "../../app/types.js";
+import { createLogger } from "../../logger.js";
+import { isGeneralThread } from "../../forum/thread.js";
+import type { BotDeps } from "../deps.js";
+import { extractReplyContext } from "../reply-context.js";
+import { resolveScope } from "../scope.js";
+
+const log = createLogger("grok-slash");
+
+/**
+ * Telegram command names reserved by this bot (without leading slash).
+ * Must stay in sync with bot.command registrations / COMMANDS menu.
+ * Bare names in this set are NEVER stolen for Grok — use collision aliases.
+ */
+export const BOT_RESERVED_COMMANDS = new Set(
+  [
+    "start",
+    "menu",
+    "help",
+    "projects",
+    "project",
+    "sessions",
+    "active",
+    "running",
+    "killall",
+    "mcp",
+    "tasks",
+    "newtask",
+    "history",
+    "new",
+    "status",
+    "usage",
+    "btw",
+    "flush",
+    "queue",
+    "clearqueue",
+    "cancel",
+    "stop",
+    "unwatch",
+    "model",
+    "restart",
+    "sandbox",
+    "reauth",
+    "accounts",
+    "import",
+    "forum_setup",
+  ].map((c) => c.toLowerCase()),
+);
+
+/**
+ * Telegram command name (no slash, lowercase) → Grok shell command name (no slash).
+ * Covers hyphenated multi-word forms, documented Grok aliases, and collision aliases
+ * for bot-reserved bare names that still have distinct Grok builtins.
+ */
+export const GROK_SLASH_ALIASES: Readonly<Record<string, string>> = {
+  // Multi-word (Telegram underscore ↔ Grok hyphen)
+  view_plan: "view-plan",
+  show_plan: "view-plan",
+  plan_view: "view-plan",
+  deep_research: "deep-research",
+  always_approve: "always-approve",
+  session_info: "session-info",
+  imagine_video: "imagine-video",
+  config_agents: "config-agents",
+  release_notes: "release-notes",
+  import_claude: "import-claude",
+  compact_mode: "compact-mode",
+  vim_mode: "vim-mode",
+  agents_dashboard: "dashboard",
+  // No-underscore convenience forms
+  viewplan: "view-plan",
+  showplan: "view-plan",
+  planview: "view-plan",
+  deepresearch: "deep-research",
+  alwaysapprove: "always-approve",
+  sessioninfo: "session-info",
+  imaginevideo: "imagine-video",
+  configagents: "config-agents",
+  releasenotes: "release-notes",
+  importclaude: "import-claude",
+  // Documented Grok aliases
+  clear: "new",
+  undo: "rewind",
+  title: "rename",
+  m: "model",
+  mem: "memory",
+  cost: "usage",
+  agents: "config-agents",
+  howto: "docs",
+  guides: "docs",
+  changelog: "release-notes",
+  ml: "multiline",
+  t: "theme",
+  full: "fullscreen",
+  tour: "tutorial",
+  onboarding: "tutorial",
+  welcome: "home",
+  exit: "quit",
+  prefs: "settings",
+  preferences: "settings",
+  config: "settings",
+  terminal_setup: "doctor",
+  terminal_check: "doctor",
+  terminal_info: "doctor",
+  terminalsetup: "doctor",
+  terminalcheck: "doctor",
+  terminalinfo: "doctor",
+  // Bot name collisions → still send the Grok builtin
+  grok_new: "new",
+  session_new: "new",
+  grok_clear: "new",
+  memory_flush: "flush",
+  grok_flush: "flush",
+  grok_usage: "usage",
+  grok_cost: "usage",
+  grok_btw: "btw",
+  // session-info aliases when bare status/info are bot-reserved
+  grok_status: "session-info",
+  grok_info: "session-info",
+};
+
+/**
+ * Official shell builtins that are meaningful over ACP (not pure TUI/pager).
+ * Used for tests / inventory; menu may advertise a subset + collision aliases.
+ */
+export const GROK_SHELL_ACP_COMMANDS: readonly string[] = [
+  "new",
+  "compact",
+  "context",
+  "session-info",
+  "fork",
+  "rewind",
+  "copy",
+  "export",
+  "delete",
+  "rename",
+  "model",
+  "effort",
+  "always-approve",
+  "auto",
+  "plan",
+  "view-plan",
+  "memory",
+  "flush",
+  "dream",
+  "remember",
+  "hooks",
+  "plugins",
+  "marketplace",
+  "skills",
+  "imagine",
+  "imagine-video",
+  "loop",
+  "goal",
+  "deep-research",
+  "workflow",
+  "workflows",
+  "feedback",
+  "btw",
+  "mcps",
+  "doctor",
+  "release-notes",
+  "docs",
+  "import-claude",
+  "config-agents",
+  "personas",
+  "login",
+  "logout",
+  "usage",
+  "privacy",
+  "settings",
+];
+
+/** Grok Build slash commands we advertise in the Telegram menu (Telegram-safe names). */
+export const GROK_FORWARDED_COMMANDS: { command: string; description: string; grok: string }[] = [
+  // Session
+  { command: "compact", description: "Grok /compact — compress context", grok: "compact" },
+  { command: "context", description: "Grok /context — context window usage", grok: "context" },
+  { command: "session_info", description: "Grok /session-info", grok: "session-info" },
+  { command: "fork", description: "Grok /fork — branch session", grok: "fork" },
+  { command: "rewind", description: "Grok /rewind — undo last turns", grok: "rewind" },
+  { command: "copy", description: "Grok /copy — copy last response", grok: "copy" },
+  { command: "export", description: "Grok /export — export conversation", grok: "export" },
+  { command: "delete", description: "Grok /delete — delete session history", grok: "delete" },
+  { command: "rename", description: "Grok /rename <title>", grok: "rename" },
+  { command: "grok_new", description: "Grok /new — fresh session (CLI)", grok: "new" },
+  // Model / mode
+  { command: "effort", description: "Grok /effort low|medium|high|xhigh", grok: "effort" },
+  { command: "always_approve", description: "Grok /always-approve toggle", grok: "always-approve" },
+  { command: "auto", description: "Grok /auto — auto permission mode", grok: "auto" },
+  { command: "plan", description: "Grok /plan — enter plan mode", grok: "plan" },
+  { command: "view_plan", description: "Grok /view-plan — show saved plan", grok: "view-plan" },
+  // Memory
+  { command: "memory", description: "Grok /memory — browse memories", grok: "memory" },
+  { command: "memory_flush", description: "Grok /flush — save session to memory", grok: "flush" },
+  { command: "dream", description: "Grok /dream — consolidate memory", grok: "dream" },
+  { command: "remember", description: "Grok /remember <note>", grok: "remember" },
+  // Extensions
+  { command: "hooks", description: "Grok /hooks — hooks panel", grok: "hooks" },
+  { command: "plugins", description: "Grok /plugins — plugins panel", grok: "plugins" },
+  { command: "marketplace", description: "Grok /marketplace — plugin marketplace", grok: "marketplace" },
+  { command: "skills", description: "Grok /skills — skills panel", grok: "skills" },
+  // Media
+  { command: "imagine", description: "Grok /imagine <description>", grok: "imagine" },
+  { command: "imagine_video", description: "Grok /imagine-video <description>", grok: "imagine-video" },
+  // Scheduling / workflows / goals
+  { command: "loop", description: "Grok /loop [interval] <prompt>", grok: "loop" },
+  { command: "goal", description: "Grok /goal — set/status/pause/resume/clear", grok: "goal" },
+  { command: "deep_research", description: "Grok /deep-research <query>", grok: "deep-research" },
+  { command: "workflow", description: "Grok /workflow — run/manage workflow", grok: "workflow" },
+  { command: "workflows", description: "Grok /workflows — workflow dashboard", grok: "workflows" },
+  // Other
+  { command: "feedback", description: "Grok /feedback [message]", grok: "feedback" },
+  { command: "grok_btw", description: "Grok /btw — aside without interrupting", grok: "btw" },
+  { command: "mcps", description: "Grok /mcps — MCP servers modal", grok: "mcps" },
+  { command: "doctor", description: "Grok /doctor — session diagnostics", grok: "doctor" },
+  { command: "release_notes", description: "Grok /release-notes", grok: "release-notes" },
+  { command: "docs", description: "Grok /docs — how-to guides", grok: "docs" },
+  { command: "import_claude", description: "Grok /import-claude", grok: "import-claude" },
+  { command: "config_agents", description: "Grok /config-agents — agent defs", grok: "config-agents" },
+  { command: "personas", description: "Grok /personas — manage personas", grok: "personas" },
+  { command: "login", description: "Grok /login — re-auth in session", grok: "login" },
+  { command: "logout", description: "Grok /logout", grok: "logout" },
+  { command: "grok_usage", description: "Grok /usage — credit/billing", grok: "usage" },
+  { command: "privacy", description: "Grok /privacy — data/retention", grok: "privacy" },
+  { command: "settings", description: "Grok /settings — config modal", grok: "settings" },
+];
+
+/** Resolve a Telegram command token (no slash) to a Grok shell command name. */
+export function resolveGrokCommandName(telegramName: string): string {
+  const name = telegramName.toLowerCase();
+  const fromAlias = GROK_SLASH_ALIASES[name];
+  if (fromAlias) return fromAlias;
+  const fromMenu = GROK_FORWARDED_COMMANDS.find((c) => c.command === name);
+  if (fromMenu) return fromMenu.grok;
+  // underscore → hyphen for multi-word Grok commands (deep_research → deep-research)
+  return name.replace(/_/g, "-");
+}
+
+/** True when a bare slash line should be forwarded to Grok (not a bot command). */
+export function shouldForwardSlashToGrok(text: string): boolean {
+  const t = text.trim();
+  if (!t.startsWith("/") || t.includes("\n")) return false;
+  // /cmd@botname args
+  const m = t.match(/^\/([A-Za-z0-9_]+)(?:@\w+)?(?:\s|$)/);
+  if (!m) return false;
+  const name = m[1]!.toLowerCase();
+  if (BOT_RESERVED_COMMANDS.has(name)) return false;
+  return true;
+}
+
+/** Normalize Telegram `/view_plan foo` → Grok `/view-plan foo`. */
+export function toGrokSlashLine(text: string): string {
+  const t = text.trim();
+  const m = t.match(/^\/([A-Za-z0-9_]+)(@\w+)?([\s\S]*)$/);
+  if (!m) return t;
+  const rest = m[3] ?? "";
+  const name = resolveGrokCommandName(m[1]!);
+  return `/${name}${rest}`;
+}
+
+export async function submitGrokSlash(ctx: Context, deps: BotDeps, line: string): Promise<void> {
+  if (!ctx.chat) return;
+  const grokLine = toGrokSlashLine(line);
+  const scope = resolveScope(ctx, deps);
+  const extra: Record<string, unknown> = { parse_mode: "Markdown", ...scope.threadExtra };
+  if (scope.isForum && isGeneralThread(scope.threadId) && /^\/goal(?:\s|$)/i.test(grokLine)) {
+    await ctx.reply(
+      "Use /goal in a **project topic** or **AI Chat**, not in General \\(manager\\).",
+      extra,
+    );
+    return;
+  }
+  const rt = scope.rt;
+  try {
+    // Prefer dedicated ACP command RPC when the agent supports it; fall back to
+    // session/prompt (Grok slash_exec parses leading / in the prompt).
+    if (rt.sessionId) {
+      try {
+        await deps.acp.executeCommand(rt.sessionId, grokLine);
+        await ctx.reply(`\u25B6\uFE0F Sent to Grok: \`${grokLine}\``, extra);
+        return;
+      } catch (err) {
+        log.debug(
+          `executeCommand failed for ${grokLine}: ${(err as Error).message}; falling back to prompt`,
+        );
+      }
+    }
+    const outcome = await rt.submit(
+      textPrompt(grokLine, ctx.message?.message_id, extractReplyContext(ctx), {
+        skipSelfRecheck: true,
+        rawSlashCommand: true,
+      }),
+    );
+    if (outcome === "queued") {
+      await ctx.reply(
+        `\u{1F4E5} Queued (position ${rt.queueLength}): \`${grokLine}\` \u2014 runs after the current turn.`,
+        extra,
+      );
+    } else {
+      await ctx.reply(`\u25B6\uFE0F Running \`${grokLine}\`\u2026`, extra);
+    }
+  } catch (err) {
+    log.warn(`grok slash failed: ${(err as Error).message}`);
+    await ctx.reply(`\u274C Could not run \`${grokLine}\`: ${(err as Error).message}`, extra);
+  }
+}
+
+export function registerGrokSlash(bot: Bot, deps: BotDeps): void {
+  // Explicit Telegram commands for advertised Grok builtins (appear in menu).
+  for (const def of GROK_FORWARDED_COMMANDS) {
+    if (BOT_RESERVED_COMMANDS.has(def.command)) continue;
+    bot.command(def.command, async (ctx) => {
+      const args = (ctx.match || "").toString();
+      const line = args ? `/${def.command} ${args}` : `/${def.command}`;
+      await submitGrokSlash(ctx, deps, line);
+    });
+  }
+  // Catch-all for other Grok / skills slashes not in the menu.
+  bot.on("message:text", async (ctx, next) => {
+    const text = ctx.message?.text ?? "";
+    if (!shouldForwardSlashToGrok(text)) return next();
+    await submitGrokSlash(ctx, deps, text);
+  });
+}