grok-telegram-bot 2.0.0

package/src/render/markdown.ts

@@ -0,0 +1,130 @@
+/**
+ * Convert standard Markdown (as produced by the agent) into Telegram
+ * MarkdownV2, with correct escaping and graceful handling of code blocks,
+ * headings, lists, quotes, links and inline styles.
+ */
+import { escapeCode, escapeMdV2, escapeUrl } from "./escape.js";
+
+const FENCE = /```([^\n`]*)\n([\s\S]*?)```/g;
+
+/** Main entry: returns a MarkdownV2-safe string. */
+export function toTelegramMarkdown(src: string): string {
+  let out = "";
+  let last = 0;
+  let m: RegExpExecArray | null;
+  FENCE.lastIndex = 0;
+
+  while ((m = FENCE.exec(src)) !== null) {
+    out += renderTextBlock(src.slice(last, m.index));
+    const lang = (m[1] ?? "").trim();
+    const code = (m[2] ?? "").replace(/\n$/, "");
+    out += "```" + lang + "\n" + escapeCode(code) + "\n```\n";
+    last = FENCE.lastIndex;
+  }
+  out += renderTextBlock(src.slice(last));
+
+  return out.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function renderTextBlock(text: string): string {
+  if (!text) return "";
+  return text
+    .split("\n")
+    // Drop stray orphan backtick lines (` or ``) left by an unbalanced/partial
+    // code fence — they otherwise render as a broken-looking lone "`". A real
+    // fence is ``` (3+) and is handled by the FENCE pass, so it's never seen here.
+    .filter((line) => !/^\s*`{1,2}\s*$/.test(line))
+    .map((line) => renderLine(line))
+    .join("\n");
+}
+
+function renderLine(line: string): string {
+  // Heading -> bold
+  const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+  if (heading) return "*" + renderInline((heading[2] ?? "").replace(/#+\s*$/, "").trim()) + "*";
+
+  // Horizontal rule
+  if (/^\s*([-*_])\1{2,}\s*$/.test(line)) return "\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014";
+
+  // Blockquote (keep '>' literal so Telegram renders the quote)
+  const quote = /^>\s?(.*)$/.exec(line);
+  if (quote) return ">" + renderInline(quote[1] ?? "");
+
+  // Unordered list
+  const ul = /^(\s*)[-*+]\s+(.*)$/.exec(line);
+  if (ul) return (ul[1] ?? "") + "\u2022 " + renderInline(ul[2] ?? "");
+
+  // Ordered list
+  const ol = /^(\s*)(\d+)[.)]\s+(.*)$/.exec(line);
+  if (ol) return (ol[1] ?? "") + (ol[2] ?? "") + "\\. " + renderInline(ol[3] ?? "");
+
+  return renderInline(line);
+}
+
+/** Render inline markdown spans into MarkdownV2. */
+function renderInline(text: string): string {
+  let out = "";
+  let i = 0;
+  const n = text.length;
+
+  while (i < n) {
+    const c = text[i]!;
+    const next = text[i + 1];
+
+    // Inline code
+    if (c === "`") {
+      const end = text.indexOf("`", i + 1);
+      if (end !== -1) {
+        out += "`" + escapeCode(text.slice(i + 1, end)) + "`";
+        i = end + 1;
+        continue;
+      }
+    }
+
+    // Bold ** ** or __ __
+    if ((c === "*" && next === "*") || (c === "_" && next === "_")) {
+      const marker = c + c;
+      const end = text.indexOf(marker, i + 2);
+      if (end !== -1 && end > i + 2) {
+        out += "*" + renderInline(text.slice(i + 2, end)) + "*";
+        i = end + 2;
+        continue;
+      }
+    }
+
+    // Strikethrough ~~ ~~
+    if (c === "~" && next === "~") {
+      const end = text.indexOf("~~", i + 2);
+      if (end !== -1 && end > i + 2) {
+        out += "~" + renderInline(text.slice(i + 2, end)) + "~";
+        i = end + 2;
+        continue;
+      }
+    }
+
+    // Italic * * (single)
+    if (c === "*") {
+      const end = text.indexOf("*", i + 1);
+      if (end !== -1 && end > i + 1) {
+        out += "_" + renderInline(text.slice(i + 1, end)) + "_";
+        i = end + 1;
+        continue;
+      }
+    }
+
+    // Link [text](url)
+    if (c === "[") {
+      const link = /^\[([^\]]*)\]\(([^)\s]+)\)/.exec(text.slice(i));
+      if (link) {
+        out += "[" + renderInline(link[1] ?? "") + "](" + escapeUrl(link[2] ?? "") + ")";
+        i += link[0].length;
+        continue;
+      }
+    }
+
+    out += escapeMdV2(c);
+    i += 1;
+  }
+
+  return out;
+}

