@aaroncql/pim-agent 0.0.1

package/src/telegram/Markdown.ts

@@ -0,0 +1,177 @@
+type TableRow = ReadonlyArray<string>;
+
+type Segment =
+  | { readonly kind: "md"; readonly text: string }
+  | { readonly kind: "table"; readonly rows: ReadonlyArray<TableRow> };
+
+const SAFE_LINK = /^(https?:|tg:|mailto:)/i;
+
+export class Markdown {
+  public static toHtml(md: string): 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);
+    }
+    return out.replace(/\n{3,}/g, "\n\n").trim();
+  }
+
+  public static escape(s: string): string {
+    return s
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;");
+  }
+
+  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`,
+    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;
+      const open = lang
+        ? `<pre><code class="language-${Markdown.escape(lang)}">`
+        : "<pre>";
+      const close = lang ? "</code></pre>" : "</pre>";
+      return `${open}${body}${close}\n\n`;
+    },
+    link: (c: string, meta?: { href?: string }): string => {
+      const href = meta?.href ?? "";
+      return SAFE_LINK.test(href)
+        ? `<a href="${Markdown.escape(href)}">${c}</a>`
+        : c;
+    },
+    image: (c: string, meta?: { src?: string }): string => {
+      const src = meta?.src ?? "";
+      const alt = c || src;
+      return SAFE_LINK.test(src)
+        ? `<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;
+      }
+    ): 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`;
+    },
+    hr: (): string => "───\n\n",
+    br: (): string => "\n",
+    table: (c: string): string => c,
+  };
+
+  private static renderMd(md: string): string {
+    if (!md.trim()) {
+      return "";
+    }
+    return Bun.markdown.render(md, Markdown.RENDERERS);
+  }
+
+  private static split(md: string): ReadonlyArray<Segment> {
+    const lines = md.split("\n");
+    const segments: Segment[] = [];
+    let buf: string[] = [];
+
+    const flushMd = (): void => {
+      if (buf.length > 0) {
+        segments.push({ kind: "md", text: buf.join("\n") });
+        buf = [];
+      }
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]!;
+      const next = lines[i + 1];
+      if (
+        Markdown.isPipeLine(line) &&
+        next !== undefined &&
+        Markdown.isTableSeparator(next)
+      ) {
+        flushMd();
+        const rows: string[][] = [Markdown.parseRow(line)];
+        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 });
+        continue;
+      }
+      buf.push(line);
+    }
+    flushMd();
+    return segments;
+  }
+
+  private static isPipeLine(line: string): boolean {
+    return /^\s*\|.*\|\s*$/.test(line);
+  }
+
+  private static isTableSeparator(line: string): boolean {
+    return /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$/.test(line);
+  }
+
+  private static parseRow(line: string): string[] {
+    const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+    return trimmed.split("|").map((cell) => cell.trim());
+  }
+
+  private static renderTable(rows: ReadonlyArray<TableRow>): string {
+    if (rows.length < 2) {
+      return "";
+    }
+    const header = rows[0]!;
+    const dataRows = rows.slice(1);
+    if (dataRows.length === 0) {
+      return "";
+    }
+    const pieces: string[] = [];
+    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);
+        }
+      }
+    }
+    pieces.push("───");
+    return `${pieces.join("\n")}\n\n`;
+  }
+}

package/src/telegram/Message.ts

@@ -0,0 +1,211 @@
+import type { PromptOptions } from "@earendil-works/pi-coding-agent";
+import type { Context, Filter } from "grammy";
+import { mkdir } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+
+import type { SessionId } from "./Session";
+
+type DownloadedFile = {
+  readonly path: string;
+  readonly mimeType: string;
+  readonly imageBase64: string | undefined;
+};
+
+type FileRef = {
+  readonly fileId: string;
+  readonly uniqueId?: string;
+  readonly name?: string;
+  readonly mimeType: string;
+  readonly ext: string;
+};
+
+export type Prompt = {
+  readonly text: string;
+  readonly options: Pick<PromptOptions, "images">;
+};
+
+const IMAGE_BYTES_LIMIT = 4 * 1024 * 1024;
+const REPLY_QUOTE_HEAD = 128;
+const REPLY_QUOTE_TAIL = 128;
+
+export class Message {
+  public static async toPrompt(
+    ctx: Filter<Context, "message">,
+    token: string,
+    configDir: string,
+    sessionId: SessionId
+  ): Promise<Prompt | undefined> {
+    const message = ctx.message;
+    const text = ("text" in message ? message.text : undefined) ?? "";
+    const caption = ("caption" in message ? message.caption : undefined) ?? "";
+    const files = await Message.download(ctx, token, configDir, sessionId);
+
+    const attachments: string[] = [];
+    const images: NonNullable<PromptOptions["images"]> = [];
+    for (const file of files) {
+      if (file.imageBase64) {
+        images.push({
+          type: "image",
+          data: file.imageBase64,
+          mimeType: file.mimeType,
+        });
+        attachments.push(`[Image attachment: ${file.path}]`);
+        continue;
+      }
+      attachments.push(`[Attachment: ${file.path}]`);
+    }
+
+    const body = (text || caption || "").trim();
+    if (!body && images.length === 0 && attachments.length === 0) {
+      return undefined;
+    }
+    const replyContext = Message.buildReplyContext(ctx);
+    const promptText = [replyContext, body, ...attachments]
+      .filter(Boolean)
+      .join("\n\n")
+      .trim();
+    return {
+      text: promptText,
+      options: images.length > 0 ? { images } : {},
+    };
+  }
+
+  private static buildReplyContext(
+    ctx: Filter<Context, "message">
+  ): string | undefined {
+    const reply = ctx.message.reply_to_message;
+    if (!reply) {
+      return undefined;
+    }
+    const raw = ctx.message.quote?.text ?? reply.text ?? reply.caption ?? "";
+    const trimmed = raw.trim();
+    if (!trimmed) {
+      return undefined;
+    }
+    const truncated =
+      trimmed.length > REPLY_QUOTE_HEAD + REPLY_QUOTE_TAIL + 1
+        ? `${trimmed.slice(0, REPLY_QUOTE_HEAD)}…${trimmed.slice(-REPLY_QUOTE_TAIL)}`
+        : trimmed;
+    const quoted = truncated
+      .split("\n")
+      .map((line) => `> ${line}`)
+      .join("\n");
+    const isFromBot = reply.from?.id === ctx.me.id;
+    const label = isFromBot
+      ? "Replying to your earlier message:"
+      : "Replying to my earlier message:";
+    return `${label}\n${quoted}`;
+  }
+
+  private static async download(
+    ctx: Filter<Context, "message">,
+    token: string,
+    configDir: string,
+    sessionId: SessionId
+  ): Promise<ReadonlyArray<DownloadedFile>> {
+    const refs = Message.refs(ctx);
+    if (refs.length === 0) {
+      return [];
+    }
+
+    const dir = join(configDir, "attachments", String(sessionId.chatId));
+    await mkdir(dir, { recursive: true });
+    const out: DownloadedFile[] = [];
+    for (const ref of refs) {
+      const telegramFile = await ctx.api.getFile(ref.fileId);
+      if (!telegramFile.file_path) {
+        continue;
+      }
+      const url = `https://api.telegram.org/file/bot${token}/${telegramFile.file_path}`;
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Telegram file download failed: ${response.status}`);
+      }
+      const ext =
+        extname(telegramFile.file_path) || extname(ref.name ?? "") || ref.ext;
+      const filename = Message.safeName(
+        `${ref.uniqueId ?? ref.fileId}-${Date.now()}${ext}`
+      );
+      const path = join(dir, filename);
+      const bytes = await response.arrayBuffer();
+      await Bun.write(path, bytes);
+      const isImage = ref.mimeType.startsWith("image/");
+      out.push({
+        path,
+        mimeType: ref.mimeType,
+        imageBase64:
+          isImage && bytes.byteLength <= IMAGE_BYTES_LIMIT
+            ? Buffer.from(bytes).toString("base64")
+            : undefined,
+      });
+    }
+    return out;
+  }
+
+  private static refs(ctx: Filter<Context, "message">): ReadonlyArray<FileRef> {
+    const message = ctx.message;
+    if ("photo" in message && message.photo) {
+      const photo = message.photo.at(-1)!;
+      return [
+        {
+          fileId: photo.file_id,
+          uniqueId: photo.file_unique_id,
+          mimeType: "image/jpeg",
+          ext: ".jpg",
+        },
+      ];
+    }
+    if ("document" in message && message.document) {
+      const doc = message.document;
+      return [
+        {
+          fileId: doc.file_id,
+          uniqueId: doc.file_unique_id,
+          name: doc.file_name,
+          mimeType: doc.mime_type ?? "application/octet-stream",
+          ext: extname(doc.file_name ?? "") || ".bin",
+        },
+      ];
+    }
+    if ("video" in message && message.video) {
+      const video = message.video;
+      return [
+        {
+          fileId: video.file_id,
+          uniqueId: video.file_unique_id,
+          name: video.file_name,
+          mimeType: video.mime_type ?? "video/mp4",
+          ext: extname(video.file_name ?? "") || ".mp4",
+        },
+      ];
+    }
+    if ("audio" in message && message.audio) {
+      const audio = message.audio;
+      return [
+        {
+          fileId: audio.file_id,
+          uniqueId: audio.file_unique_id,
+          name: audio.file_name,
+          mimeType: audio.mime_type ?? "audio/mpeg",
+          ext: extname(audio.file_name ?? "") || ".mp3",
+        },
+      ];
+    }
+    if ("voice" in message && message.voice) {
+      const voice = message.voice;
+      return [
+        {
+          fileId: voice.file_id,
+          uniqueId: voice.file_unique_id,
+          mimeType: voice.mime_type ?? "audio/ogg",
+          ext: ".ogg",
+        },
+      ];
+    }
+    return [];
+  }
+
+  private static safeName(name: string): string {
+    return basename(name).replace(/[^a-zA-Z0-9._-]/g, "_");
+  }
+}

package/src/telegram/Renderer.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, test } from "bun:test";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { Api } from "grammy";
+
+import { Renderer } from "./Renderer";
+import type { Session } from "./Session";
+
+type SentMessage = {
+  readonly chatId: number;
+  readonly text: string;
+  readonly options: unknown;
+};
+
+type EditedMessage = {
+  readonly chatId: number;
+  readonly messageId: number;
+  readonly text: string;
+  readonly options: unknown;
+};
+
+class FakeApi {
+  public readonly sent: SentMessage[] = [];
+  public readonly edited: EditedMessage[] = [];
+
+  public async sendMessage(
+    chatId: number,
+    text: string,
+    options: unknown
+  ): Promise<{ readonly message_id: number }> {
+    this.sent.push({ chatId, text, options });
+    return { message_id: this.sent.length };
+  }
+
+  public async editMessageText(
+    chatId: number,
+    messageId: number,
+    text: string,
+    options: unknown
+  ): Promise<void> {
+    this.edited.push({ chatId, messageId, text, options });
+  }
+
+  public async sendChatAction(): Promise<void> {}
+}
+
+const session = {
+  id: { chatId: 123, threadId: undefined },
+  settings: { logsMode: "text" },
+} as unknown as Session;
+
+function makeRenderer(): {
+  readonly api: FakeApi;
+  readonly renderer: Renderer;
+} {
+  const api = new FakeApi();
+  return { api, renderer: new Renderer(session, api as unknown as Api) };
+}
+
+function todoStart(
+  todos: readonly unknown[],
+  toolCallId = "todo-1"
+): AgentSessionEvent {
+  return todoStartWithArgs({ todos }, toolCallId);
+}
+
+function todoStartWithArgs(
+  args: unknown,
+  toolCallId = "todo-1"
+): AgentSessionEvent {
+  return {
+    type: "tool_execution_start",
+    toolCallId,
+    toolName: "todo",
+    args,
+  } as AgentSessionEvent;
+}
+
+function todoEnd(
+  todos: readonly unknown[],
+  toolCallId = "todo-1"
+): AgentSessionEvent {
+  return {
+    type: "tool_execution_end",
+    toolCallId,
+    toolName: "todo",
+    result: { content: [], details: { todos } },
+    isError: false,
+  } as AgentSessionEvent;
+}
+
+function assistantText(text: string): readonly AgentSessionEvent[] {
+  return [
+    { type: "message_start" } as AgentSessionEvent,
+    {
+      type: "message_update",
+      assistantMessageEvent: { type: "text_delta", delta: text },
+    } as AgentSessionEvent,
+    {
+      type: "message_update",
+      assistantMessageEvent: { type: "text_end", content: text },
+    } as AgentSessionEvent,
+    {
+      type: "message_end",
+      message: { role: "assistant", stopReason: "toolUse" },
+    } as AgentSessionEvent,
+  ];
+}
+
+async function flush(renderer: Renderer): Promise<void> {
+  await (
+    renderer as unknown as {
+      readonly flushEdit: (state: "running") => Promise<void>;
+    }
+  ).flushEdit("running");
+}
+
+describe("Telegram Renderer todo status", () => {
+  test("renders the latest in-progress todo in bold", async () => {
+    const { api, renderer } = makeRenderer();
+
+    renderer.handleEvent(
+      todoStart([
+        { content: "First task", status: "in_progress" },
+        { content: "Second <task> & verify", status: "in_progress" },
+      ])
+    );
+    await renderer.finish("", "ok");
+
+    expect(api.sent.map((msg) => msg.text)).toEqual([
+      "📋 <b>Second &lt;task&gt; &amp; verify</b>",
+    ]);
+  });
+
+  test("keeps todo entries in event order instead of replacing the prior one", async () => {
+    const { api, renderer } = makeRenderer();
+
+    renderer.handleEvent(
+      todoStart([{ content: "Remember to buy milk", status: "in_progress" }])
+    );
+    await flush(renderer);
+
+    for (const event of assistantText(
+      "First item is in progress. Now let me finish it and start the next one:"
+    )) {
+      renderer.handleEvent(event);
+    }
+    renderer.handleEvent(
+      todoStart(
+        [
+          { content: "Remember to buy milk", status: "completed" },
+          { content: "Remember to get water", status: "in_progress" },
+        ],
+        "todo-2"
+      )
+    );
+    await renderer.finish("", "ok");
+
+    expect(api.sent.map((msg) => msg.text)).toEqual([
+      "📋 <b>Remember to buy milk</b>",
+    ]);
+    expect(api.edited.map((msg) => msg.text)).toEqual([
+      [
+        "📋 <b>Remember to buy milk</b>",
+        "",
+        "First item is in progress. Now let me finish it and start the next one:",
+        "",
+        "📋 <b>Remember to get water</b>",
+      ].join("\n"),
+    ]);
+  });
+
+  test("does not render todo calls with no in-progress item", async () => {
+    const { api, renderer } = makeRenderer();
+
+    renderer.handleEvent(
+      todoStart([
+        { content: "Plan", status: "pending" },
+        { content: "Done", status: "completed" },
+      ])
+    );
+    await renderer.finish("", "ok");
+
+    expect(api.sent).toEqual([]);
+    expect(api.edited).toEqual([]);
+  });
+
+  test("ignores malformed todo args", async () => {
+    const { api, renderer } = makeRenderer();
+
+    expect(() =>
+      renderer.handleEvent(todoStartWithArgs({ text: "done" }))
+    ).not.toThrow();
+    await renderer.finish("", "ok");
+
+    expect(api.sent).toEqual([]);
+    expect(api.edited).toEqual([]);
+  });
+
+  test("does not emit a new todo entry when no item remains in progress", async () => {
+    const { api, renderer } = makeRenderer();
+
+    renderer.handleEvent(
+      todoStart([{ content: "Build feature", status: "in_progress" }])
+    );
+    await flush(renderer);
+    renderer.handleEvent(
+      todoEnd([{ content: "Build feature", status: "completed" }])
+    );
+    await flush(renderer);
+
+    expect(api.sent.map((msg) => msg.text)).toEqual([
+      "📋 <b>Build feature</b>",
+    ]);
+    expect(api.edited).toEqual([]);
+  });
+});