@hienlh/ppm 0.9.41 → 0.9.43

package/src/server/index.ts

@@ -15,7 +15,7 @@ import { fsBrowseRoutes } from "./routes/fs-browse.ts";
 import { accountsRoutes } from "./routes/accounts.ts";
 import { proxyRoutes } from "./routes/proxy.ts";
 import { mcpRoutes } from "./routes/mcp.ts";
-import { browserPreviewRoutes } from "./routes/browser-preview.ts";
+import { portForwardingRoutes } from "./routes/port-forwarding.ts";
 import { initAdapters } from "../services/database/init-adapters.ts";
 import { terminalWebSocket } from "./ws/terminal.ts";
 import { chatWebSocket } from "./ws/chat.ts";
@@ -133,8 +133,8 @@ app.route("/proxy", proxyRoutes);
 app.use("/api/*", authMiddleware);
 app.get("/api/auth/check", (c) => c.json(ok(true)));
 
-// Browser preview reverse proxy — proxies to localhost:<port> for iframe embedding
-app.route("/api/preview", browserPreviewRoutes);
+// Port forwarding — starts per-port Cloudflare tunnels
+app.route("/api/preview", portForwardingRoutes);
 
 // Filesystem operations (browse, list, read, write) — consolidated in fs-browse route
 app.route("/api/fs", fsBrowseRoutes);
@@ -477,5 +477,12 @@ if (process.argv.includes("__serve__")) {
     console.error("[ExtService] Startup error:", e);
   });
 
+  // Start PPMBot Telegram poller (if enabled)
+  import("../services/ppmbot/ppmbot-service.ts")
+    .then(({ ppmbotService }) => ppmbotService.start())
+    .catch((e) => {
+      console.error("[ppmbot] Startup error:", e);
+    });
+
   console.log(`Server child ready on port ${port}`);
 }

package/src/server/routes/{browser-preview.ts → port-forwarding.ts}

@@ -3,14 +3,14 @@ import { ok, err } from "../../types/api.ts";
 import { ensureCloudflared } from "../../services/cloudflared.service.ts";
 
 /**
- * Browser preview API — starts per-port Cloudflare Quick Tunnels so the
- * frontend can iframe any localhost dev server without CORS/path issues.
+ * Port forwarding API — starts per-port Cloudflare Quick Tunnels so the
+ * frontend can open any localhost dev server via tunnel URL.
  *
  * POST /api/preview/tunnel { port: 3000 } → { url: "https://xxx.trycloudflare.com" }
  * DELETE /api/preview/tunnel/:port → stops tunnel for that port
  * GET /api/preview/tunnels → list active tunnels
  */
-export const browserPreviewRoutes = new Hono();
+export const portForwardingRoutes = new Hono();
 
 const TUNNEL_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 
