@llblab/pi-telegram 0.9.7 → 0.9.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.9.9: Guest Mode HTML Rendering
+
+- `[Guest Mode]` Guest replies now render through the same `renderTelegramMessage` pipeline as direct messages: Markdown → HTML → `answerGuestQuery` with `parse_mode: "HTML"`. Bold, italic, code, links, lists, and tables render identically in guest and DM replies.
+- `[Replies]` Added `createGuestMarkdownReplySender` in the replies domain — guest rendering stays encapsulated within `replies.ts` and `index.ts` no longer imports from `rendering.ts` directly.
+- `[API]` Simplified `answerGuestQuery` title to a fixed `"Response"` string (the `InlineQueryResultArticle` title is hidden in guest mode and was previously generated by stripping HTML/Markdown from the message text).
+- `[API]` Removed `replyMarkup` parameter from `answerGuestQuery` — inline keyboards are not supported in guest mode because `callback_query` from inline results carries `inline_message_id` instead of `chat_id`/`message_id`, which the existing callback routing cannot handle.
+
+## 0.9.8: Guest Mode Context
+
+- `[Guest Mode]` Extended the [telegram] prefix with |from:user (sender) and |guest:GroupName (source chat for group guest messages) so the agent sees who sent the message and where from. Private guest chats omit the guest: suffix.
+- `[Guest Mode]` Added |from:user to the [reply] block so the agent knows the original author of a replied-to message in guest mode.
+- `[Guest Mode]` Formatted guest prompt text identically to regular DMs through buildTelegramTurnPrompt, including [attachments] and [outputs] sections with file downloads and inbound handler processing.
+- `[Prompts]` Added compact agent guidance explaining guest-mode prefix suffixes (|from:, |guest:) and reply-from context.
+
 ## 0.9.7: Bot API 10.0 Alignment
 
 - `[Dependencies]` Migrated peer dependencies and imports from `@mariozechner/*` to `@earendil-works/*` (`pi-agent-core`, `pi-ai`, `pi-coding-agent`). Impact: the extension now tracks the new `@earendil-works` package scope; transitive `@mariozechner` packages remain in the lockfile until their upstreams migrate.

package/index.ts