package/src/render/progress-estimate.ts

@@ -0,0 +1,63 @@
+/**
+ * Bot-side FALLBACK task-progress estimate.
+ *
+ * The primary progress signal is the `{progress: N%}` marker the agent is asked
+ * to emit (see PROGRESS_DIRECTIVE). But that marker is only an *instruction* the
+ * model can ignore — weaker/free models and long, tool-heavy turns frequently
+ * never emit one, leaving the bar empty for the whole turn. This module gives
+ * the bot a way to show a live, advancing bar anyway, derived ONLY from real,
+ * observable work signals (never random):
+ *
+ *   • completed tool calls   — each is concrete progress, weighted most
+ *   • streamed prose chars    — the agent explaining / answering
+ *   • streamed thinking chars — reasoning volume (weighted least)
+ *   • elapsed time            — a small, slow contribution so a quiet turn still creeps
+ *
+ * The estimate is monotonic by construction (every input only grows during a
+ * turn) and asymptotically capped well below 100 while running, so the bar never
+ * claims "done" on its own — the caller pushes 100 only when the turn actually
+ * completes. The agent's own marker, when present, always takes precedence.
+ */
+
+/** Observable, monotonically-increasing signals collected during one turn. */
+export interface ActivitySignals {
+  /** Number of tool calls / subagent transitions shown this turn. */
+  toolCalls: number;
+  /** Characters of agent prose streamed this turn. */
+  outputChars: number;
+  /** Characters of agent thinking streamed this turn. */
+  thoughtChars: number;
+  /** Milliseconds since the turn started. */
+  elapsedMs: number;
+}
+
+/** Hard ceiling for the fallback while a turn is still running. The agent (or
+ *  turn completion) is the only thing allowed to take the bar to 100. */
+export const FALLBACK_RUNNING_CAP = 90;
+
+/** Minimum shown once *any* work signal is present (so the bar never sits at 0
+ *  while the agent is clearly busy). */
+const FALLBACK_FLOOR = 5;
+
+/** Controls how quickly the asymptotic curve approaches the cap. Larger = slower. */
+const CURVE_K = 6;
+
+/**
+ * Map real work signals to a 0–FALLBACK_RUNNING_CAP estimate via a saturating
+ * curve `cap * (1 - e^(-units/K))`. Tool calls dominate because each is a
+ * discrete, completed step; text volume and elapsed time add gentle, diminishing
+ * contributions so a turn that's only thinking still advances slowly.
+ */
+export function estimateProgress(s: ActivitySignals): number {
+  const units =
+    Math.max(0, s.toolCalls) * 1.0 +
+    Math.max(0, s.outputChars) / 400 +
+    Math.max(0, s.thoughtChars) / 1500 +
+    Math.max(0, s.elapsedMs) / 30_000;
+
+  if (units <= 0) return 0;
+
+  const raw = FALLBACK_RUNNING_CAP * (1 - Math.exp(-units / CURVE_K));
+  const clamped = Math.min(FALLBACK_RUNNING_CAP, Math.max(FALLBACK_FLOOR, raw));
+  return Math.round(clamped);
+}

package/src/render/progress.ts

