@aaroncql/pim-agent 0.3.0 → 0.5.0

package/README.md

@@ -232,7 +232,7 @@ For development, run standalone with `pim --mode telegram` instead.
 
 - ⏰ **Scheduled tasks** - your bot can create one-time, interval, or cron-based tasks that fire automatically; ask your bot to schedule something.
 - 👀 **Live progress logs** - use `/logs` to choose what you see while the agent works: final replies, tool use, intermediate text, or thinking.
-- 📝 **Markdown formatting** - replies render Markdown out of the box, including tables converted to vertical lists for Telegram.
+- 📝 **Rich Markdown** - supports Telegram's [rich text formatting](https://telegram.org/blog/watch-apps-and-more#obscenely-rich-text-formatting-for-bots) with full markdown and LaTeX math support.
 - 📎 **Rich media** - send photos, documents, videos, audio, and voice messages directly in chat; your bot can also send files back to you.
 - 🧵 **Thread-specific prompts** - each chat (or thread) gets its own session and optional instructions; ask your bot to modify its instructions.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaroncql/pim-agent",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A Bun-native extension pack for Pi: web access, subagents, revamped core tools, ANSI-compatible themes, fzf-style completions, Telegram mode, and more.",
   "license": "MIT",
   "type": "module",
@@ -57,7 +57,7 @@
   "dependencies": {
     "diff": "^9.0.0",
     "fzf": "^0.5.2",
-    "grammy": "^1.43.0",
+    "grammy": "^1.44.0",
     "ignore": "^7.0.5",
     "ky": "^2.0.2"
   }

package/src/extensions/web-search/ExaMcpClient.ts

@@ -1,9 +1,11 @@
 import { McpClient, type McpFetch } from "../../shared/McpClient";