@@ -157,6 +157,11 @@ export default function (pi: Pi.ExtensionAPI) {
 
   // --- Message Delivery & Preview ---
 
+  const sendGuestReply = Replies.createGuestMarkdownReplySender({
+    renderTelegramMessage: Replies.renderTelegramMessage,
+    answerGuestQuery,
+  });
+
   const promptDispatchRuntime =
     Runtime.createTelegramPromptDispatchRuntime<Pi.ExtensionContext>({
       lifecycle,
@@ -497,6 +502,7 @@ export default function (pi: Pi.ExtensionAPI) {
     sendTextReply,
     sendQueuedAttachments: queuedAttachmentSender,
     answerGuestQuery,
+    sendGuestReply,
     planOutboundReply: outboundReplyPlanner,
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
     isCurrentOwner: lockOwnershipGuard.ownsContext,

package/lib/api.ts

@@ -161,6 +161,7 @@ export interface TelegramGuestMessage {
   guest_query_id: string;
   guest_bot_caller_user?: TelegramUser;
   guest_bot_caller_chat?: TelegramChat;
+  reply_to_message?: TelegramMessage;
 }
 
 export interface TelegramUpdate {
@@ -255,7 +256,11 @@ export interface TelegramApiClient {
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
-  answerGuestQuery?: (guestQueryId: string, text?: string) => Promise<void>;
+  answerGuestQuery?: (
+    guestQueryId: string,
+    text?: string,
+    options?: { parseMode?: string },
+  ) => Promise<void>;
 }
 
 export interface TelegramBridgeApiRuntimeDeps {
@@ -313,7 +318,11 @@ export interface TelegramBridgeApiRuntime {
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
-  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
+  answerGuestQuery: (
+    guestQueryId: string,
+    text?: string,
+    options?: { parseMode?: string },
+  ) => Promise<void>;
   prepareTempDir: () => Promise<number>;
 }
 
@@ -784,14 +793,24 @@ export function createTelegramBridgeApiRuntime(
     answerCallbackQuery: (callbackQueryId, text) => {
       return deps.client.answerCallbackQuery(callbackQueryId, text);
     },
-    answerGuestQuery: (guestQueryId, text) => {
+    answerGuestQuery: (
+      guestQueryId: string,
+      text: string | undefined,
+      options: { parseMode?: string } | undefined,
+    ) => {
       const body: Record<string, unknown> = { guest_query_id: guestQueryId };
       if (text !== undefined) {
+        const inputContent: Record<string, unknown> = {
+          message_text: text,
+        };
+        if (options?.parseMode) {
+          inputContent.parse_mode = options.parseMode;
+        }
         body.result = {
           type: "article",
           id: "1",
-          title: text.length > 64 ? text.slice(0, 61) + "..." : text,
-          input_message_content: { message_text: text },
+          title: "Response",
+          input_message_content: inputContent,
         };
       }
       return callRecorded<void>("answerGuestQuery", body);

package/lib/prompts.ts

@@ -12,8 +12,8 @@ const SYSTEM_PROMPT_SUFFIX = `
 Telegram bridge extension is active.
 
 Inbound context:
-- \`[telegram]\` marks Telegram-originated messages.
-- \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
+- \`[telegram]\` marks Telegram-originated messages. Suffixes \`|from:user\` (sender) and \`|guest:group\` (guest mode — message from another chat where the bot is not a member) may be present; the bot sees the message as if forwarded from that user/chat.
+- \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Suffix \`|from:user\` identifies the original author in guest-mode replies. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
 - \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains inbound-handler stdout such as transcriptions or extracted text for those attachments.
 - Unknown \`[callback] ...\` messages may be intended for another extension; if you see one, say the callback was not handled and the environment may be misconfigured.
 

package/lib/queue.ts

@@ -788,7 +788,8 @@ export interface TelegramAgentEndRuntimeDeps<
     text: string,
   ) => Promise<unknown>;
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
-  answerGuestQuery?: (guestQueryId: string, text?: string) => Promise<void>;
+  answerGuestQuery?: (guestQueryId: string, text?: string, options?: { parseMode?: string }) => Promise<void>;
+  sendGuestReply?: (guestQueryId: string, markdown: string) => Promise<void>;
   planOutboundReply?: (
     markdown: string,
   ) => TelegramAgentEndOutboundReplyPlan<TReplyMarkup>;
@@ -837,6 +838,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   sendTextReply: TelegramAgentEndRuntimeDeps<TTurn>["sendTextReply"];
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
   answerGuestQuery?: TelegramAgentEndRuntimeDeps<TTurn>["answerGuestQuery"];
+  sendGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestReply"];
   planOutboundReply?: TelegramAgentEndRuntimeDeps<
     TTurn,
     TReplyMarkup
@@ -958,6 +960,7 @@ export function createTelegramAgentEndHook<
       sendTextReply: deps.sendTextReply,
       sendQueuedAttachments: deps.sendQueuedAttachments,
       answerGuestQuery: deps.answerGuestQuery,
+      sendGuestReply: deps.sendGuestReply,
       planOutboundReply: deps.planOutboundReply,
       sendOutboundReplyArtifacts: deps.sendOutboundReplyArtifacts,
       getDefaultChatId: deps.getDefaultChatId,
@@ -1027,7 +1030,11 @@ export async function handleTelegramAgentEndRuntime<
       return;
     }
     if (finalText) {
-      await deps.answerGuestQuery?.(turn.guestQueryId, finalText);
+      if (deps.sendGuestReply) {
+        await deps.sendGuestReply(turn.guestQueryId, finalText);
+      } else {
+        await deps.answerGuestQuery?.(turn.guestQueryId, finalText);
+      }
     }
     if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
     return;

package/lib/replies.ts

@@ -11,6 +11,12 @@ import {
   type TelegramRenderMode,
 } from "./rendering.ts";
 
+export {
+  renderTelegramMessage,
+  type TelegramRenderedChunk,
+  type TelegramRenderMode,
+};
+
 // --- Reply Dedup ---
 
 /** Non-persistent reply deduplication for a single agent turn.
@@ -420,3 +426,26 @@ export function dedupSendMarkdownReply<TReplyMarkup = unknown>(
     return inner(chatId, effectiveReplyTo, markdown, options);
   };
 }
+
+/**
+ * Guest reply sender: renders Markdown → HTML, sends via answerGuestQuery.
+ * Keeps guest rendering inside the replies domain so the orchestration layer
+ * (index.ts) does not import from rendering.ts directly.
+ */
+export function createGuestMarkdownReplySender(deps: {
+  renderTelegramMessage: (
+    text: string,
+    options?: { mode?: TelegramRenderMode },
+  ) => TelegramRenderedChunk[];
+  answerGuestQuery: (
+    guestQueryId: string,
+    text?: string,
+    options?: { parseMode?: string },
+  ) => Promise<void>;
+}) {
+  return async (guestQueryId: string, markdown: string) => {
+    const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
+    const html = chunks.length > 0 ? chunks[0].text : markdown;
+    await deps.answerGuestQuery(guestQueryId, html, { parseMode: "HTML" });
+  };
+}

package/lib/routing.ts

@@ -6,6 +6,7 @@
 
 import * as OutboundHandlers from "./outbound-handlers.ts";
 import * as Commands from "./commands.ts";
+import { readFile } from "node:fs/promises";
 import type { TelegramConfigStore } from "./config.ts";
 import type { TelegramInboundHandlerRuntime } from "./inbound-handlers.ts";
 import * as Media from "./media.ts";
@@ -371,7 +372,71 @@ export function createTelegramInboundRouteRuntime<
     ctx: TContext,
   ): Promise<void> => {
     const text = guestMessage.text ?? "";
+    const gm = guestMessage as unknown as Record<string, unknown>;
+    // Build telegram prefix with guest context
+    const fromRaw = gm.from as Record<string, unknown> | undefined;
+    const fromName =
+      (fromRaw?.username as string) ||
+      (fromRaw?.first_name as string) ||
+      "";
+    const chatRaw = gm.chat as Record<string, unknown>;
+    const chatTitle = chatRaw?.title as string | undefined;
+    const chatType = chatRaw?.type as string;
+    const prefixParts = ["telegram"];
+    if (fromName) prefixParts.push(`from:${fromName}`);
+    if (chatType !== "private" && chatTitle) {
+      prefixParts.push(`guest:${chatTitle}`);
+    }
+    const telegramPrefix = `[${prefixParts.join("|")}]`;
+    // Extract reply context
+    const replyMsg = gm.reply_to_message as Record<string, unknown> | undefined;
+    const replyText =
+      replyMsg
+        ? ((replyMsg.text as string) || (replyMsg.caption as string) || "").trim()
+        : "";
+    const replyFrom =
+      replyMsg
+        ? (replyMsg.from as Record<string, unknown> | undefined)?.username as string | undefined
+        : undefined;
+    // Download files, run inbound handlers
+    const guestMsg = guestMessage as unknown as Media.TelegramMediaMessage;
+    const files = await Media.downloadTelegramMessageFiles([guestMsg], {
+      downloadFile: deps.downloadFile,
+    });
+    const processed = await deps.inboundHandlerRuntime.process(files, text, ctx);
+    let rawText = processed.rawText || text;
+    // Append reply context after handler processing
+    if (replyText) {
+      const replyBlock = replyFrom
+        ? `[reply|from:${replyFrom}] ${replyText}`
+        : `[reply] ${replyText}`;
+      rawText = `${rawText}\n\n${replyBlock}`;
+    }
+    const promptText = Turns.buildTelegramTurnPrompt({
+      telegramPrefix,
+      rawText,
+      files,
+      promptFiles: processed.promptFiles,
+      handlerOutputs: processed.handlerOutputs,
+    });
     const order = deps.bridgeRuntime.queue.allocateItemOrder();
+    const content: Queue.TelegramPromptContent[] = [
+      { type: "text", text: promptText },
+    ];
+    for (const file of processed.promptFiles) {
+      if (file.isImage && file.mimeType) {
+        try {
+          const buffer = await readFile(file.path);
+          content.push({
+            type: "image",
+            data: Buffer.from(buffer).toString("base64"),
+            mimeType: file.mimeType,
+          });
+        } catch {
+          // skip unreadable files
+        }
+      }
+    }
     const guestTurn: Queue.PendingTelegramTurn = {
       kind: "prompt",
       chatId: 0,
@@ -382,9 +447,15 @@ export function createTelegramInboundRouteRuntime<
       queueLane: "default",
       laneOrder: order,
       queuedAttachments: [],
-      content: [{ type: "text", text }],
-      historyText: text,
-      statusSummary: Turns.truncateTelegramQueueSummary(text),
+      content,
+      historyText: Turns.formatTelegramTurnStatusSummary(
+        processed.rawText || text,
+        processed.promptFiles,
+        processed.handlerOutputs,
+      ),
+      statusSummary: Turns.truncateTelegramQueueSummary(
+        processed.rawText || text,
+      ),
     };
     const items = deps.telegramQueueStore.getQueuedItems();
     deps.telegramQueueStore.setQueuedItems(

package/lib/updates.ts

@@ -136,6 +136,7 @@ export interface TelegramGuestMessage {
   from?: TelegramUser;
   message_id?: number;
   text?: string;
+  reply_to_message?: TelegramUpdateMessage;
 }
 
 export interface TelegramUpdateRouting {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "private": false,
   "publishConfig": {
     "access": "public"