grok-telegram-bot 2.4.0 → 2.5.0

package/src/render/telegram-bridge.ts

@@ -0,0 +1,360 @@
+/**
+ * Telegram bridge protocol: first-prompt directive + parse/strip of agent
+ * JSON action blocks (`{"telegram":[...]}`) from assistant responses.
+ *
+ * Keep TELEGRAM_BRIDGE_DIRECTIVE tidy-idempotent (no trailing spaces / 3+ blank
+ * lines, no digit `{progress:…}` tokens) so history cleaners can strip by
+ * exact match after extractProgress/tidy.
+ */
+import type { PromptInput } from "../app/types.js";
+
+/** Marker prefix for first-prompt teaching block (used by strip / history). */
+export const TELEGRAM_BRIDGE_MARKER = "TELEGRAM BRIDGE (how to work in this chat):";
+
+/** Marker for results injected back into the agent after actions run. */
+export const TELEGRAM_BRIDGE_RESULTS_MARKER =
+  "TELEGRAM BRIDGE RESULTS (system — use these facts; do not re-emit the same request unless needed):";
+
+/** Max actions accepted from one agent turn (create + path + several prompts). */
+export const TELEGRAM_ACTION_MAX = 9;
+/** Max bot_command actions per turn. */
+export const TELEGRAM_BOT_COMMAND_MAX = 2;
+/** Max send_prompt actions per turn (cross-topic work). */
+export const TELEGRAM_SEND_PROMPT_MAX = 5;
+
+export type TelegramAction =
+  | { action: "create_topic"; name: string; path?: string }
+  | { action: "set_path"; topic: string; path: string }
+  | { action: "send_prompt"; topic: string; prompt: string; newSession?: boolean }
+  | { action: "search_memory"; query: string; limit?: number }
+  | { action: "list_bots" }
+  | { action: "bot_command"; bot: string; command: string; args?: string };
+
+export interface TelegramActionExtract {
+  actions: TelegramAction[];
+  /** Text with telegram action fences removed. */
+  cleaned: string;
+}
+
+/**
+ * Static teaching block. Dynamic capability lines are appended by
+ * {@link buildTelegramBridgeDirective}.
+ */
+export const TELEGRAM_BRIDGE_DIRECTIVE_BASE = [
+  TELEGRAM_BRIDGE_MARKER,
+  "You are driven by the Grok Telegram Bot bridge over ACP. Beyond normal coding tools you may request Telegram-side actions by putting a fenced JSON block in your response (language json preferred), BEFORE the final progress marker line.",
+  "",
+  "Format (one block; multiple actions allowed, run in order — up to 9):",
+  "```json",
+  '{ "telegram": [',
+  '  { "action": "create_topic", "name": "Topic title", "path": "optional absolute project path or exact catalog name" },',
+  '  { "action": "set_path", "topic": "Topic title or #threadId", "path": "absolute path or exact catalog name" },',
+  '  { "action": "send_prompt", "topic": "Topic title or #threadId", "prompt": "work for that topic", "new_session": false },',
+  '  { "action": "search_memory", "query": "keywords about past work", "limit": 8 },',
+  '  { "action": "list_bots" },',
+  '  { "action": "bot_command", "bot": "username_without_at", "command": "status", "args": "optional" }',
+  "] }",
+  "```",
+  "",
+  "Actions:",
+  "- create_topic — new forum topic; optional path binds the project immediately.",
+  "  Absolute paths that do not exist yet are created on disk (new project flow).",
+  "- set_path — bind/rebind an existing topic to a project path (absolute dir or exact catalog name).",
+  "  Absolute paths that do not exist yet are created on disk.",
+  "- send_prompt — start or queue a prompt in another topic's session (does not wait for that turn to finish).",
+  "  From General/AI Chat (GROK_WORKSPACE) you can create a project topic, set_path, then send_prompt with multi-step work.",
+  "  topic = exact topic title, #threadId, \"general\", or \"ai chat\". Optional new_session=true starts a fresh session there.",
+  "- search_memory — search indexed forum topics + session titles/comments/history.",
+  "- list_bots — list allowlisted sibling Telegram bots and command catalogs.",
+  "- bot_command — /command@bot; waits for that bot to settle. NOT a Done; timeouts return ok=false.",
+  "",
+  "Example (from General): create project topic + path + kick off work there:",
+  '```json',
+  '{ "telegram": [',
+  '  { "action": "create_topic", "name": "MyApp", "path": "H:\\\\Projects\\\\MyApp" },',
+  '  { "action": "send_prompt", "topic": "MyApp", "prompt": "1) scaffold\\n2) tests\\n3) README" }',
+  "] }",
+  "```",
+  "",
+  "After you emit these actions, the bridge runs them and may send TELEGRAM BRIDGE RESULTS. Use those facts; do not invent replies.",
+  "The bridge strips the JSON fence from the user-visible message. Prefer plain prose for the user; put protocol only in the fence.",
+  "Do not spam actions. Prefer one orchestration block per turn.",
+].join("\n");
+
+export interface TelegramBridgeCaps {
+  forumReady: boolean;
+  topicGroupId?: number;
+  allowedBots: string[];
+  /** username → command list for first-prompt teaching */
+  botCommands?: Record<string, Array<{ command: string; description?: string }>>;
+}
+
+/** Full first-prompt directive including live capabilities. */
+export function buildTelegramBridgeDirective(caps: TelegramBridgeCaps): string {
+  const lines = [TELEGRAM_BRIDGE_DIRECTIVE_BASE, "", "Capabilities right now:"];
+  if (caps.forumReady && caps.topicGroupId !== undefined) {
+    lines.push(
+      `- Forum topics: READY (group ${caps.topicGroupId}). You may create_topic, set_path, and send_prompt.`,
+      `- General / AI Chat sessions use GROK_WORKSPACE; other topics use their bound project path.`,
+    );
+  } else if (caps.topicGroupId !== undefined) {
+    lines.push(
+      `- Forum topics: NOT READY (group ${caps.topicGroupId} configured but setup failed or bot is not admin). Do not rely on create_topic / set_path / send_prompt.`,
+    );
+  } else {
+    lines.push("- Forum topics: OFF (TOPIC_GROUP_ID unset). create_topic / set_path / send_prompt will fail.");
+  }
+  if (caps.allowedBots.length > 0) {
+    lines.push(
+      `- Sibling bots (allowlist): ${caps.allowedBots.map((b) => "@" + b).join(", ")}. Use list_bots / bot_command like MCP.`,
+    );
+    for (const u of caps.allowedBots) {
+      const cmds = caps.botCommands?.[u];
+      if (cmds && cmds.length > 0) {
+        lines.push(
+          `  - @${u}: ${cmds
+            .map((c) => (c.description ? `/${c.command} (${c.description})` : `/${c.command}`))
+            .join(", ")}`,
+        );
+      }
+    }
+  } else {
+    lines.push(
+      "- Sibling bots: none configured (ALLOWED_TELEGRAM_BOTS empty). list_bots returns empty; bot_command disabled.",
+    );
+  }
+  lines.push("- search_memory: always available against bot-owned session/topic indexes.");
+  return lines.join("\n");
+}
+
+/**
+ * Prepend the telegram bridge teaching block (idempotent if already present).
+ * Call after complexity wrapping so it sits between complexity and user task body.
+ */
+export function wrapTelegramBridgePrompt(input: PromptInput, directive: string): PromptInput {
+  const body = input.text.trim() || "(see attached media / files)";
+  if (body.includes(TELEGRAM_BRIDGE_MARKER)) return input;
+  // Prefer inserting after "User task:\n" when complexity wrapper is present.
+  const marker = "User task:";
+  const idx = body.indexOf(marker);
+  if (idx !== -1) {
+    const before = body.slice(0, idx + marker.length);
+    const after = body.slice(idx + marker.length);
+    return {
+      ...input,
+      text: `${before}\n\n${directive}\n\nUser task (continued):\n${after.trimStart()}`,
+    };
+  }
+  return {
+    ...input,
+    text: `${directive}\n\n${body}`,
+  };
+}
+
+/** True when text is the bridge results follow-up (meta; skip recheck). */
+export function isTelegramBridgeResultsPrompt(text: string): boolean {
+  return text.trimStart().startsWith(TELEGRAM_BRIDGE_RESULTS_MARKER);
+}
+
+/** Build the meta prompt that feeds action results back to the agent. */
+export function buildTelegramBridgeResultsPrompt(results: unknown[]): string {
+  const payload = JSON.stringify({ results }, null, 2);
+  return [
+    TELEGRAM_BRIDGE_RESULTS_MARKER,
+    "```json",
+    payload,
+    "```",
+    "Continue the user's task with this information. Do not ask the user to paste results. Do not re-emit the same telegram actions unless something failed and a retry is useful.",
+  ].join("\n");
+}
+
+/**
+ * Extract telegram actions from fenced JSON blocks and strip those fences from
+ * the visible text. Non-telegram fences are left intact.
+ */
+export function extractTelegramActions(text: string): TelegramActionExtract {
+  if (!text) return { actions: [], cleaned: text };
+  const actions: TelegramAction[] = [];
+  // Match complete fenced blocks (``` or ```json etc.).
+  const fenceRe = /```(?:json|JSON)?\s*\r?\n([\s\S]*?)```/g;
+  let cleaned = text.replace(fenceRe, (full, body: string) => {
+    const parsed = tryParseTelegramFence(body);
+    if (!parsed) return full;
+    for (const a of parsed) {
+      if (actions.length >= TELEGRAM_ACTION_MAX) break;
+      actions.push(a);
+    }
+    return "";
+  });
+  // Hide a trailing incomplete ```json … telegram block mid-stream.
+  cleaned = cleaned.replace(/```(?:json|JSON)?\s*\r?\n[\s\S]*$/i, (tail) => {
+    if (
+      /"telegram"\s*:/i.test(tail) ||
+      /"action"\s*:\s*"(?:create_topic|set_path|send_prompt|search_memory|list_bots|bot_command)"/i.test(
+        tail,
+      )
+    ) {
+      return "";
+    }
+    return tail;
+  });
+  cleaned = tidy(cleaned);
+  return { actions: capBotCommands(actions), cleaned };
+}
+
+/** Strip only (no need for actions) — streamer path. */
+export function stripTelegramActionFences(text: string): string {
+  return extractTelegramActions(text).cleaned;
+}
+
+function tryParseTelegramFence(body: string): TelegramAction[] | undefined {
+  const raw = body.trim();
+  if (!raw) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  const list = coerceActionList(parsed);
+  if (!list) return undefined;
+  const out: TelegramAction[] = [];
+  for (const item of list) {
+    const a = normalizeAction(item);
+    if (a) out.push(a);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+function coerceActionList(parsed: unknown): unknown[] | undefined {
+  if (Array.isArray(parsed)) {
+    if (parsed.length === 0) return undefined;
+    // Bare array only if every element looks like an action.
+    if (parsed.every((x) => x && typeof x === "object" && "action" in (x as object))) {
+      return parsed;
+    }
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object") return undefined;
+  const rec = parsed as Record<string, unknown>;
+  if ("telegram" in rec) {
+    const t = rec.telegram;
+    if (Array.isArray(t)) return t;
+    if (t && typeof t === "object") return [t];
+    return undefined;
+  }
+  // Single action object at top level.
+  if (typeof rec.action === "string") return [rec];
+  return undefined;
+}
+
+function normalizeAction(item: unknown): TelegramAction | undefined {
+  if (!item || typeof item !== "object") return undefined;
+  const rec = item as Record<string, unknown>;
+  const action = String(rec.action ?? rec.type ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/-/g, "_");
+
+  switch (action) {
+    case "create_topic": {
+      const name = String(rec.name ?? rec.title ?? "").trim();
+      if (!name) return undefined;
+      const path = String(rec.path ?? rec.project_path ?? rec.projectPath ?? "").trim();
+      return path
+        ? { action: "create_topic", name: name.slice(0, 128), path: path.slice(0, 500) }
+        : { action: "create_topic", name: name.slice(0, 128) };
+    }
+    case "set_path":
+    case "bind_path":
+    case "bind_topic": {
+      const topic = String(rec.topic ?? rec.name ?? rec.thread ?? rec.thread_id ?? rec.threadId ?? "").trim();
+      const path = String(rec.path ?? rec.project_path ?? rec.projectPath ?? "").trim();
+      if (!topic || !path) return undefined;
+      return {
+        action: "set_path",
+        topic: topic.slice(0, 128),
+        path: path.slice(0, 500),
+      };
+    }
+    case "send_prompt":
+    case "topic_prompt":
+    case "prompt_topic": {
+      const topic = String(rec.topic ?? rec.name ?? rec.thread ?? rec.thread_id ?? rec.threadId ?? "").trim();
+      const prompt = String(rec.prompt ?? rec.text ?? rec.message ?? "").trim();
+      if (!topic || !prompt) return undefined;
+      const newSessionRaw = rec.new_session ?? rec.newSession ?? rec.fresh;
+      const newSession =
+        newSessionRaw === true ||
+        newSessionRaw === 1 ||
+        /^(1|true|yes|y)$/i.test(String(newSessionRaw ?? "").trim());
+      return {
+        action: "send_prompt",
+        topic: topic.slice(0, 128),
+        prompt: prompt.slice(0, 4000),
+        newSession: newSession || undefined,
+      };
+    }
+    case "search_memory":
+    case "search":
+    case "memory_search": {
+      const query = String(rec.query ?? rec.q ?? rec.text ?? "").trim();
+      if (!query) return undefined;
+      let limit = Number(rec.limit ?? rec.max ?? 8);
+      if (!Number.isFinite(limit)) limit = 8;
+      limit = Math.max(1, Math.min(20, Math.round(limit)));
+      return { action: "search_memory", query: query.slice(0, 300), limit };
+    }
+    case "list_bots":
+    case "bots":
+      return { action: "list_bots" };
+    case "bot_command":
+    case "call_bot":
+    case "invoke_bot": {
+      const bot = normalizeUsername(String(rec.bot ?? rec.username ?? ""));
+      const command = String(rec.command ?? rec.cmd ?? "")
+        .trim()
+        .replace(/^\//, "");
+      if (!bot || !command) return undefined;
+      const args = String(rec.args ?? rec.arguments ?? rec.text ?? "").trim();
+      return {
+        action: "bot_command",
+        bot,
+        command: command.slice(0, 64),
+        args: args ? args.slice(0, 500) : undefined,
+      };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function capBotCommands(actions: TelegramAction[]): TelegramAction[] {
+  let botCmds = 0;
+  let sendPrompts = 0;
+  const out: TelegramAction[] = [];
+  for (const a of actions) {
+    if (a.action === "bot_command") {
+      if (botCmds >= TELEGRAM_BOT_COMMAND_MAX) continue;
+      botCmds++;
+    }
+    if (a.action === "send_prompt") {
+      if (sendPrompts >= TELEGRAM_SEND_PROMPT_MAX) continue;
+      sendPrompts++;
+    }
+    out.push(a);
+    if (out.length >= TELEGRAM_ACTION_MAX) break;
+  }
+  return out;
+}
+
+export function normalizeUsername(raw: string): string {
+  return raw.trim().replace(/^@/, "").toLowerCase();
+}
+
+function tidy(s: string): string {
+  return s
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/\s+$/g, "");
+}

package/src/render/tool-call.ts

@@ -159,7 +159,24 @@ function formatByKind(
   }
 }
 
-// ---- helpers for code fences ----
+// ---- helpers for code fences / path labels ----
+
+/**
+ * File paths in **bold** break Telegram MarkdownV2 (Windows `\`, dots, long
+ * session paths). Always put paths in inline code; keep only the verb bold.
+ *   ✏️ **Edit** `C:\Users\…\plan.md`
+ */
+function pathCode(path: string | undefined | null, fallback = "file"): string {
+  const p = (path || "").trim() || fallback;
+  // Inline code cannot contain raw backticks unescaped in our MD pipeline;
+  // replace rare ` in paths so the span stays closed.
+  return "`" + p.replace(/`/g, "'") + "`";
+}
+
+/** `**Edit** \`path\`` style header fragment (no leading emoji). */
+function boldVerbPath(verb: string, path: string | undefined | null, fallback = "file"): string {
+  return "**" + verb + "** " + pathCode(path, fallback);
+}
 
 /** Fence that lengthens itself when the body contains backticks (avoids MD break). */
 function fence(text: string, lang?: string): string {
@@ -197,8 +214,8 @@ function formatExecute(
 ): string {
   const cmd = extractCommand(raw);
   const cwd = strOf(raw.cwd) || strOf(raw.working_directory) || strOf(raw.workingDirectory);
-  const title = "Run command" + (cwd ? " in " + truncate(cwd, 80) : "");
-  let out = "\u{1F4BB} **" + title + "**" + tail;
+  let out = "\u{1F4BB} **Run command**" + tail;
+  if (cwd) out += " in " + pathCode(truncate(cwd, 80));
   if (toolName && toolName !== "execute" && toolName !== "shell" && toolName !== "bash") {
     out += `\n  tool: \`${toolName}\``;
   }
@@ -226,8 +243,7 @@ function formatEdit(
   toolName: string,
 ): string {
   const path = extractPath(raw);
-  const title = "Edit " + (path || "file");
-  let out = "\u270F\uFE0F **" + title + "**" + tail;
+  let out = "\u270F\uFE0F " + boldVerbPath("Edit", path) + tail;
   if (toolName && !/edit|replace/i.test(toolName)) out += `\n  tool: \`${toolName}\``;
   if (opts.showDiffs) {
     const diff = buildEditDiff(u, raw, opts.diffMaxLines);
@@ -242,7 +258,7 @@ function formatEdit(
 function formatWrite(u: SessionUpdate, kind: string, raw: Record<string, unknown>, tail: string): string {
   const path = extractPath(raw);
   const verb = kind === "create" ? "Create" : "Write";
-  let out = "\u{1F4DD} **" + verb + " " + (path || "file") + "**" + tail;
+  let out = "\u{1F4DD} " + boldVerbPath(verb, path) + tail;
   const content = extractContent(raw) || extractToolOutput(u);
   if (content) {
     out += "\n" + fence(truncateMiddleLines(content, OUTPUT_PREVIEW_LINES, CONTENT_PREVIEW_MAX), detectLang(path)) + "\n";
@@ -258,14 +274,13 @@ function formatRead(
 ): string {
   const path = extractPath(raw, u);
   const range = extractReadRange(raw);
-  let title = "Read " + (path || "file");
   const parts: string[] = [];
   if (range.startLine) parts.push("line " + range.startLine);
   if (range.offset) parts.push("offset " + range.offset);
   if (range.limit) parts.push("limit " + range.limit);
   if (range.pages) parts.push("pages " + range.pages);
-  if (parts.length) title += " (" + parts.join(", ") + ")";
-  let out = "\u{1F4D6} **" + title + "**" + tail;
+  let out = "\u{1F4D6} " + boldVerbPath("Read", path) + tail;
+  if (parts.length) out += " (" + parts.join(", ") + ")";
   if (toolName && toolName !== "read" && toolName !== "read_file") {
     out += `\n  tool: \`${toolName}\``;
   }
@@ -292,11 +307,11 @@ function formatList(
     strOf(raw.target_directory) ||
     strOf(raw.targetDirectory) ||
     ".";
-  let out = "\u{1F4C1} **List " + truncate(path, 120) + "**" + tail;
+  let out = "\u{1F4C1} " + boldVerbPath("List", truncate(path, 120), ".") + tail;
   if (toolName) out += `\n  tool: \`${toolName}\``;
   const filters = extractFilters(raw);
-  if (filters.include) out += "\n  include: " + filters.include;
-  if (filters.exclude) out += "\n  exclude: " + filters.exclude;
+  if (filters.include) out += "\n  include: `" + filters.include.replace(/`/g, "'") + "`";
+  if (filters.exclude) out += "\n  exclude: `" + filters.exclude.replace(/`/g, "'") + "`";
   const body = extractToolOutput(u);
   if (body) {
     out += "\n" + fence(truncateMiddleLines(body, OUTPUT_PREVIEW_LINES, OUTPUT_PREVIEW_MAX)) + "\n";
@@ -314,16 +329,16 @@ function formatSearch(
   const path = extractSearchPath(raw);
   const filters = extractFilters(raw);
   const isGlob = /glob/i.test(toolName) || (!!filters.include && !query);
-  let title = isGlob ? "Glob" : "Search";
-  if (query) title += ": " + truncate(query, 120);
-  else if (path) title += " " + path;
-  let out = "\u{1F50E} **" + title + "**" + tail;
+  const verb = isGlob ? "Glob" : "Search";
+  let out = "\u{1F50E} **" + verb + "**" + tail;
+  if (query) out += " " + pathCode(truncate(query, 120), "query");
+  else if (path) out += " " + pathCode(truncate(path, 120));
   if (toolName && toolName !== "search" && toolName !== "grep") {
     out += `\n  tool: \`${toolName}\``;
   }
-  if (path && !(query && query.includes(path))) out += "\n  \u{1F4C2} in: " + truncate(path, 100);
-  if (filters.include) out += "\n  \u{1F4C1} include: " + filters.include;
-  if (filters.exclude) out += "\n  \u{1F6AB} exclude: " + filters.exclude;
+  if (path && query) out += "\n  \u{1F4C2} in: " + pathCode(truncate(path, 100));
+  if (filters.include) out += "\n  \u{1F4C1} include: " + pathCode(filters.include);
+  if (filters.exclude) out += "\n  \u{1F6AB} exclude: " + pathCode(filters.exclude);
   if (raw.case_sensitive !== undefined) {
     out += "\n  case-sensitive: " + (raw.case_sensitive ? "yes" : "no");
   }
@@ -338,7 +353,7 @@ function formatSearch(
 
 function formatDelete(raw: Record<string, unknown>, tail: string): string {
   const path = extractPath(raw);
-  return "\u{1F5D1}\uFE0F **Delete " + (path || "file") + "**" + tail;
+  return "\u{1F5D1}\uFE0F " + boldVerbPath("Delete", path) + tail;
 }
 
 function formatMove(kind: string, raw: Record<string, unknown>, tail: string): string {
@@ -352,20 +367,20 @@ function formatMove(kind: string, raw: Record<string, unknown>, tail: string): s
       "**" +
       tail +
       "\n  \u{1F4C4} " +
-      truncate(src, 100) +
+      pathCode(truncate(src, 100)) +
       "\n  \u27A1\uFE0F " +
-      truncate(dst, 100)
+      pathCode(truncate(dst, 100))
     );
   }
-  return "\u{1F4E6} **" + verb + " " + (src || dst || "file") + "**" + tail;
+  return "\u{1F4E6} " + boldVerbPath(verb, src || dst) + tail;
 }
 
 function formatFetch(u: SessionUpdate, raw: Record<string, unknown>, tail: string): string {
   const url = extractUrl(raw);
   const method = strOf(raw.method) || strOf(raw.verb) || "GET";
-  let title = "Fetch URL";
-  if (url) title = "Fetch " + truncate(url, 200);
-  let out = "\u{1F310} **" + title + "**" + tail;
+  let out = url
+    ? "\u{1F310} **Fetch** " + pathCode(truncate(url, 200), "URL") + tail
+    : "\u{1F310} **Fetch URL**" + tail;
   if (method && method !== "GET") out += "\n  method: " + method;
   const headers = raw.headers;
   if (headers && typeof headers === "object") {
@@ -384,9 +399,8 @@ function formatFetch(u: SessionUpdate, raw: Record<string, unknown>, tail: strin
 function formatWebSearch(u: SessionUpdate, raw: Record<string, unknown>, tail: string): string {
   const query = extractSearchQuery(raw) || extractUrl(raw);
   const count = strOf(raw.count) || strOf(raw.num) || strOf(raw.num_results) || numStr(raw.num_results);
-  let title = "Web search";
-  if (query) title += ": " + truncate(query, 150);
-  let out = "\u{1F310} **" + title + "**" + tail;
+  let out = "\u{1F310} **Web search**" + tail;
+  if (query) out += " " + pathCode(truncate(query, 150), "query");
   if (count) out += "\n  results: " + count;
   const result = extractToolOutput(u);
   if (result) {
@@ -428,7 +442,7 @@ function formatImage(raw: Record<string, unknown>, tail: string, toolName: strin
   const path = extractPath(raw) || strOf(raw.image) || strOf(raw.output);
   let out = "\u{1F5BC}\uFE0F **Image**" + tail;
   if (toolName) out += `\n  tool: \`${toolName}\``;
-  if (path) out += "\n  " + truncate(path, 200);
+  if (path) out += "\n  " + pathCode(truncate(path, 200));
   const prompt = strOf(raw.prompt);
   if (prompt) out += "\n  prompt: " + truncate(prompt, 200);
   return out;
@@ -482,27 +496,32 @@ function formatGeneric(
   const path = extractPath(raw);
   const cmd = extractCommand(raw);
   const query = extractSearchQuery(raw);
-  // Never show a bare "Other" / "Tool call" — prefer real tool name / path / cmd.
+  // Never show a bare "Other" / "Tool call" — prefer real tool name. Paths/queries
+  // go in inline code (not bold) so Windows paths cannot break MarkdownV2.
   let label =
     (toolName && !/^tool[_ ]?call$/i.test(toolName) ? toolName : "") ||
     (u.title && !/^other$/i.test(u.title.trim()) && !/^tool[_ ]?call$/i.test(u.title.trim())
       ? u.title.trim()
       : "") ||
-    (path ? capitalize(kind !== "other" ? kind : "use") + " " + path : "") ||
+    (path ? capitalize(kind !== "other" ? kind : "use") : "") ||
     (cmd ? "Run command" : "") ||
-    (query ? "Search: " + truncate(query, 80) : "") ||
+    (query ? "Search" : "") ||
     (kind && kind !== "other" ? capitalize(kind) : "") ||
     (toolName || "Tool");
   if (/^other$/i.test(label) || /^tool[_ ]?call$/i.test(label)) {
-    label = toolName && !/^tool[_ ]?call$/i.test(toolName) ? toolName : path || cmd || query || "Tool";
+    label = toolName && !/^tool[_ ]?call$/i.test(toolName) ? toolName : "Tool";
+  }
+  // Titles that accidentally embed a path stay short: drop path from bold label.
+  if (path && label.includes(path)) {
+    label = label.replace(path, "").replace(/\s+/g, " ").trim() || capitalize(kind !== "other" ? kind : "Tool");
   }
 
   let out = icon + " **" + label + "**" + tail;
   if (toolName && toolName !== label) out += `\n  tool: \`${toolName}\``;
-  if (path && !label.includes(path)) out += "\n  \u{1F4C4} " + truncate(path, 120);
+  if (path) out += "\n  \u{1F4C4} " + pathCode(truncate(path, 120));
   if (cmd) out += "\n" + fence(truncateMiddle(cmd, PREVIEW_MAX), "bash") + "\n";
-  else if (query && !label.includes(query)) out += "\n  query: " + truncate(query, 150);
-  else {
+  else if (query) out += "\n  query: " + pathCode(truncate(query, 150), "query");
+  else if (!path && !cmd) {
     const args = formatArgLines(raw);
     if (args) out += "\n" + fence(truncateMiddle(args, PREVIEW_MAX)) + "\n";
   }

package/src/service/platform.ts

@@ -2,7 +2,7 @@
  * Platform detection, launch-spec construction, and a small command runner
  * shared by the per-OS service controllers.
  */
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { join } from "node:path";
 import { PROJECT_ROOT, INSTANCE_DIR } from "../config.js";
 
@@ -47,18 +47,55 @@ export function buildLaunchSpec(): LaunchSpec {
   };
 }
 
-/** Run a command, returning combined output. Throws on non-zero exit. */
-export function run(cmd: string, args: string[]): string {
-  return execFileSync(cmd, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+/** Default max wait for schtasks/systemctl/powershell helpers — never hang the CLI. */
+const RUN_TIMEOUT_MS = 45_000;
+
+/** Run a command, returning combined output. Throws on non-zero exit or timeout. */
+export function run(cmd: string, args: string[], timeoutMs = RUN_TIMEOUT_MS): string {
+  return execFileSync(cmd, args, {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: timeoutMs,
+  });
 }
 
 /** Run a command, swallowing errors and returning { ok, out }. */
-export function runSafe(cmd: string, args: string[]): { ok: boolean; out: string } {
+export function runSafe(cmd: string, args: string[], timeoutMs = RUN_TIMEOUT_MS): { ok: boolean; out: string } {
   try {
-    return { ok: true, out: run(cmd, args) };
+    return { ok: true, out: run(cmd, args, timeoutMs) };
   } catch (e) {
-    const err = e as { stdout?: Buffer | string; stderr?: Buffer | string; message?: string };
+    const err = e as {
+      stdout?: Buffer | string;
+      stderr?: Buffer | string;
+      message?: string;
+      killed?: boolean;
+      code?: string;
+    };
+    // Node sets killed=true when the timeout option aborts the child.
+    if (err.killed || err.code === "ETIMEDOUT") {
+      return { ok: false, out: `timed out after ${timeoutMs}ms: ${cmd} ${args.join(" ")}` };
+    }
     const out = String(err.stdout ?? "") + String(err.stderr ?? "") || err.message || "failed";
     return { ok: false, out };
   }
 }
+
+/**
+ * Fire-and-forget process (detached). Use for forever-restart supervisors
+ * (Windows VBS loop) so `grok-tg install|start|restart` does not hang waiting
+ * for a process that never exits.
+ */
+export function launchDetached(cmd: string, args: string[]): { ok: boolean; out: string } {
+  try {
+    const child = spawn(cmd, args, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+    if (child.pid == null) return { ok: false, out: "spawn produced no pid" };
+    return { ok: true, out: `pid ${child.pid}` };
+  } catch (e) {
+    return { ok: false, out: (e as Error).message || "spawn failed" };
+  }
+}