@llblab/pi-telegram 0.5.2 → 0.6.1

package/lib/preview.ts

@@ -20,6 +20,7 @@ import {
   type TelegramRenderMode,
 } from "./rendering.ts";
 import { buildTelegramReplyParameters } from "./replies.ts";
+import { stripTelegramCommentMarkupForPreview } from "./outbound-handlers.ts";
 
 const TELEGRAM_PREVIEW_THROTTLE_MS = 750;
 const TELEGRAM_DRAFT_ID_MAX = 2_147_483_647;
@@ -43,6 +44,7 @@ export interface TelegramPreviewRuntimeState extends TelegramPreviewState {
 }
 
 export type TelegramSentPreviewMessage = TelegramSentMessage;
+export type TelegramPreviewReplyMarkup = any;
 
 export interface TelegramPreviewRuntimeDeps {
   getState: () => TelegramPreviewRuntimeState | undefined;
@@ -76,11 +78,13 @@ export interface TelegramPreviewRuntimeDeps {
   sendRenderedChunks: (
     chatId: number,
     chunks: TelegramRenderedChunk[],
+    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
   ) => Promise<number | undefined>;
   editRenderedMessage: (
     chatId: number,
     messageId: number,
     chunks: TelegramRenderedChunk[],
+    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
   ) => Promise<number | undefined>;
 }
 
@@ -158,11 +162,13 @@ export interface TelegramPreviewControllerDeps {
     chatId: number,
     chunks: TelegramRenderedChunk[],
     replyToMessageId: number | undefined,
+    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
   ) => Promise<number | undefined>;
   editRenderedMessage: (
     chatId: number,
     messageId: number,
     chunks: TelegramRenderedChunk[],
+    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
   ) => Promise<number | undefined>;
   throttleMs?: number;
   maxDraftId?: number;
@@ -187,6 +193,7 @@ export interface TelegramPreviewController {
     chatId: number,
     markdown: string,
     replyToMessageId?: number,
+    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
   ) => Promise<boolean>;
 }
 
@@ -227,12 +234,16 @@ export interface TelegramPreviewRenderedChunkTransportDeps {
   sendRenderedChunks: (
     chatId: number,
     chunks: TelegramRenderedChunk[],
-    options?: { replyToMessageId?: number },
+    options?: {
+      replyToMessageId?: number;
+      replyMarkup?: TelegramPreviewReplyMarkup;
+    },
   ) => Promise<number | undefined>;
   editRenderedMessage: (
     chatId: number,
     messageId: number,
     chunks: TelegramRenderedChunk[],
+    options?: { replyMarkup?: TelegramPreviewReplyMarkup },
   ) => Promise<number | undefined>;
 }
 
@@ -243,9 +254,13 @@ export function createTelegramPreviewRenderedChunkTransport(
   "sendRenderedChunks" | "editRenderedMessage"
 > {
   return {
-    sendRenderedChunks: (chatId, chunks, replyToMessageId) =>
-      deps.sendRenderedChunks(chatId, chunks, { replyToMessageId }),
-    editRenderedMessage: deps.editRenderedMessage,
+    sendRenderedChunks: (chatId, chunks, replyToMessageId, options) =>
+      deps.sendRenderedChunks(chatId, chunks, {
+        replyToMessageId,
+        ...(options?.replyMarkup ? { replyMarkup: options.replyMarkup } : {}),
+      }),
+    editRenderedMessage: (chatId, messageId, chunks, options) =>
+      deps.editRenderedMessage(chatId, messageId, chunks, options),
   };
 }
 
@@ -364,11 +379,12 @@ export function createTelegramPreviewController(
       ),
     editMessageText: deps.editMessageText,
     renderTelegramMessage: renderMessage,
-    sendRenderedChunks: (chatId, chunks) =>
+    sendRenderedChunks: (chatId, chunks, options) =>
       deps.sendRenderedChunks(
         chatId,
         chunks,
         replyToMessageId ?? deps.getDefaultReplyToMessageId?.(),
+        options,
       ),
     editRenderedMessage: deps.editRenderedMessage,
   });
@@ -394,11 +410,12 @@ export function createTelegramPreviewController(
     },
     finalize: (chatId, replyToMessageId) =>
       finalizeTelegramPreview(chatId, getRuntimeDeps(replyToMessageId)),
-    finalizeMarkdown: (chatId, markdown, replyToMessageId) =>
+    finalizeMarkdown: (chatId, markdown, replyToMessageId, options) =>
       finalizeTelegramMarkdownPreview(
         chatId,
         markdown,
         getRuntimeDeps(replyToMessageId),
+        options,
       ),
   };
 }
@@ -453,7 +470,9 @@ export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
     state = deps.createPreviewState();
     deps.setState(state);
   }