@@ -0,0 +1,80 @@
+/**
+ * Task-progress support: parse the `{progress: N%}` marker the agent appends to
+ * its messages, strip it from the visible text, and render a green loading bar.
+ *
+ * The agent is asked (see PROGRESS_DIRECTIVE) to end each message with a marker
+ * like `{progress: 65%}`. The bot extracts the latest value, removes the marker
+ * so it never shows raw, and renders a 0–100% bar (filled = 🟩, empty = ⬜) on
+ * the live message, in session cards, and in the pinned status panel.
+ */
+
+/** Matches a complete marker: `{progress: 65%}`, `{ progress:65 }`, etc. */
+const PROGRESS_RE = /\{\s*progress\s*:\s*(\d{1,3})\s*%?\s*\}/gi;
+/** Matches a trailing, not-yet-closed marker mid-stream (e.g. `…{progress: 6`). */
+const PARTIAL_TAIL_RE = /\{\s*progress\b[^}]*$/i;
+
+const FILLED = "\u{1F7E9}"; // 🟩
+const EMPTY = "\u2B1C"; // ⬜
+const SEGMENTS = 10;
+
+/**
+ * The instruction appended to prompts so the agent emits a progress marker.
+ *
+ * IMPORTANT for maintainers:
+ *  - The ONLY brace token may be the literal `{progress: N%}` with the letter
+ *    `N` (never a digit). A digit inside braces would be parsed by PROGRESS_RE
+ *    as a real value AND would break the exact-string strip in
+ *    `sessions/history.ts` (`cleanStoredText`).
+ *  - Keep this string "tidy-idempotent": no trailing spaces on any line, no run
+ *    of 3+ newlines, and no trailing whitespace at the end. `cleanStoredText`
+ *    runs `extractProgress` (which calls `tidy()`) before stripping the
+ *    directive by exact match, so any whitespace `tidy()` would rewrite must
+ *    not appear here, or the directive leaks into history/previews.
+ */
+export const PROGRESS_DIRECTIVE = [
+  "PROGRESS REPORTING IS MANDATORY ON EVERY SINGLE MESSAGE YOU SEND \u2014 NO EXCEPTIONS.",
+  "Rule 1 (format): finish EVERY message with a task-completion marker on its own final line, in EXACTLY this format, with nothing at all after it: {progress: N%}",
+  "N is a plain integer from 0 to 100 (no decimals, no ranges, no math). The marker is the very last thing in the message: no text, punctuation, spaces, emoji, backticks, or code fences may follow it, and it must NEVER be placed inside a code block or quote.",
+  "Rule 2 (frequency): emit the marker on your FIRST message, on EVERY intermediate message, after EVERY tool call or group of tool calls, around any subagent delegation, and on your FINAL message. Short replies, plans, questions, acknowledgements, clarifications, errors, and tool-only or status updates are NOT exempt \u2014 if you output any text at all, it ends with the marker. Do not batch it only into the last message.",
+  "Rule 3 (compute it for real, never random): before each message, decompose the overall task into the concrete steps it actually needs (understand the request, read the relevant files, each separate edit, run the build/tests, fix failures, verify) and set N = round(100 * completed_steps / total_steps), re-estimated fresh from the real current state each time.",
+  "Rule 4 (be granular and honest): start low (about 5 to 15 on your first message; use 0 only when literally nothing is started yet), then climb in realistic increments that mirror real progress. Do NOT jump from a low number straight to a high one, and do NOT keep repeating the same number across messages while work is clearly advancing.",
+  "Rule 5 (monotonic): within one task the number must NEVER decrease \u2014 each marker is greater than or equal to the previous one you emitted.",
+  "Rule 6 (terminal): report 100 ONLY when the entire task is fully complete and verified with nothing left to do. While ANY work, fix, verification, question, or follow-up remains, cap the number at 99.",
+  "The client parses this marker, removes it from the visible text, and renders it as a live progress bar, so its presence on every message and the accuracy of the number both matter.",
+].join("\n");
+
+export interface ProgressExtract {
+  /** Latest progress value found (0–100), or undefined if none. */
+  value?: number;
+  /** The input text with all progress markers removed. */
+  cleaned: string;
+}
+
+/** Pull the latest `{progress: N%}` value out of `text` and strip every marker
+ *  (plus any trailing half-streamed marker so it never flashes raw). */
+export function extractProgress(text: string): ProgressExtract {
+  let value: number | undefined;
+  let cleaned = text.replace(PROGRESS_RE, (_m, digits: string) => {
+    const v = Math.max(0, Math.min(100, Number.parseInt(digits, 10)));
+    if (Number.isFinite(v)) value = v; // keep the LAST occurrence (most recent)
+    return "";
+  });
+  cleaned = cleaned.replace(PARTIAL_TAIL_RE, "");
+  return { value, cleaned: tidy(cleaned) };
+}
+
+/** Tidy whitespace left behind by a removed marker. */
+function tidy(s: string): string {
+  return s
+    .replace(/[ \t]+\n/g, "\n") // trailing spaces on lines
+    .replace(/\n{3,}/g, "\n\n") // collapse blank-line runs
+    .replace(/\s+$/g, ""); // trailing whitespace/newlines
+}
+
+/** A 10-segment green progress bar, e.g. `🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜ 50%` (✅ at 100%). */
+export function progressBar(pct: number): string {
+  const v = Math.max(0, Math.min(100, Math.round(pct)));
+  const filled = Math.round((v / 100) * SEGMENTS);
+  const bar = FILLED.repeat(filled) + EMPTY.repeat(SEGMENTS - filled);
+  return `${bar} ${v}%${v >= 100 ? " \u2705" : ""}`;
+}

