grok-telegram-bot 2.0.0

package/src/mcp/probe.ts

@@ -0,0 +1,218 @@
+/**
+ * MCP health probe — performs a real MCP `initialize` JSON-RPC handshake against
+ * a configured server to determine whether it actually connects, and why not.
+ *
+ *   • stdio servers → spawn the command (args/env), write `initialize` to stdin,
+ *     await a matching JSON-RPC response on stdout, then kill the process.
+ *   • http servers  → POST `initialize` to the URL (with headers); accept either
+ *     a JSON body or an SSE `data:` line (Streamable HTTP transport).
+ *
+ * This mirrors exactly what an MCP client does on connect, so a success means
+ * the server is reachable and speaks MCP; a failure carries the real reason
+ * (command not found, timeout, HTTP status, transport error, …).
+ */
+import { spawn } from "node:child_process";
+import { createLogger } from "../logger.js";
+import type { McpProbeResult, McpServer } from "./types.js";
+
+const log = createLogger("mcp:probe");
+
+const INIT_REQUEST = {
+  jsonrpc: "2.0",
+  id: 1,
+  method: "initialize",
+  params: {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "grok-telegram-bot", version: "1.0.0" },
+  },
+};
+
+export interface ProbeOptions {
+  timeoutMs: number;
+  concurrency: number;
+}
+
+/** Probe a single server. Never throws — failures are returned as results. */
+export async function probeServer(server: McpServer, timeoutMs: number): Promise<McpProbeResult> {
+  if (server.disabled) return { name: server.name, ok: false, skipped: true, error: "disabled" };
+  const start = Date.now();
+  try {
+    const info = server.transport === "http" ? await probeHttp(server, timeoutMs) : await probeStdio(server, timeoutMs);
+    return { name: server.name, ok: true, ms: Date.now() - start, serverName: info.name, serverVersion: info.version };
+  } catch (e) {
+    return { name: server.name, ok: false, ms: Date.now() - start, error: (e as Error).message };
+  }
+}
+
+/** Probe many servers with bounded concurrency. Disabled servers are skipped. */
+export async function probeAll(
+  servers: McpServer[],
+  opts: ProbeOptions,
+  onResult?: (r: McpProbeResult, done: number, total: number) => void,
+): Promise<McpProbeResult[]> {
+  const results: McpProbeResult[] = new Array(servers.length);
+  let next = 0;
+  let done = 0;
+  const total = servers.length;
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const i = next++;
+      if (i >= servers.length) return;
+      const r = await probeServer(servers[i]!, opts.timeoutMs);
+      results[i] = r;
+      done++;
+      try {
+        onResult?.(r, done, total);
+      } catch {
+        /* non-fatal */
+      }
+    }
+  };
+  const workers = Array.from({ length: Math.max(1, Math.min(opts.concurrency, servers.length)) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}
+
+interface ServerIdent {
+  name?: string;
+  version?: string;
+}
+
+function identFrom(result: unknown): ServerIdent {
+  const r = result as { serverInfo?: { name?: string; version?: string } };
+  return { name: r?.serverInfo?.name, version: r?.serverInfo?.version };
+}
+
+/** stdio handshake: spawn, send initialize, await a JSON-RPC response. */
+function probeStdio(server: McpServer, timeoutMs: number): Promise<ServerIdent> {
+  return new Promise<ServerIdent>((resolve, reject) => {
+    const cmd = server.config.command;
+    if (!cmd) return reject(new Error("no command configured"));
+    const args = Array.isArray(server.config.args) ? server.config.args.map(String) : [];
+    let settled = false;
+    let proc: ReturnType<typeof spawn>;
+    try {
+      proc = spawn(cmd, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env, ...(server.config.env ?? {}) },
+        windowsHide: true,
+      });
+    } catch (e) {
+      return reject(new Error(`spawn failed: ${(e as Error).message}`));
+    }
+
+    const finish = (err?: Error, ident?: ServerIdent): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        proc.kill();
+      } catch {
+        /* ignore */
+      }
+      if (err) reject(err);
+      else resolve(ident ?? {});
+    };
+
+    const timer = setTimeout(() => finish(new Error(`timeout after ${timeoutMs}ms (no response)`)), timeoutMs);
+
+    let stderrTail = "";
+    let buf = "";
+    proc.stdout?.setEncoding("utf-8");
+    proc.stdout?.on("data", (chunk: string) => {
+      buf += chunk;
+      let i: number;
+      while ((i = buf.indexOf("\n")) !== -1) {
+        const line = buf.slice(0, i).trim();
+        buf = buf.slice(i + 1);
+        if (!line) continue;
+        try {
+          const m = JSON.parse(line) as { id?: unknown; result?: unknown; error?: { message?: string } };
+          if (m && m.id === 1) {
+            if (m.error) finish(new Error(`server error: ${m.error.message ?? "unknown"}`));
+            else finish(undefined, identFrom(m.result));
+            return;
+          }
+        } catch {
+          /* partial / non-JSON banner line — keep reading */
+        }
+      }
+    });
+    proc.stderr?.setEncoding("utf-8");
+    proc.stderr?.on("data", (c: string) => {
+      stderrTail = (stderrTail + c).slice(-300);
+    });
+    proc.on("error", (e) => finish(new Error(`spawn failed: ${e.message}`)));
+    proc.on("exit", (code) => {
+      if (!settled) {
+        const tail = stderrTail.trim() ? ` — ${stderrTail.trim().split("\n").pop()}` : "";
+        finish(new Error(`process exited (code ${code})${tail}`));
+      }
+    });
+
+    try {
+      proc.stdin?.write(JSON.stringify(INIT_REQUEST) + "\n");
+    } catch (e) {
+      finish(new Error(`write failed: ${(e as Error).message}`));
+    }
+  });
+}
+
+/** HTTP handshake: POST initialize; parse JSON or an SSE `data:` payload. */
+async function probeHttp(server: McpServer, timeoutMs: number): Promise<ServerIdent> {
+  const url = server.config.url!;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        ...(server.config.headers ?? {}),
+      },
+      body: JSON.stringify(INIT_REQUEST),
+      signal: controller.signal,
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`.trim());
+    const text = await res.text();
+    const parsed = parseJsonOrSse(text);
+    if (!parsed) throw new Error("no JSON-RPC result in response");
+    if (parsed.error) throw new Error(`server error: ${parsed.error.message ?? "unknown"}`);
+    return identFrom(parsed.result);
+  } catch (e) {
+    const msg = (e as Error).name === "AbortError" ? `timeout after ${timeoutMs}ms` : (e as Error).message;
+    throw new Error(msg);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+interface RpcEnvelope {
+  result?: unknown;
+  error?: { message?: string };
+}
+
+/** Accept a plain JSON body or SSE frames (`event: …\n data: {json}`). */
+function parseJsonOrSse(text: string): RpcEnvelope | undefined {
+  const trimmed = text.trim();
+  if (!trimmed) return undefined;
+  try {
+    return JSON.parse(trimmed) as RpcEnvelope;
+  } catch {
+    /* maybe SSE */
+  }
+  for (const line of trimmed.split("\n")) {
+    const m = /^data:\s*(.+)$/.exec(line.trim());
+    if (m) {
+      try {
+        return JSON.parse(m[1]!) as RpcEnvelope;
+      } catch {
+        /* keep scanning */
+      }
+    }
+  }
+  log.debug("unparseable MCP HTTP response:", trimmed.slice(0, 120));
+  return undefined;
+}

package/src/mcp/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Types for MCP (Model Context Protocol) server inspection & control.
+ *
+ * Grok CLI loads MCP servers from JSON config files: a global one at
+ * `~/.grok/settings/mcp.json` (the "default" scope used by the default agent)
+ * and an optional per-workspace `<cwd>/.grok/settings/mcp.json`. Each server may
+ * carry a `disabled` flag; toggling it enables/disables the server (applied the
+ * next time the agent (re)loads — i.e. after `/restart` or a new session).
+ */
+
+export type McpScope = "global" | "workspace";
+export type McpTransport = "http" | "stdio" | "unknown";
+
+/** Raw server definition as stored in an mcp.json `mcpServers` entry. */
+export interface McpServerConfig {
+  command?: string;
+  args?: string[];
+  url?: string;
+  headers?: Record<string, string>;
+  env?: Record<string, string>;
+  timeout?: number;
+  disabled?: boolean;
+  autoApprove?: string[];
+  [k: string]: unknown;
+}
+
+/** A configured server resolved from a specific config file. */
+export interface McpServer {
+  name: string;
+  scope: McpScope;
+  /** Absolute path of the config file this server is defined in. */
+  configPath: string;
+  disabled: boolean;
+  transport: McpTransport;
+  /** Short transport descriptor for display (command or url, trimmed). */
+  detail: string;
+  config: McpServerConfig;
+}
+
+/** Result of a live connection probe (MCP `initialize` handshake). */
+export interface McpProbeResult {
+  name: string;
+  ok: boolean;
+  /** Round-trip time in ms when ok. */
+  ms?: number;
+  /** Server-reported name/version when ok. */
+  serverName?: string;
+  serverVersion?: string;
+  /** Human-readable failure reason when not ok. */
+  error?: string;
+  /** True when the server was skipped because it is disabled. */
+  skipped?: boolean;
+}
+
+export function transportOf(c: McpServerConfig): McpTransport {
+  if (typeof c.url === "string" && c.url.trim()) return "http";
+  if (typeof c.command === "string" && c.command.trim()) return "stdio";
+  return "unknown";
+}
+
+export function detailOf(c: McpServerConfig): string {
+  if (typeof c.url === "string" && c.url.trim()) return c.url.trim();
+  if (typeof c.command === "string" && c.command.trim()) {
+    const args = Array.isArray(c.args) && c.args.length ? " " + c.args.join(" ") : "";
+    return (c.command + args).trim();
+  }
+  return "(no command/url)";
+}

package/src/projects/manager.ts

@@ -0,0 +1,99 @@
+/**
+ * Project manager — discovers candidate project directories under the
+ * configured roots, de-duplicated by name, with search and create helpers.
+ */
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("projects");
+
+const IGNORE = new Set([
+  "node_modules",
+  ".git",
+  ".history",
+  "dist",
+  "build",
+  "out",
+  ".cache",
+  "target",
+  ".venv",
+  "__pycache__",
+]);
+
+export interface ProjectEntry {
+  name: string;
+  path: string;
+  /** Best-known "last used" time (epoch ms) — directory mtime by default,
+   *  refined with Grok session activity by the caller. Drives freshest-first. */
+  lastUsed: number;
+}
+
+export class ProjectManager {
+  constructor(private readonly roots: string[]) {}
+
+  /** List projects, de-duplicated by (case-insensitive) name. */
+  list(limit = 100): ProjectEntry[] {
+    const byName = new Map<string, ProjectEntry>();
+
+    for (const root of this.roots) {
+      let children: string[];
+      try {
+        children = readdirSync(root);
+      } catch (e) {
+        log.debug(`cannot read root ${root}:`, (e as Error).message);
+        continue;
+      }
+      for (const child of children) {
+        if (IGNORE.has(child) || child.startsWith(".")) continue;
+        const full = join(root, child);
+        let mtime = 0;
+        try {
+          const st = statSync(full);
+          if (!st.isDirectory()) continue;
+          mtime = st.mtimeMs;
+        } catch {
+          continue;
+        }
+        const key = child.toLowerCase();
+        if (!byName.has(key)) byName.set(key, { name: child, path: full, lastUsed: mtime });
+      }
+    }
+
+    // Freshest first (directory mtime); callers may refine `lastUsed` with
+    // session activity and re-sort. Alphabetical as a stable tiebreak.
+    const out = [...byName.values()].sort(
+      (a, b) => b.lastUsed - a.lastUsed || a.name.localeCompare(b.name),
+    );
+    return out.slice(0, limit);
+  }
+
+  /** Projects whose name contains the query (case-insensitive). */
+  search(query: string, limit = 100): ProjectEntry[] {
+    const q = query.trim().toLowerCase();
+    if (!q) return this.list(limit);
+    return this.list(1000)
+      .filter((p) => p.name.toLowerCase().includes(q))
+      .slice(0, limit);
+  }
+
+  /** Create a new project folder under the first root and return it. */
+  create(name: string): ProjectEntry {
+    const clean = name.trim().replace(/[<>:"/\\|?*]/g, "_");
+    if (!clean) throw new Error("Invalid project name.");
+    const root = this.roots[0];
+    if (!root) throw new Error("No project root configured (set PROJECT_ROOTS).");
+    const full = join(root, clean);
+    if (existsSync(full)) throw new Error(`"${clean}" already exists in ${root}.`);
+    mkdirSync(full, { recursive: true });
+    return { name: clean, path: full, lastUsed: Date.now() };
+  }
+
+  isDirectory(path: string): boolean {
+    try {
+      return statSync(path).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+}

package/src/render/chunk.ts

@@ -0,0 +1,57 @@
+/**
+ * Split a MarkdownV2 string into Telegram-sized chunks (<= 4096 chars) without
+ * breaking code fences. If a split happens inside a ``` block, the block is
+ * closed before the boundary and reopened in the next chunk.
+ */
+const LIMIT = 4000; // headroom under Telegram's 4096 hard limit
+
+export function chunkMarkdown(text: string, limit = LIMIT): string[] {
+  if (text.length <= limit) return text.length ? [text] : [];
+
+  const lines = text.split("\n");
+  const chunks: string[] = [];
+  let current: string[] = [];
+  let size = 0;
+  let fenceLang: string | null = null; // non-null => currently inside a fence
+
+  const flush = (): void => {
+    if (current.length === 0) return;
+    let body = current.join("\n");
+    if (fenceLang !== null) body += "\n```"; // close dangling fence
+    chunks.push(body);
+    current = [];
+    size = 0;
+    if (fenceLang !== null) {
+      // Reopen the fence at the top of the next chunk.
+      const reopen = "```" + fenceLang;
+      current.push(reopen);
+      size = reopen.length + 1;
+    }
+  };
+
+  for (const rawLine of lines) {
+    const line = rawLine;
+    const fenceMatch = /^```(.*)$/.exec(line);
+
+    // Hard-split a single oversized line.
+    if (line.length + 1 > limit && fenceMatch === null) {
+      flush();
+      for (let i = 0; i < line.length; i += limit) {
+        chunks.push(line.slice(i, i + limit));
+      }
+      continue;
+    }
+
+    if (size + line.length + 1 > limit) flush();
+
+    current.push(line);
+    size += line.length + 1;
+
+    if (fenceMatch) {
+      fenceLang = fenceLang === null ? (fenceMatch[1] ?? "").trim() : null;
+    }
+  }
+
+  flush();
+  return chunks.filter((c) => c.trim().length > 0);
+}

package/src/render/diff.ts

@@ -0,0 +1,48 @@
+/**
+ * Render a unified diff for a file edit as RAW markdown (a ```diff fenced
+ * block). Escaping/splitting is handled downstream by the markdown converter.
+ */
+import { structuredPatch } from "diff";
+
+export interface DiffInput {
+  path: string;
+  oldText: string | null | undefined;
+  newText: string | null | undefined;
+  maxLines: number;
+}
+
+export interface DiffResult {
+  block: string; // raw ```diff fenced markdown, or ""
+  added: number;
+  removed: number;
+}
+
+export function renderUnifiedDiff(input: DiffInput): DiffResult {
+  const oldText = input.oldText ?? "";
+  const newText = input.newText ?? "";
+  if (oldText === newText) return { block: "", added: 0, removed: 0 };
+
+  const patch = structuredPatch(input.path, input.path, oldText, newText, "", "", { context: 2 });
+  const lines: string[] = [];
+  let added = 0;
+  let removed = 0;
+
+  for (const hunk of patch.hunks) {
+    lines.push(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`);
+    for (const l of hunk.lines) {
+      if (l.startsWith("\\")) continue; // drop ""
+      if (l.startsWith("+")) added++;
+      else if (l.startsWith("-")) removed++;
+      lines.push(l);
+    }
+  }
+  if (lines.length === 0) return { block: "", added, removed };
+
+  let shown = lines;
+  let note = "";
+  if (lines.length > input.maxLines) {
+    shown = lines.slice(0, input.maxLines);
+    note = `\n… +${lines.length - input.maxLines} more lines`;
+  }
+  return { block: "```diff\n" + shown.join("\n") + note + "\n```", added, removed };
+}

package/src/render/escape.ts

@@ -0,0 +1,22 @@
+/**
+ * Telegram MarkdownV2 escaping helpers.
+ * @see https://core.telegram.org/bots/api#markdownv2-style
+ */
+
+// Characters that must be escaped in normal MarkdownV2 text.
+const SPECIAL = /[_*\[\]()~`>#+\-=|{}.!\\]/g;
+
+/** Escape text that appears in normal (non-entity) MarkdownV2 context. */
+export function escapeMdV2(text: string): string {
+  return text.replace(SPECIAL, (c) => `\\${c}`);
+}
+
+/** Escape the body of an inline code span or code block (only ` and \). */
+export function escapeCode(text: string): string {
+  return text.replace(/([`\\])/g, "\\$1");
+}
+
+/** Escape a URL used inside a MarkdownV2 link target. */
+export function escapeUrl(url: string): string {
+  return url.replace(/([)\\])/g, "\\$1");
+}

package/src/render/file-summary.ts

@@ -0,0 +1,111 @@
+/**
+ * File-change summary for the turn-completion message. We classify each
+ * tool-call update into a file operation (created / edited / deleted / moved)
+ * and render a compact summary — independent of whether the turn streamed live,
+ * so a background session's "Done" still reports what changed.
+ */
+import type { SessionUpdate, ToolCallContent } from "../grok/types.js";
+
+export type FileOp = "created" | "edited" | "deleted" | "moved";
+
+/** Tool kinds that never modify files. */
+const NON_FILE = new Set(["read", "search", "fetch", "execute", "think", "other", ""]);
+
+/** Merge priority — a stronger signal wins (deleted > moved > edited > created). */
+const RANK: Record<FileOp, number> = { created: 1, edited: 2, moved: 3, deleted: 4 };
+
+const SIGN: Record<FileOp, string> = { created: "+", edited: "~", deleted: "\u2212", moved: "\u2192" };
+const ORDER: Record<FileOp, number> = { created: 0, edited: 1, deleted: 2, moved: 3 };
+
+/** The file path + operation a tool-call update represents, or undefined. */
+export function fileOpFromUpdate(u: SessionUpdate): { path: string; op: FileOp } | undefined {
+  const kind = (u.kind || "").toLowerCase();
+  if (NON_FILE.has(kind)) return undefined;
+
+  const raw = (u.rawInput || {}) as Record<string, unknown>;
+  const diff = findDiff(u);
+  const path =
+    str(diff?.path) || str(raw.path) || str(raw.file_path) || str(raw.filename) || pathFromTitle(u.title);
+  if (!path) return undefined;
+
+  if (kind === "delete") return { path, op: "deleted" };
+  if (kind === "move" || kind === "rename") return { path, op: "moved" };
+
+  // Edit-like: classify by whether the file had prior content.
+  const oldText = diff && typeof diff.oldText === "string" ? diff.oldText : str(raw.old_str ?? raw.oldStr);
+  const newText =
+    diff && typeof diff.newText === "string"
+      ? diff.newText
+      : str(raw.new_str ?? raw.newStr ?? raw.file_text ?? raw.content ?? raw.text);
+  const hasOld = oldText.trim().length > 0;
+  const hasNew = newText.trim().length > 0;
+  if (hasOld && !hasNew) return { path, op: "deleted" };
+  if (!hasOld && hasNew) return { path, op: "created" };
+  return { path, op: "edited" };
+}
+
+/** Combine a new op into an existing one for the same path (stronger wins). */
+export function mergeFileOp(prev: FileOp | undefined, next: FileOp): FileOp {
+  if (!prev) return next;
+  return RANK[next] > RANK[prev] ? next : prev;
+}
+
+/**
+ * Render the file-change summary appended to a turn's completion message.
+ * Always returns a line — "No files modified" when nothing changed.
+ */
+export function summarizeFileOps(ops: Map<string, FileOp>, cwd: string, maxList = 15): string {
+  if (ops.size === 0) return "\u{1F4C4} No files modified";
+
+  const entries = [...ops.entries()].sort(
+    (a, b) => ORDER[a[1]] - ORDER[b[1]] || a[0].localeCompare(b[0]),
+  );
+  const shown = entries.slice(0, maxList).map(([p, op]) => `${SIGN[op]} ${rel(cwd, p)}`);
+  const more = entries.length > maxList ? `\n  \u2026and ${entries.length - maxList} more` : "";
+
+  return `\u{1F4DD} ${countsLine(ops)}\n  ${shown.join("\n  ")}${more}`;
+}
+
+/** Compact, one-line counts (no file list) — used for "other session" pings. */
+export function summarizeFileOpsShort(ops: Map<string, FileOp>): string {
+  return ops.size === 0 ? "\u{1F4C4} No files modified" : `\u{1F4DD} ${countsLine(ops)}`;
+}
+
+/** "+2 created · ~3 edited · −1 deleted" — only the non-zero buckets. */
+function countsLine(ops: Map<string, FileOp>): string {
+  const counts: Record<FileOp, number> = { created: 0, edited: 0, deleted: 0, moved: 0 };
+  for (const op of ops.values()) counts[op]++;
+  const parts: string[] = [];
+  if (counts.created) parts.push(`+${counts.created} created`);
+  if (counts.edited) parts.push(`~${counts.edited} edited`);
+  if (counts.deleted) parts.push(`\u2212${counts.deleted} deleted`);
+  if (counts.moved) parts.push(`\u2192${counts.moved} moved`);
+  return parts.join(" \u00B7 ");
+}
+
+function findDiff(u: SessionUpdate): ToolCallContent | undefined {
+  const blocks: ToolCallContent[] = [];
+  if (Array.isArray(u.content_blocks)) blocks.push(...u.content_blocks);
+  const content = (u as unknown as { content?: unknown }).content;
+  if (Array.isArray(content)) blocks.push(...(content as ToolCallContent[]));
+  return blocks.find((b) => b.type === "diff");
+}
+
+function pathFromTitle(title?: string): string {
+  if (!title) return "";
+  // Titles look like "Edit src/foo.ts" / "Create /abs/path" — take the last token.
+  const m = title.trim().match(/(\S+)\s*$/);
+  const tok = m?.[1] ?? "";
+  return /[\\/.]/.test(tok) ? tok : "";
+}
+
+/** Display a path relative to the session's cwd when it lives under it. */
+function rel(cwd: string, p: string): string {
+  const np = p.replace(/\\/g, "/");
+  const c = cwd.replace(/\\/g, "/").replace(/\/+$/, "") + "/";
+  return np.startsWith(c) ? np.slice(c.length) : np;
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}

package/src/render/hashtags.ts

@@ -0,0 +1,34 @@
+/**
+ * Searchable Telegram hashtags for a session's messages. Tapping a tag in
+ * Telegram pulls up every message that carries it, so the SAME footer is
+ * appended to every AI-output surface: live streams, Done/error summaries, the
+ * history/unread you see when switching back to a session, and live watch.
+ */
+import { basename } from "node:path";
+
+export interface TagInput {
+  projectName?: string;
+  cwd?: string;
+  sessionId?: string;
+}
+
+/** Sanitise a value into a Telegram-safe hashtag body (letters/digits/_ only). */
+export function tagSafe(v: string): string {
+  const s = v
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 40);
+  return s || "none";
+}
+
+/**
+ * Build the hashtag footer. `#proj_` is always present; `#sess_` is added only
+ * when the session id is known, so partial callers (e.g. a static /history view)
+ * still tag consistently. Order: project · session.
+ */
+export function sessionHashtags(input: TagInput): string {
+  const tags = [`#proj_${tagSafe(input.projectName || basename(input.cwd || "") || "none")}`];
+  if (input.sessionId) tags.push(`#sess_${tagSafe(input.sessionId.slice(0, 8))}`);
+  return tags.join(" ");
+}