-  state.pendingText = deps.getMessageText(message);
+  state.pendingText = stripTelegramCommentMarkupForPreview(
+    deps.getMessageText(message),
+  );
   deps.schedulePreviewFlush(turn.chatId);
 }
 
@@ -613,6 +632,7 @@ export async function finalizeTelegramMarkdownPreview(
   chatId: number,
   markdown: string,
   deps: TelegramPreviewRuntimeDeps,
+  options?: { replyMarkup?: TelegramPreviewReplyMarkup },
 ): Promise<boolean> {
   const state = deps.getState();
   if (!state) return false;
@@ -623,12 +643,12 @@ export async function finalizeTelegramMarkdownPreview(
     return false;
   }
   if (state.mode === "draft") {
-    await deps.sendRenderedChunks(chatId, chunks);
+    await deps.sendRenderedChunks(chatId, chunks, options);
     await clearTelegramPreview(chatId, deps);
     return true;
   }
   if (state.messageId === undefined) return false;
-  await deps.editRenderedMessage(chatId, state.messageId, chunks);
+  await deps.editRenderedMessage(chatId, state.messageId, chunks, options);
   deps.setState(undefined);
   return true;
 }

package/lib/prompts.ts

@@ -11,9 +11,13 @@ const SYSTEM_PROMPT_SUFFIX = `
 Telegram bridge extension is active.
 - Messages forwarded from Telegram are prefixed with "[telegram]".
 - [telegram] messages may include [attachments] sections with a base directory plus relative local file entries. Resolve and read those files as needed.
+- [telegram] messages may include a [reply] block after the user's current text. Treat [reply] as quoted context from the Telegram message the user replied to, not as a new instruction by itself; use it to resolve references like "this", "it", or "that message". The actual new user instruction is the message text before [reply], unless it explicitly asks you to act on the quoted context.
 - Telegram is often read on narrow phone screens, so prefer narrow table columns when presenting tabular data; wide monospace tables can become unreadable.
 - If a [telegram] user asked for a file or generated artifact, use telegram_attach with the local path instead of only mentioning the path in text.
-- Do not assume mentioning a local file path in plain text will send it to Telegram. Use telegram_attach.`;
+- Do not assume mentioning a local file path in plain text will send it to Telegram. Use telegram_attach.
+- For Telegram-native outbound actions, use hidden top-level Markdown comments instead of agent-side tool calls: write a normal answer plus correctly formatted column-zero \`telegram_voice\` or \`telegram_button\` blocks outside code, quotes, and lists. The bridge handles delivery after \`agent_end\`, so do not call or register transport/TTS/text-to-OGG tools for these actions.
+- A \`telegram_voice\` block body is the text to synthesize through the extension's configured outbound-handler pipeline. It may be a short companion summary when useful, but no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
+- Button blocks should contain quick reply prompts the user can tap; use independent blocks like \`<!-- telegram_button label="OK"\nPrompt text\n-->\`, or \`<!-- telegram_button label="OK" -->\` when the prompt should equal the label. The callback prompt is routed back as a normal Telegram turn.`;
 
 export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;

package/lib/queue.ts

@@ -720,6 +720,21 @@ export interface TelegramAgentEndAssistantResult {
   errorMessage?: string;
 }
 
+export interface TelegramAgentEndOutboundVoiceReply {
+  text: string;
+  lang?: string;
+  rate?: string;
+}
+
+export interface TelegramAgentEndOutboundReplyPlan<TReplyMarkup = unknown> {
+  markdown: string;
+  replyMarkup?: TReplyMarkup;
+  voiceText?: string;
+  voiceReplies?: TelegramAgentEndOutboundVoiceReply[];
+  lang?: string;
+  rate?: string;
+}
+
 export interface TelegramAgentEndRuntimeDeps<
   TTurn extends PendingTelegramTurn,
 > {
@@ -735,11 +750,13 @@ export interface TelegramAgentEndRuntimeDeps<
     chatId: number,
     markdown: string,
     replyToMessageId: number,
+    options?: { replyMarkup?: unknown },
   ) => Promise<boolean>;
   sendMarkdownReply: (
     chatId: number,
     replyToMessageId: number,
     markdown: string,
+    options?: { replyMarkup?: unknown },
   ) => Promise<unknown>;
   sendTextReply: (
     chatId: number,
@@ -747,6 +764,12 @@ export interface TelegramAgentEndRuntimeDeps<
     text: string,
   ) => Promise<unknown>;
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
+  planOutboundReply?: (markdown: string) => TelegramAgentEndOutboundReplyPlan;
+  sendOutboundReplyArtifacts?: (
+    turn: TTurn,
+    plan: TelegramAgentEndOutboundReplyPlan,
+    options?: { replyToPrompt?: boolean },
+  ) => Promise<void>;
 }
 
 export interface TelegramAgentEndHookRuntimeDeps<
