@aaroncql/pim-agent 0.3.0 → 0.4.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.4.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,8 +1,14 @@
+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>;
+    };
 
 const SAFE_LINK = /^(https?:|tg:|mailto:)/i;
 
@@ -14,9 +20,9 @@ export class Markdown {
       out +=
         seg.kind === "md"
           ? Markdown.renderMd(seg.text)
-          : Markdown.renderTable(seg.rows);
+          : Markdown.renderTable(seg.rows, seg.aligns);
     }
-    return out.replace(/\n{3,}/g, "\n\n").trim();
+    return out.trim();
   }
 
   public static escape(s: string): string {
@@ -29,9 +35,11 @@ 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`,
+    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>`,
@@ -39,11 +47,14 @@ export class Markdown {
     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,38 +69,28 @@ 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;
+      return `<ul>${c}</ul>`;
+    },
+    listItem: (c: string, meta?: { checked?: boolean }): string => {
+      const body = c.replace(/\n+$/, "");
       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 `<li><input type="checkbox" checked> ${body}</li>`;
+      }
+      if (checked === false) {
+        return `<li><input type="checkbox"> ${body}</li>`;
       }
-      return `${indent}${marker} ${c.replace(/\n+$/, "")}\n`;
+      return `<li>${body}</li>`;
     },
-    hr: (): string => "───\n\n",
-    br: (): string => "\n",
+    hr: (): string => "<hr/>",
+    br: (): string => "<br>",
     table: (c: string): string => c,
   };
 
@@ -100,6 +101,13 @@ export class Markdown {
     return Bun.markdown.render(md, Markdown.RENDERERS);
   }
 
+  private static renderInline(md: string): string {
+    return Markdown.renderMd(md)
+      .replace(/^<p>/, "")
+      .replace(/<\/p>$/, "")
+      .trim();
+  }
+
   private static split(md: string): ReadonlyArray<Segment> {
     const lines = md.split("\n");
     const segments: Segment[] = [];
@@ -122,12 +130,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 +158,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 +187,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,8 @@ const TOOL_EMOJI: Record<string, string> = {
   subagent: "🤖",
 };
 
-const MESSAGE_LIMIT = 4000;
+const MESSAGE_LIMIT = 32000;
+const BR = "<br>";
 
 export class Renderer {
   private readonly api: Api;
@@ -432,9 +433,9 @@ 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(`<i>${Renderer.escapeInline(entry.label)}</i>`);
       } else if (entry.kind === "narration") {
-        pieces.push(Markdown.toHtml(entry.label));
+        pieces.push(Renderer.escapeInline(entry.label));
       } else {
         const isLastEntry = i === visible.length - 1;
         let suffix = "";
@@ -449,16 +450,16 @@ export class Renderer {
       const next = visible[i + 1];
       if (next) {
         pieces.push(
-          entry.kind === "tool" && next.kind === "tool" ? "\n" : "\n\n"
+          entry.kind === "tool" && next.kind === "tool" ? "<br>" : "<br><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 +478,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 +525,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 +570,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 +715,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)
+          )
         : "";
     }
 
@@ -851,15 +848,15 @@ export class Renderer {
     if (text.length <= MESSAGE_LIMIT) {
       return text;
     }
-    const lines = text.split("\n");
+    const lines = text.split(BR);
     let dropped = 0;
     let total = text.length;
     while (total > MESSAGE_LIMIT && lines.length > 1) {
       const first = lines.shift()!;
-      total -= first.length + 1;
+      total -= first.length + BR.length;
       dropped += 1;
     }
-    return `… ${dropped} earlier entries\n${lines.join("\n")}`;
+    return `… ${dropped} earlier entries${BR}${lines.join(BR)}`;
   }
 
   private static chunk(html: string): readonly string[] {
@@ -869,10 +866,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 +881,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>`;
   }