+import { RateLimiter } from "../../shared/RateLimiter";
 
 type ExaMcpClientOptions = {
   readonly endpoint?: string;
   readonly apiKey?: string;
   readonly fetch?: McpFetch;
+  readonly rateLimiter?: RateLimiter;
 };
 
 type ExaSearchInput = {
@@ -28,15 +30,30 @@ class ExaSearchError extends Error {
 export class ExaMcpClient {
   private static readonly defaultEndpoint = "https://mcp.exa.ai/mcp";
   private static readonly toolName = "web_search_exa";
+  private static readonly maxRequestsPerWindow = 3;
+  private static readonly windowMs = 1000;
 
   private readonly client: McpClient;
 
   public constructor(options: ExaMcpClientOptions = {}) {
+    const apiKey =
+      options.apiKey === undefined || options.apiKey.length === 0
+        ? undefined
+        : options.apiKey;
+    // Throttle only on the free tier; an API key lifts the request rate limit.
+    const rateLimiter =
+      apiKey !== undefined
+        ? undefined
+        : (options.rateLimiter ??
+          new RateLimiter({
+            maxRequests: ExaMcpClient.maxRequestsPerWindow,
+            windowMs: ExaMcpClient.windowMs,
+          }));
+
     this.client = new McpClient({
       endpoint: options.endpoint ?? ExaMcpClient.defaultEndpoint,
-      ...(options.apiKey === undefined || options.apiKey.length === 0
-        ? {}
-        : { headers: { "x-api-key": options.apiKey } }),
+      ...(apiKey === undefined ? {} : { headers: { "x-api-key": apiKey } }),
+      ...(rateLimiter === undefined ? {} : { rateLimiter }),
       ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
     });
   }

package/src/shared/McpClient.ts

@@ -1,4 +1,5 @@
 import ky, { HTTPError, type KyInstance } from "ky";
+import type { RateLimiter } from "./RateLimiter";
 
 export type McpFetch = (
   input: Parameters<typeof fetch>[0],
@@ -11,6 +12,7 @@ export type McpClientOptions = {
   readonly fetch?: McpFetch;
   readonly clientName?: string;
   readonly clientVersion?: string;
+  readonly rateLimiter?: RateLimiter;
 };
 
 export type CallToolInput = {
@@ -26,9 +28,12 @@ type JsonRpcResponse = {
 };
 
 export class McpClientError extends Error {
-  public constructor(message: string) {
+  public readonly status: number | undefined;
+
+  public constructor(message: string, status?: number) {
     super(message);
     this.name = "McpClientError";
+    this.status = status;
   }
 }
 
@@ -40,13 +45,16 @@ export class McpClient {
   private readonly clientName: string;
   private readonly clientVersion: string;
   private readonly ky: KyInstance;
+  private readonly rateLimiter: RateLimiter | undefined;
   private nextRequestId = 1;
+  private sessionPromise: Promise<string | undefined> | undefined;
 
   public constructor(options: McpClientOptions) {
     this.endpoint = options.endpoint;
     this.extraHeaders = options.headers ?? {};
     this.clientName = options.clientName ?? "pim-agent";
     this.clientVersion = options.clientVersion ?? "0.0.0";
+    this.rateLimiter = options.rateLimiter;
     this.ky = ky.create(
       options.fetch === undefined
         ? {}
@@ -55,35 +63,75 @@ export class McpClient {
   }
 
   public async callTool(input: CallToolInput): Promise<unknown> {
-    let sessionId: string | undefined;
-    let activeRequestId: number | undefined;
+    const pending = this.ensureSession();
+    const sessionId = await pending;
 
     try {
-      activeRequestId = this.nextRequestId++;
-      const initialize = await this.sendRpcRequest({
-        id: activeRequestId,
-        method: "initialize",
-        params: {
-          protocolVersion: McpClient.protocolVersion,
-          clientInfo: {
-            name: this.clientName,
-            version: this.clientVersion,
-          },
-          capabilities: {},
+      return await this.invokeTool(input, sessionId);
+    } catch (error) {
+      if (
+        input.signal?.aborted ||
+        sessionId === undefined ||
+        !isStaleSessionError(error)
+      ) {
+        throw error;
+      }
+
+      this.invalidateSession(pending);
+
+      return this.invokeTool(input, await this.ensureSession());
+    }
+  }
+
+  private ensureSession(): Promise<string | undefined> {
+    const pending = (this.sessionPromise ??= this.handshake().catch(
+      (error: unknown) => {
+        this.invalidateSession(pending);
+        throw error;
+      }
+    ));
+
+    return pending;
+  }
+
+  private invalidateSession(pending: Promise<string | undefined>): void {
+    if (this.sessionPromise === pending) {
+      this.sessionPromise = undefined;
+    }
+  }
+
+  private async handshake(): Promise<string | undefined> {
+    const initialize = await this.sendRpcRequest({
+      id: this.nextRequestId++,
+      method: "initialize",
+      params: {
+        protocolVersion: McpClient.protocolVersion,
+        clientInfo: {
+          name: this.clientName,
+          version: this.clientVersion,
         },
-        ...(input.signal === undefined ? {} : { signal: input.signal }),
-      });
-      sessionId = initialize.sessionId;
+        capabilities: {},
+      },
+    });
 
-      await this.sendNotification({
-        sessionId,
-        method: "notifications/initialized",
-        params: {},
-      });
+    await this.sendNotification({
+      sessionId: initialize.sessionId,
+      method: "notifications/initialized",
+      params: {},
+    });
 
-      activeRequestId = this.nextRequestId++;
+    return initialize.sessionId;
+  }
+
+  private async invokeTool(
+    input: CallToolInput,
+    sessionId: string | undefined
+  ): Promise<unknown> {
+    const requestId = this.nextRequestId++;
+
+    try {
       const toolCall = await this.sendRpcRequest({
-        id: activeRequestId,
+        id: requestId,
         ...(sessionId === undefined ? {} : { sessionId }),
         method: "tools/call",
         params: {
@@ -96,7 +144,7 @@ export class McpClient {
       return toolCall.envelope.result;
     } catch (error) {
       if (input.signal?.aborted) {
-        await this.sendCancellation(sessionId, activeRequestId);
+        await this.sendCancellation(sessionId, requestId);
         throw new McpClientError("MCP request aborted.");
       }
 
@@ -141,6 +189,7 @@ export class McpClient {
     readonly sessionId: string | undefined;
     readonly method: string;
     readonly params: Readonly<Record<string, unknown>>;
+    readonly rateLimited?: boolean;
   }): Promise<void> {
     await this.postJson(
       {
@@ -148,7 +197,9 @@ export class McpClient {
         method: input.method,
         params: input.params,
       },
-      input.sessionId
+      input.sessionId,
+      undefined,
+      input.rateLimited ?? true
     );
   }
 
@@ -168,6 +219,7 @@ export class McpClient {
           requestId,
           reason: "Tool call aborted.",
         },
+        rateLimited: false,
       });
     } catch {
       // abort already surfaces; cancel is best-effort
@@ -177,8 +229,13 @@ export class McpClient {
   private async postJson(
     body: Readonly<Record<string, unknown>>,
     sessionId?: string,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    rateLimited = true
   ): Promise<Response> {
+    if (rateLimited) {
+      await this.rateLimiter?.acquire();
+    }
+
     try {
       return await this.ky(this.endpoint, {
         method: "POST",
@@ -193,7 +250,8 @@ export class McpClient {
 
       if (error instanceof HTTPError) {
         throw new McpClientError(
-          `MCP request failed with HTTP ${error.response.status}: ${excerpt(stringifyErrorData(error.data))}`
+          `MCP request failed with HTTP ${error.response.status}: ${excerpt(stringifyErrorData(error.data))}`,
+          error.response.status
         );
       }
 
@@ -330,6 +388,10 @@ export class McpClient {
   }
 }
 
+function isStaleSessionError(error: unknown): boolean {
+  return error instanceof McpClientError && error.status === 404;
+}
+
 function asRecord(
   value: unknown
 ): Readonly<Record<string, unknown>> | undefined {

package/src/shared/RateLimiter.ts

@@ -0,0 +1,50 @@
+export type RateLimiterOptions = {
+  readonly maxRequests: number;
+  readonly windowMs: number;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+};
+
+export class RateLimiter {
+  private readonly maxRequests: number;
+  private readonly windowMs: number;
+  private readonly now: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly timestamps: number[] = [];
+  private tail: Promise<void> = Promise.resolve();
+
+  public constructor(options: RateLimiterOptions) {
+    this.maxRequests = Math.max(1, options.maxRequests);
+    this.windowMs = options.windowMs;
+    this.now = options.now ?? Date.now;
+    this.sleep = options.sleep ?? ((ms) => Bun.sleep(ms));
+  }
+
+  public acquire(): Promise<void> {
+    const reserved = this.tail.then(() => this.reserve());
+    this.tail = reserved.catch(() => {});
+
+    return reserved;
+  }
+
+  private async reserve(): Promise<void> {
+    while (true) {
+      const now = this.now();
+      const threshold = now - this.windowMs;
+
+      while (this.timestamps.length > 0 && this.timestamps[0]! <= threshold) {
+        this.timestamps.shift();
+      }
+
+      if (this.timestamps.length < this.maxRequests) {
+        this.timestamps.push(now);
+
+        return;
+      }
+
+      const waitMs = this.timestamps[0]! + this.windowMs - now;
+
+      await this.sleep(Math.max(0, waitMs));
+    }
+  }
+}

package/src/telegram/Markdown.ts

@@ -1,22 +1,37 @@
+type Align = "left" | "center" | "right";
+
 type TableRow = ReadonlyArray<string>;
 
 type Segment =
   | { readonly kind: "md"; readonly text: string }
-  | { readonly kind: "table"; readonly rows: ReadonlyArray<TableRow> };
+  | {
+      readonly kind: "table";
+      readonly rows: ReadonlyArray<TableRow>;
+      readonly aligns: ReadonlyArray<Align | undefined>;
+    };
+
+type RenderOptions = {
+  readonly italics?: boolean;
+};
 
 const SAFE_LINK = /^(https?:|tg:|mailto:)/i;
 
+// Bun's GFM strikethrough strikes on a lone `~`, but Telegram (and CommonMark)
+// only strike on `~~`. We disable the parser's strikethrough and re-apply
+// double-tilde runs in the text callback, where code spans/blocks never reach.
+const STRIKETHROUGH = /(?<!~)~~(?!~)((?:[^~]|~(?!~))+?)~~(?!~)/g;
+
 export class Markdown {
-  public static toHtml(md: string): string {
+  public static toHtml(md: string, options: RenderOptions = {}): string {
     const segments = Markdown.split(md);
     let out = "";
     for (const seg of segments) {
       out +=
         seg.kind === "md"
-          ? Markdown.renderMd(seg.text)
-          : Markdown.renderTable(seg.rows);
+          ? Markdown.renderMd(seg.text, options)
+          : Markdown.renderTable(seg.rows, seg.aligns);
     }
-    return out.replace(/\n{3,}/g, "\n\n").trim();
+    return out.trim();
   }
 
   public static escape(s: string): string {
@@ -28,22 +43,27 @@ export class Markdown {
   }
 
   private static readonly RENDERERS = {
-    text: (c: string): string => Markdown.escape(c),
-    paragraph: (c: string): string => `${c}\n\n`,
-    heading: (c: string, meta?: { level?: number }): string =>
-      meta?.level === 1 ? `<u><b>${c}</b></u>\n\n` : `<b>${c}</b>\n\n`,
+    text: (c: string): string =>
+      Markdown.escape(c).replace(STRIKETHROUGH, "<s>$1</s>"),
+    paragraph: (c: string): string => `<p>${c}</p>`,
+    heading: (c: string, meta?: { level?: number }): string => {
+      const level = Math.min(6, Math.max(1, meta?.level ?? 1));
+      return `<h${level}>${c}</h${level}>`;
+    },
     strong: (c: string): string => `<b>${c}</b>`,
     emphasis: (c: string): string => `<i>${c}</i>`,
-    strikethrough: (c: string): string => `<s>${c}</s>`,
     codespan: (c: string): string => `<code>${c}</code>`,
     code: (c: string, meta?: { language?: string }): string => {
       const body = c.replace(/\n+$/, "");
       const lang = meta?.language;
+      if (lang === "math") {
+        return `<tg-math-block>${body}</tg-math-block>`;
+      }
       const open = lang
         ? `<pre><code class="language-${Markdown.escape(lang)}">`
         : "<pre>";
       const close = lang ? "</code></pre>" : "</pre>";
-      return `${open}${body}${close}\n\n`;
+      return `${open}${body}${close}`;
     },
     link: (c: string, meta?: { href?: string }): string => {
       const href = meta?.href ?? "";
@@ -58,46 +78,79 @@ export class Markdown {
         ? `<a href="${Markdown.escape(src)}">${alt}</a>`
         : alt;
     },
-    blockquote: (c: string): string =>
-      `<blockquote>${c.replace(/\n+$/, "")}</blockquote>\n\n`,
-    list: (c: string, meta?: { depth?: number }): string =>
-      (meta?.depth ?? 0) > 0 ? `\n${c}` : `${c}\n`,
-    listItem: (
-      c: string,
-      meta?: {
-        depth?: number;
-        ordered?: boolean;
-        index?: number;
-        checked?: boolean;
+    blockquote: (c: string): string => `<blockquote>${c}</blockquote>`,
+    list: (c: string, meta?: { ordered?: boolean; start?: number }): string => {
+      if (meta?.ordered) {
+        const start = meta.start ?? 1;
+        const startAttr = start > 1 ? ` start="${start}"` : "";
+        return `<ol${startAttr}>${c}</ol>`;
       }
-    ): string => {
-      const depth = meta?.depth ?? 0;
-      const ordered = meta?.ordered ?? false;
-      const index = meta?.index ?? 0;
-      const checked = meta?.checked;
-      const indent = "    ".repeat(depth);
-      let marker: string;
-      if (checked === true) {
-        marker = "✅";
-      } else if (checked === false) {
-        marker = "⬜";
-      } else if (ordered) {
-        marker = `${index + 1}.`;
-      } else {
-        marker = depth === 0 ? "•" : "◦";
-      }
-      return `${indent}${marker} ${c.replace(/\n+$/, "")}\n`;
+      return `<ul>${c}</ul>`;
     },
-    hr: (): string => "───\n\n",
-    br: (): string => "\n",
+    listItem: (c: string, meta?: { checked?: boolean }): string =>
+      Markdown.listItemHtml(c.replace(/\n+$/, ""), meta?.checked),
+    hr: (): string => "<hr/>",
+    br: (): string => "<br>",
     table: (c: string): string => c,
   };
 
-  private static renderMd(md: string): string {
+  private static readonly ITALIC_RENDERERS = {
+    ...Markdown.RENDERERS,
+    paragraph: (c: string): string => `<p>${Markdown.italic(c)}</p>`,
+    heading: (c: string, meta?: { level?: number }): string => {
+      const level = Math.min(6, Math.max(1, meta?.level ?? 1));
+      return `<h${level}>${Markdown.italic(c)}</h${level}>`;
+    },
+    listItem: (c: string, meta?: { checked?: boolean }): string =>
+      Markdown.listItemHtml(
+        Markdown.italicListItemBody(c.replace(/\n+$/, "")),
+        meta?.checked
+      ),
+  };
+
+  private static listItemHtml(body: string, checked?: boolean): string {
+    if (checked === true) {
+      return `<li><input type="checkbox" checked> ${body}</li>`;
+    }
+    if (checked === false) {
+      return `<li><input type="checkbox"> ${body}</li>`;
+    }
+    return `<li>${body}</li>`;
+  }
+
+  private static renderMd(md: string, options: RenderOptions = {}): string {
     if (!md.trim()) {
       return "";
     }
-    return Bun.markdown.render(md, Markdown.RENDERERS);
+    return Bun.markdown.render(md, Markdown.renderers(options), {
+      strikethrough: false,
+    });
+  }
+
+  private static renderers(options: RenderOptions): typeof Markdown.RENDERERS {
+    return options.italics ? Markdown.ITALIC_RENDERERS : Markdown.RENDERERS;
+  }
+
+  private static italic(text: string): string {
+    return text ? `<i>${text}</i>` : "";
+  }
+
+  // A nested list is appended to its parent item's content, so italicize only
+  // the leading text; wrapping a child <ul>/<ol> in <i> would be invalid.
+  private static italicListItemBody(body: string): string {
+    const nestedListIndex = body.search(/<(?:ul|ol)\b/);
+    if (nestedListIndex < 0) {
+      return Markdown.italic(body);
+    }
+    const before = body.slice(0, nestedListIndex);
+    return `${Markdown.italic(before)}${body.slice(nestedListIndex)}`;
+  }
+
+  private static renderInline(md: string): string {
+    return Markdown.renderMd(md)
+      .replace(/^<p>/, "")
+      .replace(/<\/p>$/, "")
+      .trim();
   }
 
   private static split(md: string): ReadonlyArray<Segment> {
@@ -122,12 +175,13 @@ export class Markdown {
       ) {
         flushMd();
         const rows: string[][] = [Markdown.parseRow(line)];
+        const aligns = Markdown.parseAligns(next);
         i += 1;
         while (i + 1 < lines.length && Markdown.isPipeLine(lines[i + 1]!)) {
           i += 1;
           rows.push(Markdown.parseRow(lines[i]!));
         }
-        segments.push({ kind: "table", rows });
+        segments.push({ kind: "table", rows, aligns });
         continue;
       }
       buf.push(line);
@@ -149,7 +203,27 @@ export class Markdown {
     return trimmed.split("|").map((cell) => cell.trim());
   }
 
-  private static renderTable(rows: ReadonlyArray<TableRow>): string {
+  private static parseAligns(sep: string): (Align | undefined)[] {
+    return Markdown.parseRow(sep).map((cell) => {
+      const left = cell.startsWith(":");
+      const right = cell.endsWith(":");
+      if (left && right) {
+        return "center";
+      }
+      if (right) {
+        return "right";
+      }
+      if (left) {
+        return "left";
+      }
+      return undefined;
+    });
+  }
+
+  private static renderTable(
+    rows: ReadonlyArray<TableRow>,
+    aligns: ReadonlyArray<Align | undefined>
+  ): string {
     if (rows.length < 2) {
       return "";
     }
@@ -158,20 +232,24 @@ export class Markdown {
     if (dataRows.length === 0) {
       return "";
     }
-    const pieces: string[] = [];
+    const attr = (col: number): string => {
+      const align = aligns[col];
+      return align ? ` align="${align}"` : "";
+    };
+    const cells = (row: TableRow, tag: "th" | "td"): string =>
+      header
+        .map(
+          (_, c) =>
+            `<${tag}${attr(c)}>${Markdown.renderInline(row[c] ?? "")}</${tag}>`
+        )
+        .join("");
+
+    let out = "<table>";
+    out += `<tr>${cells(header, "th")}</tr>`;
     for (const row of dataRows) {
-      pieces.push("───");
-      for (let c = 0; c < header.length; c++) {
-        const label = Markdown.renderMd(header[c] ?? "").trim();
-        const value = Markdown.renderMd(row[c] ?? "").trim();
-        if (label) {
-          pieces.push(`<b>${label}</b>: ${value}`);
-        } else if (value) {
-          pieces.push(value);
-        }
-      }
+      out += `<tr>${cells(row, "td")}</tr>`;
     }
-    pieces.push("───");
-    return `${pieces.join("\n")}\n\n`;
+    out += "</table>";
+    return out;
   }
 }

package/src/telegram/Renderer.ts

@@ -54,7 +54,32 @@ const TOOL_EMOJI: Record<string, string> = {
   subagent: "🤖",
 };
 
-const MESSAGE_LIMIT = 4000;
+const MESSAGE_LIMIT = 32000;
+const BR = "<br>";
+const BLOCK_TAGS = new Set([
+  "blockquote",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "ol",
+  "p",
+  "pre",
+  "table",
+  "tg-math-block",
+  "ul",
+]);
+const VOID_BLOCK_TAGS = new Set(["br", "hr"]);
+
+type HtmlTag = {
+  readonly start: number;
+  readonly end: number;
+  readonly name: string;
+  readonly closing: boolean;
+  readonly selfClosing: boolean;
+};
 
 export class Renderer {
   private readonly api: Api;
@@ -432,7 +457,7 @@ export class Renderer {
       if (entry.kind === "todo") {
         pieces.push(`${entry.emoji} <b>${Markdown.escape(entry.label)}</b>`);
       } else if (entry.kind === "thinking") {
-        pieces.push(`<i>${Markdown.toHtml(entry.label)}</i>`);
+        pieces.push(Markdown.toHtml(entry.label, { italics: true }));
       } else if (entry.kind === "narration") {
         pieces.push(Markdown.toHtml(entry.label));
       } else {
@@ -447,18 +472,16 @@ export class Renderer {
         pieces.push(`${entry.emoji} ${entry.label}${stats}${suffix}`);
       }
       const next = visible[i + 1];
-      if (next) {
-        pieces.push(
-          entry.kind === "tool" && next.kind === "tool" ? "\n" : "\n\n"
-        );
+      if (next && entry.kind === "tool" && next.kind === "tool") {
+        pieces.push(BR);
       }
     }
 
     let body = pieces.join("");
     if (state === "cancelled") {
-      body += "\n\n❌ Cancelled";
+      body += "<br><br>❌ Cancelled";
     } else if (state === "error") {
-      body += "\n\n❌ Error";
+      body += "<br><br>❌ Error";
     }
     return Renderer.capStatus(body);
   }
@@ -477,47 +500,41 @@ export class Renderer {
     if (!html) {
       return undefined;
     }
-    const other = {
-      parse_mode: "HTML" as const,
-      message_thread_id: this.sessionId.threadId,
-      link_preview_options: { is_disabled: true },
-    };
+    const clean = Renderer.sanitize(html);
     try {
-      const msg = await this.api.sendMessage(
+      const msg = await this.api.sendRichMessage(
         this.sessionId.chatId,
-        Renderer.sanitize(html),
-        other
+        { html: clean },
+        { message_thread_id: this.sessionId.threadId }
       );
       console.log(
-        `[send] chatId=${this.sessionId.chatId} threadId=${this.sessionId.threadId ?? "main"} ${opts.status ? "status" : "answer"} ok (${html.length}b)`
+        `[send] chatId=${this.sessionId.chatId} threadId=${this.sessionId.threadId ?? "main"} ${opts.status ? "status" : "answer"} ok (${clean.length}b)`
       );
       return msg;
     } catch (err) {
       if (err instanceof GrammyError && err.error_code === 400) {
-        console.warn(`[send] HTML 400 (${err.description}) — retry plain`);
-        const msg = await this.api.sendMessage(
+        console.warn(`[send] rich 400 (${err.description}) — retry plain`);
+        return this.api.sendMessage(
           this.sessionId.chatId,
-          Renderer.stripHtml(Renderer.sanitize(html)),
+          Renderer.stripHtml(clean),
           {
             message_thread_id: this.sessionId.threadId,
             link_preview_options: { is_disabled: true },
           }
         );
-        return msg;
       }
       throw err;
     }
   }
 
   private async editMessage(html: string): Promise<void> {
+    const clean = Renderer.sanitize(html);
     try {
       await this.api.editMessageText(
         this.sessionId.chatId,
         this.statusMessageId!,
-        Renderer.sanitize(html),
         {
-          parse_mode: "HTML",
-          link_preview_options: { is_disabled: true },
+          html: clean,
         }
       );
     } catch (err) {
@@ -530,7 +547,7 @@ export class Renderer {
             .editMessageText(
               this.sessionId.chatId,
               this.statusMessageId!,
-              Renderer.stripHtml(Renderer.sanitize(html)),
+              Renderer.stripHtml(clean),
               {
                 link_preview_options: { is_disabled: true },
               }
@@ -575,7 +592,7 @@ export class Renderer {
     const label = [
       first.text,
       ...rest.map((op) => `${op.emoji} ${op.text}`),
-    ].join("\n");
+    ].join("<br>");
     return { emoji: first.emoji, label };
   }
 
@@ -720,7 +737,9 @@ export class Renderer {
     if (name === "subagent") {
       const prompt = Renderer.stringArg(obj, "prompt");
       return prompt
-        ? Markdown.toHtml(Renderer.truncate(Renderer.firstLine(prompt), 180))
+        ? Renderer.escapeInline(
+            Renderer.truncate(Renderer.firstLine(prompt), 180)
+          )
         : "";
     }
 
@@ -840,7 +859,7 @@ export class Renderer {
   }
 
   private static cleanProse(text: string): string {
-    return Renderer.truncate(text.replace(/\n{3,}/g, "\n\n").trim(), 900);
+    return text.replace(/\n{3,}/g, "\n\n").trim();
   }
 
   private static truncate(text: string, limit = 180): string {
@@ -851,15 +870,216 @@ export class Renderer {
     if (text.length <= MESSAGE_LIMIT) {
       return text;
     }
-    const lines = text.split("\n");
+    const blocks = Renderer.splitStatusBlocks(text);
     let dropped = 0;
-    let total = text.length;
-    while (total > MESSAGE_LIMIT && lines.length > 1) {
-      const first = lines.shift()!;
-      total -= first.length + 1;
+    while (blocks.length > 1) {
+      blocks.shift();
       dropped += 1;
+      const rest = Renderer.trimLeadingBreaks(blocks.join("").trimStart());
+      const candidate = `<p>… ${dropped} earlier entries</p>${rest}`;
+      if (candidate.length <= MESSAGE_LIMIT) {
+        return candidate;
+      }
+    }
+    return Renderer.capPlainStatus(blocks);
+  }
+
+  private static splitStatusBlocks(html: string): string[] {
+    const blocks: string[] = [];
+    let cursor = 0;
+    while (cursor < html.length) {
+      const tag = Renderer.nextStatusBlockTag(html, cursor);
+      if (!tag) {
+        Renderer.pushStatusBlock(blocks, html.slice(cursor));
+        break;
+      }
+      if (VOID_BLOCK_TAGS.has(tag.name)) {
+        Renderer.pushStatusBlock(blocks, html.slice(cursor, tag.end));
+        cursor = tag.end;
+        continue;
+      }
+      Renderer.pushStatusBlock(blocks, html.slice(cursor, tag.start));
+      const end = Renderer.statusBlockEnd(html, tag);
+      Renderer.pushStatusBlock(blocks, html.slice(tag.start, end));
+      cursor = end;
+    }
+    return blocks;
+  }
+
+  private static nextStatusBlockTag(
+    html: string,
+    start: number
+  ): HtmlTag | undefined {
+    const tags = Renderer.htmlTags(html, start);
+    for (const tag of tags) {
+      if (tag.closing) {
+        continue;
+      }
+      if (BLOCK_TAGS.has(tag.name) || VOID_BLOCK_TAGS.has(tag.name)) {
+        return tag;
+      }
+    }
+    return undefined;
+  }
+
+  private static statusBlockEnd(html: string, opener: HtmlTag): number {
+    if (opener.selfClosing) {
+      return opener.end;
+    }
+    const stack = [opener.name];
+    const tags = Renderer.htmlTags(html, opener.end);
+    for (const tag of tags) {
+      if (VOID_BLOCK_TAGS.has(tag.name)) {
+        continue;
+      }
+      if (!BLOCK_TAGS.has(tag.name)) {
+        continue;
+      }
+      if (tag.closing) {
+        if (stack.at(-1) === tag.name) {
+          stack.pop();
+        }
+      } else if (!tag.selfClosing) {
+        stack.push(tag.name);
+      }
+      if (stack.length === 0) {
+        return tag.end;
+      }
+    }
+    return html.length;
+  }
+
+  private static *htmlTags(html: string, start: number): Generator<HtmlTag> {
+    const re = /<\s*(\/)?\s*([a-z][\w:-]*)(?:\s[^>]*)?\/?\s*>/gi;
+    re.lastIndex = start;
+    for (let match = re.exec(html); match; match = re.exec(html)) {
+      const raw = match[0]!;
+      yield {
+        start: match.index,
+        end: re.lastIndex,
+        name: match[2]!.toLowerCase(),
+        closing: match[1] !== undefined,
+        selfClosing: /\/\s*>$/.test(raw),
+      };
+    }
+  }
+
+  private static pushStatusBlock(blocks: string[], block: string): void {
+    if (block) {
+      blocks.push(block);
+    }
+  }
+
+  private static trimLeadingBreaks(text: string): string {
+    return text.replace(/^(?:<br\s*\/?>)+/i, "").trimStart();
+  }
+
+  private static capPlainStatus(blocks: readonly string[]): string {
+    let head = "";
+    for (let i = 0; i < blocks.length; i++) {
+      const block = blocks[i]!;
+      const candidate = `${head}${block}`;
+      if (candidate.length <= MESSAGE_LIMIT) {
+        head = candidate;
+        continue;
+      }
+      const remaining = MESSAGE_LIMIT - head.length;
+      const truncated = Renderer.truncateHtmlHead(block, remaining);
+      if (truncated) {
+        head = `${head}${truncated}`;
+      }
+      break;
+    }
+    return head.trimEnd();
+  }
+
+  private static truncateHtmlHead(html: string, limit: number): string {
+    if (html.length <= limit) {
+      return html;
+    }
+    if (limit <= 0) {
+      return "";
+    }
+    const wrapper = Renderer.outerHtmlWrapper(html);
+    if (wrapper) {
+      const innerLimit = limit - wrapper.open.length - wrapper.close.length;
+      if (innerLimit > 0) {
+        const inner = Renderer.truncateHtmlHead(wrapper.inner, innerLimit);
+        if (inner) {
+          return `${wrapper.open}${inner}${wrapper.close}`;
+        }
+      }
     }
-    return `… ${dropped} earlier entries\n${lines.join("\n")}`;
+    return Renderer.escapePlainHead(Renderer.stripHtml(html), limit);
+  }
+
+  private static outerHtmlWrapper(html: string):
+    | {
+        readonly open: string;
+        readonly inner: string;
+        readonly close: string;
+      }
+    | undefined {
+    const opener = /^<\s*([a-z][\w:-]*)(?:\s[^>]*)?\/?\s*>/i.exec(html);
+    if (!opener) {
+      return undefined;
+    }
+    const open = opener[0]!;
+    if (/\/\s*>$/.test(open)) {
+      return undefined;
+    }
+    const name = opener[1]!.toLowerCase();
+    const close = Renderer.matchingHtmlCloseTag(html, name, open.length);
+    if (!close || close.end !== html.length) {
+      return undefined;
+    }
+    return {
+      open,
+      inner: html.slice(open.length, close.start),
+      close: html.slice(close.start, close.end),
+    };
+  }
+
+  private static matchingHtmlCloseTag(
+    html: string,
+    name: string,
+    start: number
+  ): HtmlTag | undefined {
+    let depth = 1;
+    const tags = Renderer.htmlTags(html, start);
+    for (const tag of tags) {
+      if (tag.name !== name) {
+        continue;
+      }
+      if (tag.closing) {
+        depth -= 1;
+        if (depth === 0) {
+          return tag;
+        }
+      } else if (!tag.selfClosing && !VOID_BLOCK_TAGS.has(tag.name)) {
+        depth += 1;
+      }
+    }
+    return undefined;
+  }
+
+  private static escapePlainHead(text: string, limit: number): string {
+    const marker = "…";
+    if (limit < marker.length) {
+      return "";
+    }
+    const budget = limit - marker.length;
+    const escaped: string[] = [];
+    let length = 0;
+    for (const char of text) {
+      const next = char === "\n" ? BR : Markdown.escape(char);
+      if (length + next.length > budget) {
+        break;
+      }
+      escaped.push(next);
+      length += next.length;
+    }
+    return `${escaped.join("").trimEnd()}${marker}`;
   }
 
   private static chunk(html: string): readonly string[] {
@@ -869,10 +1089,14 @@ export class Renderer {
     const chunks: string[] = [];
     let rest = html;
     while (rest.length > MESSAGE_LIMIT) {
-      const idx = rest.lastIndexOf("\n", MESSAGE_LIMIT);
-      const splitAt = idx > 0 ? idx : MESSAGE_LIMIT;
-      chunks.push(rest.slice(0, splitAt).trim());
-      rest = rest.slice(splitAt).trim();
+      const idx = rest.lastIndexOf(BR, MESSAGE_LIMIT);
+      if (idx > 0) {
+        chunks.push(rest.slice(0, idx).trim());
+        rest = rest.slice(idx + BR.length).trim();
+      } else {
+        chunks.push(rest.slice(0, MESSAGE_LIMIT).trim());
+        rest = rest.slice(MESSAGE_LIMIT).trim();
+      }
     }
     if (rest) {
       chunks.push(rest);
@@ -880,6 +1104,10 @@ export class Renderer {
     return chunks;
   }
 
+  private static escapeInline(text: string): string {
+    return Markdown.escape(text).replace(/\n/g, BR);
+  }
+
   private static sanitize(text: string): string {
     return text.replace(
       /\b(api[_-]?key|token|secret)\b\s*[:=]\s*\S+/gi,

package/src/telegram/SendFileTool.ts

@@ -2,12 +2,11 @@ import {
   defineTool,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { GrammyError, InputFile, type Api } from "grammy";
+import { InputFile, type Api } from "grammy";
 import { basename } from "node:path";
 
 import { FsErrors } from "../shared/FsErrors";
 import { Paths } from "../shared/Paths";
-import { Markdown } from "./Markdown";
 import {
   MAX_CAPTION_CHARS,
   MAX_DOCUMENT_BYTES,
@@ -73,22 +72,9 @@ export class SendFileTool {
     path: string,
     caption: string | undefined
   ): Promise<void> {
-    const html = caption ? Markdown.toHtml(caption) : undefined;
-    try {
-      await api.sendDocument(sessionId.chatId, new InputFile(path), {
-        message_thread_id: sessionId.threadId,
-        caption: html,
-        parse_mode: html ? "HTML" : undefined,
-      });
-    } catch (err) {
-      if (err instanceof GrammyError && err.error_code === 400 && html) {
-        await api.sendDocument(sessionId.chatId, new InputFile(path), {
-          message_thread_id: sessionId.threadId,
-          caption,
-        });
-        return;
-      }
-      throw err;
-    }
+    await api.sendDocument(sessionId.chatId, new InputFile(path), {
+      message_thread_id: sessionId.threadId,
+      caption,
+    });
   }
 }

package/src/telegram/Session.ts

@@ -498,7 +498,7 @@ export class Session {
     }
     const username = this.deps.getBotUsername();
     const handle = username ? ` (@${username})` : "";
-    const systemIx = `You are running as a Telegram bot${handle} powered by Pim Agent. The telegram_user_instructions below are your editable instructions - edit the file at its \`path\` attribute to update your instructions.`;
+    const systemIx = `You are running as a Telegram bot${handle} powered by Pim Agent. The telegram_user_instructions below are your editable instructions - edit the file at its \`path\` attribute to update your instructions. Wrap LaTeX math in a \`\`\`math fenced block without the $$ delimitters; inline math is not supported.`;
     const userIx = `<telegram_user_instructions path="${path}">${userContent ? `\n${userContent}\n` : ""}</telegram_user_instructions>`;
     return `<telegram_system_instructions>\n${systemIx}\n${userIx}\n</telegram_system_instructions>`;
   }