@@ -768,6 +791,8 @@ export interface TelegramAgentEndHookRuntimeDeps<
   sendMarkdownReply: TelegramAgentEndRuntimeDeps<TTurn>["sendMarkdownReply"];
   sendTextReply: TelegramAgentEndRuntimeDeps<TTurn>["sendTextReply"];
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
+  planOutboundReply?: TelegramAgentEndRuntimeDeps<TTurn>["planOutboundReply"];
+  sendOutboundReplyArtifacts?: TelegramAgentEndRuntimeDeps<TTurn>["sendOutboundReplyArtifacts"];
 }
 
 export interface TelegramAgentEndHookEvent<TMessage> {
@@ -865,6 +890,8 @@ export function createTelegramAgentEndHook<
       sendMarkdownReply: deps.sendMarkdownReply,
       sendTextReply: deps.sendTextReply,
       sendQueuedAttachments: deps.sendQueuedAttachments,
+      planOutboundReply: deps.planOutboundReply,
+      sendOutboundReplyArtifacts: deps.sendOutboundReplyArtifacts,
     });
   };
 }
@@ -873,13 +900,20 @@ export async function handleTelegramAgentEndRuntime<
   TTurn extends PendingTelegramTurn,
 >(deps: TelegramAgentEndRuntimeDeps<TTurn>): Promise<void> {
   const { turn, assistant } = deps;
-  const finalText = assistant.text;
+  const rawFinalText = assistant.text;
+  const outboundReply = rawFinalText
+    ? deps.planOutboundReply?.(rawFinalText)
+    : undefined;
+  const finalText = outboundReply ? outboundReply.markdown : rawFinalText;
+  const hasOutboundArtifacts =
+    !!outboundReply?.voiceText || !!outboundReply?.voiceReplies?.length;
+  const replyMarkup = outboundReply?.replyMarkup;
   deps.resetRuntimeState();
   deps.updateStatus();
   const endPlan = buildTelegramAgentEndPlan({
     hasTurn: !!turn,
     stopReason: assistant.stopReason,
-    hasFinalText: !!finalText,
+    hasFinalText: !!finalText || hasOutboundArtifacts,
     hasQueuedAttachments: (turn?.queuedAttachments.length ?? 0) > 0,
     preserveQueuedTurnsAsHistory: deps.preserveQueuedTurnsAsHistory,
   });
@@ -901,11 +935,13 @@ export async function handleTelegramAgentEndRuntime<
     return;
   }
   if (finalText) deps.setPreviewPendingText(finalText);
+  if (!finalText && hasOutboundArtifacts) await deps.clearPreview(turn.chatId);
   if (endPlan.kind === "text" && finalText) {
     const finalized = await deps.finalizeMarkdownPreview(
       turn.chatId,
       finalText,
       turn.replyToMessageId,
+      { replyMarkup },
     );
     if (!finalized) {
       await deps.clearPreview(turn.chatId);
@@ -913,9 +949,15 @@ export async function handleTelegramAgentEndRuntime<
         turn.chatId,
         turn.replyToMessageId,
         finalText,
+        { replyMarkup },
       );
     }
   }