package/src/render/subagent.ts

@@ -0,0 +1,75 @@
+/**
+ * Render subagent ("crew") activity into short, readable status lines so the
+ * user can see what's happening while the main agent waits on its subagents.
+ */
+import type { PendingStage, SubagentInfo } from "../grok/types.js";
+
+const STATUS_ICON: Record<string, string> = {
+  working: "\u{1F3C3}", // 🏃 running
+  running: "\u{1F3C3}",
+  pending: "\u23F3",
+  queued: "\u23F3",
+  completed: "\u2705",
+  done: "\u2705",
+  terminated: "\u2705",
+  failed: "\u274C",
+  error: "\u274C",
+  cancelled: "\u23F9",
+};
+
+function trunc(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n - 1) + "\u2026" : s;
+}
+
+/** Normalize a subagent's status type to a short, stable key. */
+export function statusKey(s: SubagentInfo): string {
+  return (s.status?.type || "working").toLowerCase();
+}
+
+/** A one-line label for a subagent (no leading icon). */
+export function subagentLabel(s: SubagentInfo): string {
+  const name = s.sessionName || s.agentName || s.sessionId.slice(0, 8);
+  const role = s.role || s.agentName;
+  return role && role !== name ? `${name} (${role})` : name;
+}
+
+/**
+ * A markdown block announcing a subagent's status transition, or "" to skip.
+ * `kind`: "start" the first time it appears, otherwise from its status.
+ */
+export function renderSubagentTransition(s: SubagentInfo, kind: "start" | "status"): string {
+  const key = statusKey(s);
+  const label = subagentLabel(s);
+  if (kind === "start") {
+    const q = s.initialQuery ? `\n    \u2197 ${trunc(s.initialQuery.trim(), 140)}` : "";
+    return `\u{1F916} Subagent **${label}** started${q}`;
+  }
+  const icon = STATUS_ICON[key] ?? "\u{1F916}";
+  const verb =
+    key === "terminated" || key === "completed" || key === "done"
+      ? "finished"
+      : key === "failed" || key === "error"
+        ? "failed"
+        : key;
+  const msg = s.status?.message && !/^running$/i.test(s.status.message) ? ` \u2014 ${trunc(s.status.message, 80)}` : "";
+  return `${icon} Subagent **${label}** ${verb}${msg}`;
+}
+
+/** A compact summary for the status panel, e.g. "🤖 2 running · 1 pending". */
+export function subagentSummary(subagents: SubagentInfo[], pending: PendingStage[]): string | undefined {
+  const running = subagents.filter((s) => {
+    const k = statusKey(s);
+    return k === "working" || k === "running" || k === "pending" || k === "queued";
+  }).length;
+  const pend = pending.length;
+  if (running === 0 && pend === 0) return undefined;
+  const parts: string[] = [];
+  if (running > 0) parts.push(`${running} running`);
+  if (pend > 0) parts.push(`${pend} pending`);
+  return `\u{1F916} ${parts.join(" \u00B7 ")}`;
+}
+
+/** True when a status type means the subagent is still active. */
+export function isActiveStatus(key: string): boolean {
+  return key === "working" || key === "running" || key === "pending" || key === "queued";
+}

