@llblab/pi-telegram 0.9.7 → 0.9.8

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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/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 {

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/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.8",
   "private": false,
   "publishConfig": {
     "access": "public"