+  if (outboundReply && deps.sendOutboundReplyArtifacts) {
+    await deps.sendOutboundReplyArtifacts(turn, outboundReply, {
+      replyToPrompt: !finalText,
+    });
+  }
   if (endPlan.shouldSendAttachmentNotice) {
     await deps.sendTextReply(
       turn.chatId,

package/lib/replies.ts

@@ -174,13 +174,14 @@ export async function editTelegramRenderedMessage<TReplyMarkup>(
   return messageId;
 }
 
-export interface TelegramReplyRuntimeDeps {
+export interface TelegramReplyRuntimeDeps<TReplyMarkup = unknown> {
   renderTelegramMessage: (
     text: string,
     options?: { mode?: TelegramRenderMode },
   ) => TelegramRenderedChunk[];
   sendRenderedChunks: (
     chunks: TelegramRenderedChunk[],
+    options?: { replyMarkup?: TReplyMarkup },
   ) => Promise<number | undefined>;
 }
 
@@ -195,15 +196,16 @@ export async function sendTelegramPlainReply(
   return deps.sendRenderedChunks(chunks);
 }
 
-export async function sendTelegramMarkdownReply(
+export async function sendTelegramMarkdownReply<TReplyMarkup = unknown>(
   markdown: string,
   deps: TelegramReplyRuntimeDeps,
+  options?: { replyMarkup?: TReplyMarkup },
 ): Promise<number | undefined> {
   const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
   if (chunks.length === 0) {
     return sendTelegramPlainReply(markdown, deps);
   }
-  return deps.sendRenderedChunks(chunks);
+  return deps.sendRenderedChunks(chunks, options);
 }
 
 export interface TelegramRenderedMessageRuntimeDeps<TReplyMarkup> {
@@ -225,6 +227,7 @@ export interface TelegramRenderedMessageRuntime<TReplyMarkup> {
     chatId: number,
     replyToMessageId: number,
     markdown: string,
+    options?: { replyMarkup?: unknown },
   ) => Promise<number | undefined>;
   editInteractiveMessage: (
     chatId: number,
@@ -290,14 +293,21 @@ export function createTelegramRenderedMessageRuntime<TReplyMarkup>(
         options,
       );
     },
-    sendMarkdownReply: async (chatId, replyToMessageId, markdown) => {
-      return sendTelegramMarkdownReply(markdown, {
-        renderTelegramMessage: deps.renderTelegramMessage,
-        sendRenderedChunks: (chunks) =>
-          deps.replyTransport.sendRenderedChunks(chatId, chunks, {
-            replyToMessageId,
-          }),
-      });
+    sendMarkdownReply: async (chatId, replyToMessageId, markdown, options) => {
+      return sendTelegramMarkdownReply(
+        markdown,
+        {
+          renderTelegramMessage: deps.renderTelegramMessage,
+          sendRenderedChunks: (chunks, chunkOptions) =>
+            deps.replyTransport.sendRenderedChunks(chatId, chunks, {
+              replyToMessageId,
+              replyMarkup: chunkOptions?.replyMarkup as
+                | TReplyMarkup
+                | undefined,
+            }),
+        },
+        options,
+      );
     },
     editInteractiveMessage: async (
       chatId,

package/lib/routing.ts

@@ -3,9 +3,10 @@
  * Wires authorized updates into menus, commands, media grouping, and prompt queueing
  */
 
+import * as OutboundHandlers from "./outbound-handlers.ts";
 import * as Commands from "./commands.ts";
 import type { TelegramConfigStore } from "./config.ts";
-import type { TelegramAttachmentHandlerRuntime } from "./handlers.ts";
+import type { TelegramAttachmentHandlerRuntime } from "./attachment-handlers.ts";
 import * as Media from "./media.ts";
 import * as Menu from "./menu.ts";
 import * as Model from "./model.ts";
@@ -50,6 +51,7 @@ export interface TelegramInboundRouteRuntimeDeps<
     Model.ScopedTelegramModel<TModel>
   >;
   menuActions: Menu.TelegramMenuActionRuntime<TContext, TModel>;
+  buttonActionStore?: OutboundHandlers.TelegramButtonActionStore;
   attachmentHandlerRuntime: TelegramAttachmentHandlerRuntime<TContext>;
   updateStatus: (ctx: TContext, error?: string) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
@@ -99,7 +101,7 @@ export function createTelegramInboundRouteRuntime<
     TModel
   >,
 ): Updates.TelegramUpdateRuntimeController<TContext, TUpdate> {
-  const callbackHandler = Menu.createTelegramMenuCallbackHandlerForContext<
+  const menuCallbackHandler = Menu.createTelegramMenuCallbackHandlerForContext<
     TCallbackQuery,
     TContext,
     TModel
@@ -124,6 +126,41 @@ export function createTelegramInboundRouteRuntime<
     restartInterruptedTelegramTurn:
       deps.modelSwitchController.restartInterruptedTurn,
   });
+  const callbackHandler = async (
+    query: TCallbackQuery,
+    ctx: TContext,
+  ): Promise<void> => {
+    if (deps.buttonActionStore) {
+      const handled = await OutboundHandlers.handleTelegramButtonCallbackQuery(
+        query,
+        ctx,
+        {
+          resolveAction: deps.buttonActionStore.resolve,
+          answerCallbackQuery: deps.answerCallbackQuery,
+          enqueueButtonPrompt: (buttonQuery, action, context) => {
+            const chatId = buttonQuery.message?.chat?.id;
+            const messageId = buttonQuery.message?.message_id;
+            if (typeof chatId !== "number" || typeof messageId !== "number")
+              return;
+            const queueOrder = deps.bridgeRuntime.queue.allocateItemOrder();
+            deps.queueMutationRuntime.append(
+              OutboundHandlers.createTelegramButtonPromptTurn({
+                chatId,
+                replyToMessageId: messageId,
+                queueOrder,
+                action,
+              }),
+              context,
+            );
+            deps.updateStatus(context);
+            deps.dispatchNextQueuedTelegramTurn(context);
+          },
+        },
+      );
+      if (handled) return;
+    }
+    await menuCallbackHandler(query, ctx);
+  };
   const commandHandler = Commands.createTelegramCommandHandlerTargetRuntime<
     TMessage,
     TContext

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "private": false,
   "description": "Better Telegram DM bridge extension for pi",
   "type": "module",