package/src/render/tool-call.ts

@@ -0,0 +1,196 @@
+/**
+ * Format ACP tool-call updates into clear, RAW markdown blocks so they read
+ * distinctly from the agent's prose and thinking. Commands appear in a `bash`
+ * block, file edits as a `diff` block.
+ */
+import type { SessionUpdate, ToolCallContent } from "../grok/types.js";
+import { renderUnifiedDiff } from "./diff.js";
+
+const KIND_ICON: Record<string, string> = {
+  read: "\u{1F4D6}",
+  edit: "\u270F\uFE0F",
+  execute: "\u{1F4BB}",
+  search: "\u{1F50E}",
+  delete: "\u{1F5D1}\uFE0F",
+  move: "\u{1F4E6}",
+  fetch: "\u{1F310}",
+  think: "\u{1F4AD}",
+  other: "\u{1F527}",
+};
+
+const STATUS_ICON: Record<string, string> = {
+  pending: "",
+  in_progress: "\u23F3",
+  completed: "\u2705",
+  failed: "\u274C",
+};
+
+export interface ToolFormatOptions {
+  showDiffs: boolean;
+  diffMaxLines: number;
+}
+
+/** Returns a RAW markdown block describing the tool call, or "" to skip. */
+export function formatToolCall(u: SessionUpdate, opts: ToolFormatOptions): string {
+  const kind = (u.kind || "other").toLowerCase();
+  const raw = (u.rawInput || {}) as Record<string, unknown>;
+  const status = u.status ? (STATUS_ICON[u.status] ?? "") : "";
+  const tail = status ? ` ${status}` : "";
+
+  // Skill load — reading a `.../skills/<name>/SKILL.md`. Don't treat edits/
+  // deletes of a SKILL.md (skill authoring) as a "load".
+  if (kind !== "edit" && kind !== "delete" && kind !== "move") {
+    const skill = detectSkill(u, raw);
+    if (skill) return `\u{1F4DA} **Loaded skill: ${skill}**${tail}`;
+  }
+
+  // MCP / extension tool call → "Call MCP <server>: <method>" (or "Call MCP:
+  // <tool>" when the call carries no server name).
+  const mcp = detectMcp(u, raw, kind);
+  if (mcp) {
+    const label = mcp.server ? `Call MCP ${mcp.server}: ${mcp.method}` : `Call MCP: ${mcp.method}`;
+    return `\u{1F9E9} **${label}**${tail}`;
+  }
+
+  const icon = KIND_ICON[kind] ?? KIND_ICON.other;
+  const title = u.title || titleFromRaw(kind, raw);
+
+  let out = `${icon} **${title}**${tail}`;
+
+  if (kind === "execute") {
+    const cmd = strOf(raw.command ?? raw.cmd);
+    if (cmd) out += "\n```bash\n" + cmd + "\n```";
+  }
+
+  if (kind === "edit" && opts.showDiffs) {
+    const diff = buildEditDiff(u, raw, opts.diffMaxLines);
+    if (diff && diff.block) {
+      const stat = `${diff.added > 0 ? "+" + diff.added : ""}${diff.removed > 0 ? " -" + diff.removed : ""}`.trim();
+      out += `${stat ? `  (${stat})` : ""}\n${diff.block}`;
+    }
+  }
+
+  return out;
+}
+
+/** Built-in Grok tools that must never be labelled as MCP calls. */
+const BUILTIN_TOOLS = new Set([
+  "read", "write", "shell", "grep", "glob", "web_fetch", "web_search", "fs_read",
+  "fs_write", "fs_replace", "fs_search", "execute_bash", "report_issue", "use_aws",
+  "todo_list", "introspect", "knowledge", "thinking", "summary", "subagent",
+]);
+/** Tool kinds that are first-class file/shell operations (never MCP). */
+const FILE_KINDS = new Set(["read", "edit", "execute", "search", "delete", "move"]);
+/** `.../skills/<name>/SKILL.md` — the signature of loading a skill. */
+const SKILL_RE = /[\\/]skills[\\/]([^\\/]+)[\\/]SKILL\.md$/i;
+/** Namespaced MCP tool-name shapes → [, server, method]. */
+const MCP_NS = [
+  /^@([a-z0-9._-]+)[/_]{1,3}(.+)$/i, // @server/method · @server___method
+  /^([a-z0-9.-]+)___(.+)$/i, // server___method
+  /^([a-z0-9.-]+)__(.+)$/i, // server__method
+  /^([a-z0-9.-]+)\/(.+)$/i, // server/method
+  /^([a-z0-9-]+)\.(.+)$/i, // server.method
+];
+
+/** The skill name if this tool call loads a `SKILL.md`, else undefined. */
+function detectSkill(u: SessionUpdate, raw: Record<string, unknown>): string | undefined {
+  for (const p of gatherPaths(u, raw)) {
+    const m = SKILL_RE.exec(p);
+    if (m) return m[1];
+  }
+  return undefined;
+}
+
+/** The MCP server + method this call targets, if it looks like an MCP/external
+ *  tool. Built-in file/shell tools return undefined. */
+function detectMcp(
+  u: SessionUpdate,
+  raw: Record<string, unknown>,
+  kind: string,
+): { server?: string; method: string } | undefined {
+  const name = mcpToolName(u, raw);
+  if (!name) return undefined;
+  for (const re of MCP_NS) {
+    const m = re.exec(name);
+    if (m) return { server: m[1]!, method: m[2]! };
+  }
+  // Bare external tool: not a built-in, and not a file/shell operation.
+  if (!BUILTIN_TOOLS.has(name.toLowerCase()) && !FILE_KINDS.has(kind)) {
+    return { method: name };
+  }
+  return undefined;
+}
+
+/** Best-effort tool name from the raw input or a tool-name-like title. */
+function mcpToolName(u: SessionUpdate, raw: Record<string, unknown>): string {
+  const explicit = strOf(raw.tool_name) || strOf(raw.toolName) || strOf(raw.name) || strOf(raw.tool);
+  if (explicit) return explicit;
+  const t = (u.title || "").trim();
+  // Use the title only when it reads like a tool identifier (no spaces, not a
+  // "file:line" read title like "SKILL.md:1").
+  return /^[@a-z0-9._/-]+$/i.test(t) && !t.includes(":") ? t : "";
+}
+
+/** Collect every file path referenced by a tool call (incl. nested ops/diffs). */
+function gatherPaths(u: SessionUpdate, raw: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  const add = (v: unknown): void => {
+    if (typeof v === "string" && v) out.push(v);
+  };
+  add(raw.path);
+  add(raw.file_path);
+  add(raw.filename);
+  add(raw.file);
+  if (Array.isArray(raw.operations)) {
+    for (const op of raw.operations) {
+      if (op && typeof op === "object") add((op as Record<string, unknown>).path);
+    }
+  }
+  for (const b of collectContent(u)) add(b.path);
+  return out;
+}
+
+function buildEditDiff(u: SessionUpdate, raw: Record<string, unknown>, maxLines: number) {
+  const blocks = collectContent(u);
+  const diffBlock = blocks.find((b) => b.type === "diff");
+  if (diffBlock) {
+    return renderUnifiedDiff({
+      path: strOf(diffBlock.path) || strOf(raw.path) || "file",
+      oldText: typeof diffBlock.oldText === "string" ? diffBlock.oldText : "",
+      newText: typeof diffBlock.newText === "string" ? diffBlock.newText : "",
+      maxLines,
+    });
+  }
+  const oldStr = strOf(raw.old_str ?? raw.oldStr);
+  const newStr = strOf(raw.new_str ?? raw.newStr);
+  if (oldStr || newStr) {
+    return renderUnifiedDiff({ path: strOf(raw.path) || "file", oldText: oldStr, newText: newStr, maxLines });
+  }
+  const content = strOf(raw.file_text ?? raw.content ?? raw.text);
+  if (content) {
+    return renderUnifiedDiff({ path: strOf(raw.path) || "file", oldText: "", newText: content, maxLines });
+  }
+  return undefined;
+}
+
+function titleFromRaw(kind: string, raw: Record<string, unknown>): string {
+  const path = strOf(raw.path ?? raw.file_path ?? raw.filename);
+  if (path) return `${capitalize(kind)} ${path}`;
+  return capitalize(kind);
+}
+
+function collectContent(u: SessionUpdate): ToolCallContent[] {
+  const out: ToolCallContent[] = [];
+  if (Array.isArray(u.content_blocks)) out.push(...u.content_blocks);
+  const content = (u as unknown as { content?: unknown }).content;
+  if (Array.isArray(content)) out.push(...(content as ToolCallContent[]));
+  return out;
+}
+
+function strOf(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+function capitalize(s: string): string {
+  return s.length ? s[0]!.toUpperCase() + s.slice(1) : s;
+}

package/src/service/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Selects the right service controller for the current platform.
+ */
+import { detectPlatform } from "./platform.js";
+import { linuxController } from "./linux.js";
+import { macosController } from "./macos.js";
+import type { ServiceController } from "./types.js";
+import { windowsController } from "./windows.js";
+
+export { buildLaunchSpec } from "./platform.js";
+export type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
+
+export function getController(): ServiceController {
+  switch (detectPlatform()) {
+    case "windows":
+      return windowsController;
+    case "linux":
+      return linuxController;
+    case "macos":
+      return macosController;
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}

package/src/service/linux.ts

@@ -0,0 +1,85 @@
+/**
+ * Linux service controller — installs a systemd *user* service so no sudo is
+ * required. `loginctl enable-linger` is attempted so the bot runs at boot even
+ * before you log in.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { runSafe } from "./platform.js";
+import type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
+
+const UNIT = "grok-telegram-bot.service";
+
+function unitPath(): string {
+  return join(homedir(), ".config", "systemd", "user", UNIT);
+}
+
+export const linuxController: ServiceController = {
+  platform: "linux",
+
+  async install(spec) {
+    mkdirSync(join(homedir(), ".config", "systemd", "user"), { recursive: true });
+    mkdirSync(spec.logsDir, { recursive: true });
+    writeFileSync(unitPath(), unitFile(spec), "utf-8");
+
+    runSafe("systemctl", ["--user", "daemon-reload"]);
+    const en = runSafe("systemctl", ["--user", "enable", "--now", UNIT]);
+    if (!en.ok) return fail(`systemctl enable failed: ${en.out}`);
+    const linger = runSafe("loginctl", ["enable-linger", userInfo().username]);
+    const note = linger.ok ? " Boot-without-login enabled (linger)." : " (run `loginctl enable-linger` for boot-without-login)";
+    return ok(`Installed and started systemd user service "${UNIT}".${note}`);
+  },
+
+  async uninstall() {
+    runSafe("systemctl", ["--user", "disable", "--now", UNIT]);
+    rmSync(unitPath(), { force: true });
+    runSafe("systemctl", ["--user", "daemon-reload"]);
+    return ok(`Removed systemd user service "${UNIT}".`);
+  },
+
+  async start() {
+    const r = runSafe("systemctl", ["--user", "start", UNIT]);
+    return r.ok ? ok("Started.") : fail(r.out);
+  },
+
+  async stop() {
+    const r = runSafe("systemctl", ["--user", "stop", UNIT]);
+    return r.ok ? ok("Stopped.") : fail(r.out);
+  },
+
+  async status() {
+    const r = runSafe("systemctl", ["--user", "status", UNIT, "--no-pager"]);
+    return ok(r.out.trim() || "No status.");
+  },
+};
+
+function unitFile(spec: LaunchSpec): string {
+  const exec = `${spec.nodePath} ${spec.args.join(" ")}`;
+  const env = Object.entries(spec.env ?? {}).map(([k, v]) => `Environment=${k}=${v}`);
+  return [
+    "[Unit]",
+    `Description=${spec.displayName}`,
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `WorkingDirectory=${spec.cwd}`,
+    ...env,
+    `ExecStart=${exec}`,
+    "Restart=always",
+    "RestartSec=5",
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    "",
+  ].join("\n");
+}
+
+function ok(message: string): ServiceResult {
+  return { ok: true, message };
+}
+function fail(message: string): ServiceResult {
+  return { ok: false, message };
+}