@@ -25,7 +25,7 @@ interface ActiveTunnel {
 export const activeTunnels = new Map<number, ActiveTunnel>();
 
 /** Start a tunnel for a localhost port */
-browserPreviewRoutes.post("/tunnel", async (c) => {
+portForwardingRoutes.post("/tunnel", async (c) => {
   const body = await c.req.json<{ port: number }>().catch(() => null);
   const port = body?.port;
   if (!port || port < 1 || port > 65535) {
@@ -95,7 +95,7 @@ browserPreviewRoutes.post("/tunnel", async (c) => {
 });
 
 /** Stop a tunnel */
-browserPreviewRoutes.delete("/tunnel/:port{[0-9]+}", (c) => {
+portForwardingRoutes.delete("/tunnel/:port{[0-9]+}", (c) => {
   const port = parseInt(c.req.param("port"), 10);
   const tunnel = activeTunnels.get(port);
   if (!tunnel) {
@@ -109,7 +109,7 @@ browserPreviewRoutes.delete("/tunnel/:port{[0-9]+}", (c) => {
 });
 
 /** List active tunnels */
-browserPreviewRoutes.get("/tunnels", (c) => {
+portForwardingRoutes.get("/tunnels", (c) => {
   const list = Array.from(activeTunnels.values()).map((t) => ({
     port: t.port,
     url: t.url,
@@ -151,7 +151,7 @@ async function cleanupGhostTunnels() {
 setInterval(cleanupGhostTunnels, 30_000);
 
 /** Cleanup all tunnels on server shutdown */
-export function stopAllPreviewTunnels() {
+export function stopAllPortTunnels() {
   for (const [port, tunnel] of activeTunnels) {
     try { tunnel.process.kill(); } catch {}
     activeTunnels.delete(port);

package/src/server/routes/settings.ts

@@ -1,12 +1,14 @@
 import { Hono } from "hono";
 import { configService } from "../../services/config.service.ts";
-import { getConfigValue, setConfigValue } from "../../services/db.service.ts";
+import { getConfigValue, setConfigValue, listPairedChats, getPairingByCode, approvePairing, revokePairing, getPPMBotMemories, getDb } from "../../services/db.service.ts";
 import {
   validateAIProviderConfig,
   validateDefaultProvider,
   VALID_PROVIDERS,
+  DEFAULT_CONFIG,
   type AIProviderConfig,
   type TelegramConfig,
+  type PPMBotConfig,
   type ThemeConfig,
 } from "../../types/config.ts";
 import { ok, err } from "../../types/api.ts";
@@ -201,50 +203,45 @@ settingsRoutes.put("/keybindings", async (c) => {
   }
 });
 
-// ── Telegram ──────────────────────────────────────────────────────────
+// ── Telegram (bot_token managed via PPMBot settings) ────────────────
 
 /** GET /settings/telegram — return current telegram config (masks bot_token) */
 settingsRoutes.get("/telegram", (c) => {
   const tg = configService.get("telegram") as TelegramConfig | undefined;
-  if (!tg) return c.json(ok({ bot_token: "", chat_id: "" }));
+  if (!tg) return c.json(ok({ bot_token: "" }));
   return c.json(ok({
     bot_token: tg.bot_token ? `${tg.bot_token.slice(0, 6)}...` : "",
-    chat_id: tg.chat_id,
   }));
 });
 
-/** PUT /settings/telegram — save telegram bot_token + chat_id */
+/** PUT /settings/telegram — save telegram bot_token */
 settingsRoutes.put("/telegram", async (c) => {
   try {
-    const body = await c.req.json<{ bot_token?: string; chat_id?: string }>();
-    const current = (configService.get("telegram") as TelegramConfig | undefined) ?? { bot_token: "", chat_id: "" };
+    const body = await c.req.json<{ bot_token?: string }>();
+    const current = (configService.get("telegram") as TelegramConfig | undefined) ?? { bot_token: "" };
     const updated: TelegramConfig = {
       bot_token: body.bot_token ?? current.bot_token,
-      chat_id: body.chat_id ?? current.chat_id,
     };
     configService.set("telegram", updated);
     configService.save();
     return c.json(ok({
       bot_token: updated.bot_token ? `${updated.bot_token.slice(0, 6)}...` : "",
-      chat_id: updated.chat_id,
     }));
   } catch (e) {
     return c.json(err((e as Error).message), 400);
   }
 });
 
-/** POST /settings/telegram/test — send a test message */
+/** POST /settings/telegram/test — send a test notification to all approved paired chats */
 settingsRoutes.post("/telegram/test", async (c) => {
   try {
-    const body = await c.req.json<{ bot_token?: string; chat_id?: string }>();
-    const current = (configService.get("telegram") as TelegramConfig | undefined) ?? { bot_token: "", chat_id: "" };
-    const token = body.bot_token || current.bot_token;
-    const chatId = body.chat_id || current.chat_id;
-    if (!token || !chatId) {
-      return c.json(err("bot_token and chat_id are required"), 400);
+    const current = (configService.get("telegram") as TelegramConfig | undefined) ?? { bot_token: "" };
+    const token = current.bot_token;
+    if (!token) {
+      return c.json(err("Bot token not configured"), 400);
     }
     const { telegramService } = await import("../../services/telegram-notification.service.ts");
-    const result = await telegramService.sendTest(token, chatId);
+    const result = await telegramService.sendTest(token);
     if (!result.ok) return c.json(err(result.error ?? "Failed"), 500);
     return c.json(ok({ sent: true }));
   } catch (e) {
@@ -316,3 +313,91 @@ settingsRoutes.put("/proxy", async (c) => {
     return c.json(err((e as Error).message), 400);
   }
 });
+
+// ── PPMBot ─────────────────────────────────────────────────────
+
+/** GET /settings/clawbot — return current clawbot config */
+settingsRoutes.get("/clawbot", (c) => {
+  const config = configService.get("clawbot") as PPMBotConfig | undefined;
+  if (!config) return c.json(ok(DEFAULT_CONFIG.clawbot));
+  return c.json(ok(config));
+});
+
+/** PUT /settings/clawbot — update clawbot config */
+settingsRoutes.put("/clawbot", async (c) => {
+  try {
+    const body = await c.req.json<Partial<PPMBotConfig>>();
+    const current = (configService.get("clawbot") as PPMBotConfig | undefined)
+      ?? structuredClone(DEFAULT_CONFIG.clawbot!);
+    const updated: PPMBotConfig = { ...current, ...body };
+
+    if (updated.debounce_ms < 0 || updated.debounce_ms > 30000) {
+      return c.json(err("debounce_ms must be 0-30000"), 400);
+    }
+
+    configService.set("clawbot", updated);
+    configService.save();
+
+    // Restart clawbot if running state changed
+    try {
+      const { ppmbotService } = await import("../../services/ppmbot/ppmbot-service.ts");
+      if (updated.enabled && !ppmbotService.isRunning) {
+        await ppmbotService.start();
+      } else if (!updated.enabled && ppmbotService.isRunning) {
+        ppmbotService.stop();
+      }
+    } catch { /* PPMBot module not loaded yet — OK */ }
+
+    return c.json(ok(updated));
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
+/** GET /settings/clawbot/paired — list paired devices */
+settingsRoutes.get("/clawbot/paired", (c) => {
+  return c.json(ok(listPairedChats()));
+});
+
+/** POST /settings/clawbot/paired/approve — approve pairing by code */
+settingsRoutes.post("/clawbot/paired/approve", async (c) => {
+  try {
+    const { code } = await c.req.json<{ code: string }>();
+    const pairing = getPairingByCode(code);
+    if (!pairing) return c.json(err("Invalid pairing code"), 404);
+    approvePairing(pairing.telegram_chat_id);
+    // Notify user on Telegram
+    try {
+      const { ppmbotService } = await import("../../services/ppmbot/ppmbot-service.ts");
+      await ppmbotService.notifyPairingApproved(pairing.telegram_chat_id);
+    } catch { /* OK */ }
+    return c.json(ok({ approved: pairing.telegram_chat_id }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
+/** DELETE /settings/clawbot/paired/:chatId — revoke pairing */
+settingsRoutes.delete("/clawbot/paired/:chatId", (c) => {
+  revokePairing(c.req.param("chatId"));
+  return c.json(ok({ revoked: true }));
+});
+
+/** GET /settings/clawbot/memories?project=xxx — list memories for a project */
+settingsRoutes.get("/clawbot/memories", (c) => {
+  const project = c.req.query("project") || "_global";
+  const memories = getPPMBotMemories(project, 50);
+  return c.json(ok(memories));
+});
+
+/** DELETE /settings/clawbot/memories/:id — delete a specific memory */
+settingsRoutes.delete("/clawbot/memories/:id", (c) => {
+  const id = Number(c.req.param("id"));
+  if (!id) return c.json(err("Invalid memory ID"), 400);
+  try {
+    getDb().query("DELETE FROM clawbot_memories WHERE id = ?").run(id);
+    return c.json(ok({ deleted: id }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});

package/src/services/config.service.ts

@@ -19,7 +19,7 @@ const PPM_DIR = resolve(homedir(), ".ppm");
 
 /** Top-level config keys stored in the config table (not projects) */
 const CONFIG_TABLE_KEYS: (keyof PpmConfig)[] = [
-  "device_name", "port", "host", "theme", "auth", "ai", "push", "telegram",
+  "device_name", "port", "host", "theme", "auth", "ai", "push", "telegram", "clawbot",
 ];
 
 class ConfigService {

package/src/services/db.service.ts

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { mkdirSync, existsSync } from "node:fs";
 
 const PPM_DIR = process.env.PPM_HOME || resolve(homedir(), ".ppm");
-const CURRENT_SCHEMA_VERSION = 12;
+const CURRENT_SCHEMA_VERSION = 13;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -313,6 +313,80 @@ function runMigrations(database: Database): void {
       PRAGMA user_version = 12;
     `);
   }
+
+  if (current < 13) {
+    database.exec(`
+      CREATE TABLE IF NOT EXISTS clawbot_sessions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        telegram_chat_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        provider_id TEXT NOT NULL DEFAULT 'claude',
+        project_name TEXT NOT NULL,
+        project_path TEXT NOT NULL,
+        is_active INTEGER NOT NULL DEFAULT 1,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        last_message_at INTEGER NOT NULL DEFAULT (unixepoch())
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_clawbot_sessions_chat
+        ON clawbot_sessions(telegram_chat_id, is_active);
+      CREATE INDEX IF NOT EXISTS idx_clawbot_sessions_session
+        ON clawbot_sessions(session_id);
+
+      CREATE TABLE IF NOT EXISTS clawbot_memories (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        project TEXT NOT NULL,
+        content TEXT NOT NULL,
+        category TEXT NOT NULL DEFAULT 'fact',
+        importance REAL NOT NULL DEFAULT 1.0,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        session_id TEXT,
+        superseded_by INTEGER REFERENCES clawbot_memories(id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_clawbot_memories_project
+        ON clawbot_memories(project, superseded_by);
+      CREATE INDEX IF NOT EXISTS idx_clawbot_memories_importance
+        ON clawbot_memories(importance DESC);
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS clawbot_memories_fts USING fts5(
+        content,
+        content='clawbot_memories',
+        content_rowid='id'
+      );
+
+      -- FTS5 sync triggers
+      CREATE TRIGGER IF NOT EXISTS clawbot_memories_ai AFTER INSERT ON clawbot_memories BEGIN
+        INSERT INTO clawbot_memories_fts(rowid, content) VALUES (new.id, new.content);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS clawbot_memories_ad AFTER DELETE ON clawbot_memories BEGIN
+        INSERT INTO clawbot_memories_fts(clawbot_memories_fts, rowid, content) VALUES('delete', old.id, old.content);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS clawbot_memories_au AFTER UPDATE ON clawbot_memories BEGIN
+        INSERT INTO clawbot_memories_fts(clawbot_memories_fts, rowid, content) VALUES('delete', old.id, old.content);
+        INSERT INTO clawbot_memories_fts(rowid, content) VALUES (new.id, new.content);
+      END;
+
+      CREATE TABLE IF NOT EXISTS clawbot_paired_chats (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        telegram_chat_id TEXT NOT NULL UNIQUE,
+        telegram_user_id TEXT,
+        display_name TEXT,
+        pairing_code TEXT,
+        status TEXT NOT NULL DEFAULT 'pending',
+        created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        approved_at INTEGER
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_clawbot_paired_status
+        ON clawbot_paired_chats(status);
+
+      PRAGMA user_version = 13;
+    `);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -894,5 +968,215 @@ export function deleteExtensionStorage(extId: string): void {
   getDb().query("DELETE FROM extension_storage WHERE ext_id = ?").run(extId);
 }
 
+// ---------------------------------------------------------------------------
+// PPMBot session helpers
+// ---------------------------------------------------------------------------
+
+import type { PPMBotSessionRow, PPMBotMemoryRow, PPMBotPairedChat } from "../types/ppmbot.ts";
+
+export function getActivePPMBotSession(
+  telegramChatId: string,
+  projectName: string,
+): PPMBotSessionRow | null {
+  return getDb().query(
+    `SELECT * FROM clawbot_sessions
+     WHERE telegram_chat_id = ? AND project_name = ? AND is_active = 1
+     ORDER BY last_message_at DESC LIMIT 1`,
+  ).get(telegramChatId, projectName) as PPMBotSessionRow | null;
+}
+
+export function createPPMBotSession(
+  telegramChatId: string,
+  sessionId: string,
+  providerId: string,
+  projectName: string,
+  projectPath: string,
+): void {
+  getDb().query(
+    `INSERT INTO clawbot_sessions
+     (telegram_chat_id, session_id, provider_id, project_name, project_path)
+     VALUES (?, ?, ?, ?, ?)`,
+  ).run(telegramChatId, sessionId, providerId, projectName, projectPath);
+}
+
+export function deactivatePPMBotSession(sessionId: string): void {
+  getDb().query(
+    "UPDATE clawbot_sessions SET is_active = 0 WHERE session_id = ?",
+  ).run(sessionId);
+}
+
+export function touchPPMBotSession(sessionId: string): void {
+  getDb().query(
+    "UPDATE clawbot_sessions SET last_message_at = unixepoch() WHERE session_id = ?",
+  ).run(sessionId);
+}
+
+export function getRecentPPMBotSessions(
+  telegramChatId: string,
+  limit = 10,
+): PPMBotSessionRow[] {
+  return getDb().query(
+    `SELECT * FROM clawbot_sessions
+     WHERE telegram_chat_id = ?
+     ORDER BY last_message_at DESC LIMIT ?`,
+  ).all(telegramChatId, limit) as PPMBotSessionRow[];
+}
+
+// ---------------------------------------------------------------------------
+// PPMBot memory helpers
+// ---------------------------------------------------------------------------
+
+export function insertPPMBotMemory(
+  project: string,
+  content: string,
+  category: string,
+  importance: number,
+  sessionId?: string,
+): number {
+  const result = getDb().query(
+    `INSERT INTO clawbot_memories (project, content, category, importance, session_id)
+     VALUES (?, ?, ?, ?, ?)`,
+  ).run(project, content, category, importance, sessionId ?? null);
+  return Number(result.lastInsertRowid);
+}
+
+export function searchPPMBotMemories(
+  project: string,
+  query: string,
+  limit = 20,
+): Array<PPMBotMemoryRow & { rank: number }> {
+  return getDb().query(
+    `SELECT m.*, fts.rank
+     FROM clawbot_memories m
+     JOIN clawbot_memories_fts fts ON m.id = fts.rowid
+     WHERE clawbot_memories_fts MATCH ?
+       AND m.project IN (?, '_global')
+       AND m.superseded_by IS NULL
+     ORDER BY fts.rank
+     LIMIT ?`,
+  ).all(query, project, limit) as Array<PPMBotMemoryRow & { rank: number }>;
+}
+
+export function getPPMBotMemories(
+  project: string,
+  limit = 20,
+): PPMBotMemoryRow[] {
+  return getDb().query(
+    `SELECT * FROM clawbot_memories
+     WHERE project IN (?, '_global')
+       AND superseded_by IS NULL
+     ORDER BY importance DESC, updated_at DESC
+     LIMIT ?`,
+  ).all(project, limit) as PPMBotMemoryRow[];
+}
+
+export function supersedePPMBotMemory(
+  oldId: number,
+  newId: number,
+): void {
+  getDb().query(
+    "UPDATE clawbot_memories SET superseded_by = ? WHERE id = ?",
+  ).run(newId, oldId);
+}
+
+export function deletePPMBotMemoriesByTopic(
+  project: string,
+  topic: string,
+): number {
+  const matches = getDb().query(
+    `SELECT m.id FROM clawbot_memories m
+     JOIN clawbot_memories_fts fts ON m.id = fts.rowid
+     WHERE clawbot_memories_fts MATCH ?
+       AND m.project IN (?, '_global')
+       AND m.superseded_by IS NULL`,
+  ).all(topic, project) as { id: number }[];
+
+  for (const row of matches) {
+    getDb().query("DELETE FROM clawbot_memories WHERE id = ?").run(row.id);
+  }
+  return matches.length;
+}
+
+export function decayPPMBotMemories(): void {
+  getDb().query(
+    `UPDATE clawbot_memories
+     SET importance = importance * 0.95,
+         updated_at = unixepoch()
+     WHERE superseded_by IS NULL
+       AND category NOT IN ('preference', 'architecture')
+       AND updated_at < unixepoch() - 604800`,
+  ).run();
+  getDb().query(
+    `DELETE FROM clawbot_memories WHERE importance < 0.1 AND superseded_by IS NULL`,
+  ).run();
+}
+
+// ---------------------------------------------------------------------------
+// PPMBot pairing helpers
+// ---------------------------------------------------------------------------
+
+export function createPairingRequest(
+  chatId: string,
+  userId: string,
+  displayName: string,
+  code: string,
+): void {
+  getDb().query(
+    `INSERT INTO clawbot_paired_chats (telegram_chat_id, telegram_user_id, display_name, pairing_code, status)
+     VALUES (?, ?, ?, ?, 'pending')
+     ON CONFLICT(telegram_chat_id) DO UPDATE SET
+       telegram_user_id = excluded.telegram_user_id,
+       display_name = excluded.display_name,
+       pairing_code = excluded.pairing_code,
+       status = 'pending',
+       approved_at = NULL`,
+  ).run(chatId, userId, displayName, code);
+}
+
+export function approvePairing(chatId: string): void {
+  getDb().query(
+    `UPDATE clawbot_paired_chats
+     SET status = 'approved', pairing_code = NULL, approved_at = unixepoch()
+     WHERE telegram_chat_id = ? AND status = 'pending'`,
+  ).run(chatId);
+}
+
+export function revokePairing(chatId: string): void {
+  getDb().query(
+    "UPDATE clawbot_paired_chats SET status = 'revoked' WHERE telegram_chat_id = ?",
+  ).run(chatId);
+}
+
+export function getPairingByCode(code: string): PPMBotPairedChat | null {
+  return getDb().query(
+    "SELECT * FROM clawbot_paired_chats WHERE pairing_code = ? AND status = 'pending'",
+  ).get(code) as PPMBotPairedChat | null;
+}
+
+export function getPairingByChatId(chatId: string): PPMBotPairedChat | null {
+  return getDb().query(
+    "SELECT * FROM clawbot_paired_chats WHERE telegram_chat_id = ?",
+  ).get(chatId) as PPMBotPairedChat | null;
+}
+
+export function listPairedChats(): PPMBotPairedChat[] {
+  return getDb().query(
+    "SELECT * FROM clawbot_paired_chats WHERE status != 'revoked' ORDER BY created_at DESC",
+  ).all() as PPMBotPairedChat[];
+}
+
+export function getApprovedPairedChats(): PPMBotPairedChat[] {
+  return getDb().query(
+    "SELECT * FROM clawbot_paired_chats WHERE status = 'approved' ORDER BY created_at DESC",
+  ).all() as PPMBotPairedChat[];
+}
+
+export function isPairedChat(chatId: string): boolean {
+  const row = getDb().query(
+    "SELECT 1 FROM clawbot_paired_chats WHERE telegram_chat_id = ? AND status = 'approved'",
+  ).get(chatId);
+  return row != null;
+}
+
 // Auto-close on process exit
 process.on("beforeExit", closeDb);

package/src/services/ppmbot/ppmbot-formatter.ts

@@ -0,0 +1,88 @@
+const MAX_MESSAGE_LENGTH = 4096;
+
+/** Escape HTML special chars for Telegram HTML parse mode */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Convert Markdown to Telegram-compatible HTML.
+ * Handles: **bold**, *italic*, `code`, ```pre```, [links](url), ~~strikethrough~~
+ * Does NOT handle nested formatting (Telegram limitation).
+ */
+export function markdownToTelegramHtml(md: string): string {
+  let html = md;
+
+  // Code blocks first (prevent inner processing)
+  html = html.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, lang, code) => {
+    const langAttr = lang ? ` class="language-${escapeHtml(lang)}"` : "";
+    return `<pre><code${langAttr}>${escapeHtml(code.trimEnd())}</code></pre>`;
+  });
+
+  // Inline code: `code` → <code>code</code>
+  html = html.replace(/`([^`\n]+)`/g, (_match, code) => {
+    return `<code>${escapeHtml(code)}</code>`;
+  });
+
+  // Bold: **text** → <b>text</b>
+  html = html.replace(/\*\*(.+?)\*\*/g, "<b>$1</b>");
+
+  // Italic: *text* → <i>text</i>
+  html = html.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, "<i>$1</i>");
+
+  // Strikethrough: ~~text~~ → <s>text</s>
+  html = html.replace(/~~(.+?)~~/g, "<s>$1</s>");
+
+  // Links: [text](url) → <a href="url">text</a>
+  html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+  return html;
+}
+
+/**
+ * Split text into chunks that fit Telegram's 4096 char limit.
+ * Tries to break at newlines, falling back to word boundaries.
+ */
+export function chunkMessage(text: string, maxLen = MAX_MESSAGE_LENGTH): string[] {
+  if (text.length <= maxLen) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLen) {
+      chunks.push(remaining);
+      break;
+    }
+
+    let breakAt = -1;
+    const searchWindow = remaining.slice(0, maxLen);
+
+    // Try double newline
+    breakAt = searchWindow.lastIndexOf("\n\n");
+    if (breakAt === -1 || breakAt < maxLen * 0.3) {
+      breakAt = searchWindow.lastIndexOf("\n");
+    }
+    if (breakAt === -1 || breakAt < maxLen * 0.3) {
+      breakAt = searchWindow.lastIndexOf(" ");
+    }
+    if (breakAt === -1 || breakAt < maxLen * 0.3) {
+      breakAt = maxLen;
+    }
+
+    chunks.push(remaining.slice(0, breakAt));
+    remaining = remaining.slice(breakAt).trimStart();
+  }
+
+  return chunks;
+}
+
+/** Truncate text for preview (e.g. session titles), adding ellipsis */
+export function truncateForPreview(text: string, maxLen = 200): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 1) + "\u2026";
+}