@llblab/pi-telegram 0.6.0 → 0.6.2

package/README.md

@@ -171,7 +171,7 @@ A TTS plus MP3-to-OGG setup can be expressed as `template: [...]`. The bridge pr
 
 #### Buttons
 
-Button blocks attach inline quick replies to the final text. Use one independent `telegram_button` block per action; its `label` is shown in Telegram and its body is sent back to pi when tapped:
+Button blocks attach inline quick replies to the final text. Use one independent `telegram_button` block per action; its `label` is shown in Telegram and its body is sent back to pi when tapped. If the prompt should equal the label, the body can be omitted:
 
 ```md
 I can continue.
@@ -179,6 +179,8 @@ I can continue.
 <!-- telegram_button label="Continue"
 Continue with the current plan.
 -->
+
+<!-- telegram_button label="OK" -->
 ```
 
 Button prompts are routed back into the normal Telegram queue as prompt turns. Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).

package/docs/architecture.md

@@ -112,7 +112,7 @@ Dispatch is gated by:
 - `ctx.isIdle()` being true
 - `ctx.hasPendingMessages()` being false
 
-This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Telegram `/status` and `/model` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
+This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Post-agent-end dispatch retries are scheduled through a session-bound deferred dispatcher that activates on session start, cancels timers on session shutdown, and skips callbacks from older generations before they touch `ExtensionContext`. Telegram `/status` and `/model` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
 
 ### Abort Behavior
 
@@ -155,7 +155,7 @@ Telegram prompt responses use explicit delivery context to attach outbound text,
 
 Outbound files are sent only after the active Telegram turn completes, must be staged through the `telegram_attach` tool, are staged atomically per tool call, are checked against a default 50 MiB limit configurable through `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`, and use file-backed multipart blobs so large sends do not require preloading whole files into memory.
 
-Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes the block body through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, top-level `timeout` wraps the whole sequence, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn. This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
+Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes the block body through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, top-level `timeout` wraps the whole sequence, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text, or the button label when the body is omitted, as a normal Telegram prompt turn. This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
 
 ## Interactive Controls
 

package/docs/attachment-handlers.md

@@ -39,7 +39,7 @@ Attachment handlers support these built-in placeholders:
 
 `defaults` may provide additional placeholder values such as `{lang}` or `{model}`. `args` is only a string-array declaration of supported placeholders; defaults belong in `defaults` or inline placeholders such as `{lang=ru}`. Examples prefer explicit flag-style CLIs for readability, but positional forms such as `/path/to/stt {file} {lang=ru} {model=voxtral-mini-latest}` are equally valid when the target script supports them.
 
-If a top-level one-step handler template has no `{file}` placeholder, the downloaded file path is appended as the last command arg for backwards compatibility. Composition steps are plain command templates and do not receive implicit file-path args; include `{file}` explicitly where needed.
+If a top-level one-step handler template has no `{file}` placeholder, the downloaded file path is appended as the last command arg as a one-step handler convenience. Composition steps are plain command templates and do not receive implicit file-path args; include `{file}` explicitly where needed.
 
 ## Ordered Fallbacks
 

package/docs/outbound-handlers.md

@@ -75,7 +75,7 @@ For one-step `template` handlers, stdout remains the default result channel: the
 
 ## Buttons Markup
 
-Assistant replies can include independent button blocks. The block body is the prompt sent back to pi when the user taps the button:
+Assistant replies can include independent button blocks. The block body is the prompt sent back to pi when the user taps the button; omit the body when the prompt should equal the label:
 
 ```md
 I can continue.
@@ -87,11 +87,13 @@ Continue with the current plan.
 <!-- telegram_button label="Show risks"
 List the main risks first.
 -->
+
+<!-- telegram_button label="Done" -->
 ```
 
 Rules:
 
-- `telegram_button label="Label"` creates one independent button row whose prompt is the block body.
+- `telegram_button label="Label"` creates one independent button row whose prompt is the block body, or the label itself when the body is omitted.
 - The opening `<!-- telegram_button` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown.
 - Use one block per button; this mirrors HTML's singular element model and avoids a nested button DSL inside comments.
 - Button actions are stored in memory with short `callback_data`; Telegram never sees the full prompt in the button payload.

package/index.ts

@@ -46,10 +46,16 @@ export default function (pi: Pi.ExtensionAPI) {
   const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
     getBotToken: configStore.getBotToken,
   });
-  const mediaGroupRuntime =
-    Media.createTelegramMediaGroupController<Api.TelegramMessage>();
+  const mediaGroupRuntime = Media.createTelegramMediaGroupController<
+    Api.TelegramMessage,
+    Pi.ExtensionContext
+  >();
   const telegramQueueStore =
     Queue.createTelegramQueueStore<Pi.ExtensionContext>();
+  const deferredQueueDispatchRuntime =
+    Queue.createTelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>({
+      recordRuntimeEvent: runtimeEvents.record,
+    });
   const pollingControllerState = Polling.createTelegramPollingControllerState();
   const { getStatusLines, updateStatus } =
     Status.createTelegramBridgeStatusRuntime<
@@ -88,12 +94,14 @@ export default function (pi: Pi.ExtensionAPI) {
       updateStatus,
     });
   const attachmentHandlerRuntime =
-    AttachmentHandlers.createTelegramAttachmentHandlerRuntime<Pi.ExtensionContext>({
-      getHandlers: configStore.getAttachmentHandlers,
-      execCommand: CommandTemplates.execCommandTemplate,
-      getCwd: Pi.getExtensionContextCwd,
-      recordRuntimeEvent: runtimeEvents.record,
-    });
+    AttachmentHandlers.createTelegramAttachmentHandlerRuntime<Pi.ExtensionContext>(
+      {
+        getHandlers: configStore.getAttachmentHandlers,
+        execCommand: CommandTemplates.execCommandTemplate,
+        getCwd: Pi.getExtensionContextCwd,
+        recordRuntimeEvent: runtimeEvents.record,
+      },
+    );
 
   // --- Telegram API ---
 
@@ -149,6 +157,7 @@ export default function (pi: Pi.ExtensionAPI) {
       hasDispatchPending: bridgeRuntime.lifecycle.hasDispatchPending,
       isIdle: Pi.isExtensionContextIdle,
       hasPendingMessages: Pi.hasExtensionContextPendingMessages,
+      hasDispatchContext: deferredQueueDispatchRuntime.isBound,
       updateStatus,
       sendTextReply,
       recordRuntimeEvent: runtimeEvents.record,
@@ -274,8 +283,10 @@ export default function (pi: Pi.ExtensionAPI) {
       setPendingModelSwitch: pendingModelSwitchStore.set,
       syncCounters: bridgeRuntime.queue.syncCounters,
       syncFlags: bridgeRuntime.lifecycle.syncFlags,
+      bindDeferredDispatchContext: deferredQueueDispatchRuntime.bind,
       prepareTempDir,
       updateStatus,
+      unbindDeferredDispatchContext: deferredQueueDispatchRuntime.unbind,
       clearPendingMediaGroups: mediaGroupRuntime.clear,
       clearModelMenuState: modelMenuRuntime.clear,
       getActiveTurnChatId: activeTurnRuntime.getChatId,
@@ -352,6 +363,8 @@ export default function (pi: Pi.ExtensionAPI) {
         clearDispatchPending: bridgeRuntime.lifecycle.clearDispatchPending,
       }),
       dispatchNextQueuedTelegramTurn,
+      requestDeferredDispatchNextQueuedTelegramTurn:
+        deferredQueueDispatchRuntime.request,
       clearPreview: previewRuntime.clear,
       setPreviewPendingText: previewRuntime.setPendingText,
       finalizeMarkdownPreview: previewRuntime.finalizeMarkdown,
@@ -362,16 +375,16 @@ export default function (pi: Pi.ExtensionAPI) {
         sendTextReply,
         recordRuntimeEvent: runtimeEvents.record,
       }),
-      planOutboundReply: OutboundHandlers.createTelegramOutboundReplyPlanner(
-        buttonActionStore,
-      ),
-      sendOutboundReplyArtifacts: OutboundHandlers.createTelegramOutboundReplyArtifactSender({
-        execCommand: CommandTemplates.execCommandTemplate,
-        sendMultipart: callMultipart,
-        sendTextReply,
-        getHandlers: configStore.getOutboundHandlers,
-        recordRuntimeEvent: runtimeEvents.record,
-      }),
+      planOutboundReply:
+        OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
+      sendOutboundReplyArtifacts:
+        OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+          execCommand: CommandTemplates.execCommandTemplate,
+          sendMultipart: callMultipart,
+          sendTextReply,
+          getHandlers: configStore.getOutboundHandlers,
+          recordRuntimeEvent: runtimeEvents.record,
+        }),
       getActiveToolExecutions: bridgeRuntime.lifecycle.getActiveToolExecutions,
       setActiveToolExecutions: bridgeRuntime.lifecycle.setActiveToolExecutions,
       triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,

package/lib/command-templates.ts

@@ -33,6 +33,7 @@ export interface CommandTemplateExecOptions {
   timeout?: number;
   signal?: AbortSignal;
   stdin?: string;
+  killGrace?: number;
 }
 
 export interface CommandTemplateExecResult {
@@ -207,18 +208,20 @@ export function execCommandTemplate(
     let killed = false;
     let settled = false;
     let timeoutId: NodeJS.Timeout | undefined;
+    let killTimeoutId: NodeJS.Timeout | undefined;
     const killProcess = (): void => {
       if (killed) return;
       killed = true;
       proc.kill("SIGTERM");
-      setTimeout(() => {
-        if (!proc.killed) proc.kill("SIGKILL");
-      }, 5000);
+      killTimeoutId = setTimeout(() => {
+        if (!settled) proc.kill("SIGKILL");
+      }, options.killGrace ?? 5000);
     };
     const settle = (code: number): void => {
       if (settled) return;
       settled = true;
       if (timeoutId) clearTimeout(timeoutId);
+      if (killTimeoutId) clearTimeout(killTimeoutId);
       if (options.signal)
         options.signal.removeEventListener("abort", killProcess);
       resolve({ stdout, stderr, code, killed });

package/lib/locks.ts

@@ -246,13 +246,6 @@ export function createTelegramLockedPollingRuntime<
     clearInterval(ownershipInterval);
     ownershipInterval = undefined;
   };
-  const updateStatusSafely = (ctx: TContext, phase: string) => {
-    try {
-      deps.updateStatus(ctx);
-    } catch (error) {
-      deps.recordRuntimeEvent?.("lock", error, { phase });
-    }
-  };
   const suspendPolling = async () => {
     stopOwnershipWatcher();
     if (ownershipStop) {
@@ -261,7 +254,7 @@ export function createTelegramLockedPollingRuntime<
     }
     await deps.stopPolling();
   };
-  const stopAfterOwnershipLoss = (ctx: TContext) => {
+  const stopAfterOwnershipLoss = () => {
     if (ownershipStop) return;
     stopOwnershipWatcher();
     ownershipStop = deps
@@ -271,7 +264,6 @@ export function createTelegramLockedPollingRuntime<
       )
       .finally(() => {
         ownershipStop = undefined;
-        updateStatusSafely(ctx, "ownership-loss-status");
       });
   };
   const startOwnershipWatcher = (ctx: TContext) => {
@@ -279,7 +271,7 @@ export function createTelegramLockedPollingRuntime<
     stopOwnershipWatcher();
     ownershipInterval = setInterval(() => {
       if (deps.lock.owns(owner)) return;
-      stopAfterOwnershipLoss(ctx);
+      stopAfterOwnershipLoss();
     }, ownershipCheckMs);
     ownershipInterval.unref?.();
   };

package/lib/media.ts

@@ -59,17 +59,20 @@ export interface TelegramMediaGroupMessage {
   media_group_id?: string;
 }
 
-export interface TelegramMediaGroupState<TMessage> {
+export interface TelegramMediaGroupState<TMessage, TContext = unknown> {
   messages: TMessage[];
+  context?: TContext;
   flushTimer?: ReturnType<typeof setTimeout>;
 }
 
 export interface TelegramMediaGroupController<
   TMessage extends TelegramMediaGroupMessage,
+  TContext = unknown,
 > {
   queueMessage: (options: {
     message: TMessage;
-    dispatchMessages: (messages: TMessage[]) => void;
+    context?: TContext;
+    dispatchMessages: (messages: TMessage[], ctx?: TContext) => void;
   }) => boolean;
   removeMessages: (messageIds: number[]) => number;
   clear: () => void;
@@ -79,7 +82,7 @@ export interface TelegramMediaGroupDispatchRuntimeDeps<
   TMessage extends TelegramMediaGroupMessage,
   TContext,
 > {
-  mediaGroups: TelegramMediaGroupController<TMessage>;
+  mediaGroups: TelegramMediaGroupController<TMessage, TContext>;
   dispatchMessages: (messages: TMessage[], ctx: TContext) => Promise<void>;
 }
 
@@ -249,7 +252,7 @@ export function getTelegramMediaGroupKey(
 export function removePendingTelegramMediaGroupMessages<
   TMessage extends TelegramMediaGroupMessage,
 >(
-  groups: Map<string, TelegramMediaGroupState<TMessage>>,
+  groups: Map<string, TelegramMediaGroupState<TMessage, unknown>>,
   messageIds: number[],
   clearTimer: (timer: ReturnType<typeof setTimeout>) => void,
 ): number {
@@ -273,24 +276,27 @@ export function removePendingTelegramMediaGroupMessages<
 
 export function queueTelegramMediaGroupMessage<
   TMessage extends TelegramMediaGroupMessage,
+  TContext = unknown,
 >(options: {
   message: TMessage;
-  groups: Map<string, TelegramMediaGroupState<TMessage>>;
+  context?: TContext;
+  groups: Map<string, TelegramMediaGroupState<TMessage, TContext>>;
   debounceMs: number;
   setTimer: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
   clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
-  dispatchMessages: (messages: TMessage[]) => void;
+  dispatchMessages: (messages: TMessage[], ctx?: TContext) => void;
 }): boolean {
   const key = getTelegramMediaGroupKey(options.message);
   if (!key) return false;
   const existing = options.groups.get(key) ?? { messages: [] };
   existing.messages.push(options.message);
+  existing.context = options.context;
   if (existing.flushTimer) options.clearTimer(existing.flushTimer);
   existing.flushTimer = options.setTimer(() => {
     const state = options.groups.get(key);
     options.groups.delete(key);
     if (!state) return;
-    options.dispatchMessages(state.messages);
+    options.dispatchMessages(state.messages, state.context);
   }, options.debounceMs);
   options.groups.set(key, existing);
   return true;
@@ -298,10 +304,11 @@ export function queueTelegramMediaGroupMessage<
 
 export function createTelegramMediaGroupController<
   TMessage extends TelegramMediaGroupMessage,
+  TContext = unknown,
 >(
   options: TelegramMediaGroupControllerOptions = {},
-): TelegramMediaGroupController<TMessage> {
-  const groups = new Map<string, TelegramMediaGroupState<TMessage>>();
+): TelegramMediaGroupController<TMessage, TContext> {
+  const groups = new Map<string, TelegramMediaGroupState<TMessage, TContext>>();
   const debounceMs = options.debounceMs ?? TELEGRAM_MEDIA_GROUP_DEBOUNCE_MS;
   const setTimer =
     options.setTimer ??
@@ -309,9 +316,10 @@ export function createTelegramMediaGroupController<
       setTimeout(callback, ms));
   const clearTimer = options.clearTimer ?? clearTimeout;
   return {
-    queueMessage: ({ message, dispatchMessages }) =>
+    queueMessage: ({ message, context, dispatchMessages }) =>
       queueTelegramMediaGroupMessage({
         message,
+        context,
         groups,
         debounceMs,
         setTimer,
@@ -339,8 +347,11 @@ export function createTelegramMediaGroupDispatchRuntime<
     handleMessage: async (message, ctx) => {
       const queuedMediaGroup = deps.mediaGroups.queueMessage({
         message,
-        dispatchMessages: (messages) => {
-          void deps.dispatchMessages(messages, ctx);
+        context: ctx,
+        dispatchMessages: (messages, queuedCtx) => {
+          if (queuedCtx !== undefined) {
+            void deps.dispatchMessages(messages, queuedCtx);
+          }
         },
       });
       if (queuedMediaGroup) return;

package/lib/outbound-handlers.ts

@@ -101,6 +101,11 @@ interface TelegramTopLevelHtmlComment {
   end: number;
 }
 
+interface TelegramTopLevelFenceState {
+  marker: "`" | "~";
+  length: number;
+}
+
 function getMarkdownLineEnd(markdown: string, offset: number): number {
   const newlineIndex = markdown.indexOf("\n", offset);
   return newlineIndex === -1 ? markdown.length : newlineIndex + 1;
@@ -114,9 +119,29 @@ function getMarkdownLineText(
   return markdown.slice(offset, end).replace(/\r?\n$/, "");
 }
 
-function getTopLevelFenceMarker(line: string): "```" | "~~~" | undefined {
-  const match = line.match(/^(?: {0,3})(```|~~~)/);
-  return match?.[1] as "```" | "~~~" | undefined;
+function getTopLevelOpeningFence(
+  line: string,
+): TelegramTopLevelFenceState | undefined {
+  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})/);
+  const sequence = match?.[1];
+  if (!sequence) return undefined;
+  return {
+    marker: sequence[0] as "`" | "~",
+    length: sequence.length,
+  };
+}
+
+function isTopLevelClosingFence(
+  line: string,
+  fence: TelegramTopLevelFenceState,
+): boolean {
+  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})([ \t]*)$/);
+  const sequence = match?.[1];
+  return (
+    !!sequence &&
+    sequence[0] === fence.marker &&
+    sequence.length >= fence.length
+  );
 }
 
 function collectTopLevelHtmlComments(markdown: string): {
@@ -125,18 +150,18 @@ function collectTopLevelHtmlComments(markdown: string): {
 } {
   const comments: TelegramTopLevelHtmlComment[] = [];
   let offset = 0;
-  let fenceMarker: "```" | "~~~" | undefined;
+  let fence: TelegramTopLevelFenceState | undefined;
   while (offset < markdown.length) {
     const lineEnd = getMarkdownLineEnd(markdown, offset);
     const line = getMarkdownLineText(markdown, offset, lineEnd);
-    if (fenceMarker) {
-      if (line.startsWith(fenceMarker)) fenceMarker = undefined;
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) fence = undefined;
       offset = lineEnd;
       continue;
     }
-    const nextFenceMarker = getTopLevelFenceMarker(line);
-    if (nextFenceMarker) {
-      fenceMarker = nextFenceMarker;
+    const nextFence = getTopLevelOpeningFence(line);
+    if (nextFence) {
+      fence = nextFence;
       offset = lineEnd;
       continue;
     }
@@ -174,19 +199,19 @@ function findTopLevelOpenOrPartialHtmlCommentIndex(markdown: string): number {
   const { openCommentStart } = collectTopLevelHtmlComments(markdown);
   if (openCommentStart !== undefined) return openCommentStart;
   let offset = 0;
-  let fenceMarker: "```" | "~~~" | undefined;
+  let fence: TelegramTopLevelFenceState | undefined;
   while (offset < markdown.length) {
     const lineEnd = getMarkdownLineEnd(markdown, offset);
     const line = getMarkdownLineText(markdown, offset, lineEnd);
     const isLastLine = lineEnd >= markdown.length;
-    if (fenceMarker) {
-      if (line.startsWith(fenceMarker)) fenceMarker = undefined;
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) fence = undefined;
       offset = lineEnd;
       continue;
     }
-    const nextFenceMarker = getTopLevelFenceMarker(line);
-    if (nextFenceMarker) {
-      fenceMarker = nextFenceMarker;
+    const nextFence = getTopLevelOpeningFence(line);
+    if (nextFence) {
+      fence = nextFence;
       offset = lineEnd;
       continue;
     }
@@ -251,9 +276,8 @@ function normalizeMarkdownAfterVoiceExtraction(markdown: string): string {
 
 export function stripTelegramCommentMarkupForPreview(markdown: string): string {
   const withoutClosedBlocks = replaceTopLevelHtmlComments(markdown, () => "");
-  const openBlockIndex = findTopLevelOpenOrPartialHtmlCommentIndex(
-    withoutClosedBlocks,
-  );
+  const openBlockIndex =
+    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
   const previewMarkdown =
     openBlockIndex >= 0
       ? withoutClosedBlocks.slice(0, openBlockIndex)
@@ -265,9 +289,8 @@ export function stripTelegramCommentMarkupForDelivery(
   markdown: string,
 ): string {
   const withoutClosedBlocks = replaceTopLevelHtmlComments(markdown, () => "");
-  const openBlockIndex = findTopLevelOpenOrPartialHtmlCommentIndex(
-    withoutClosedBlocks,
-  );
+  const openBlockIndex =
+    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
   const deliveryMarkdown =
     openBlockIndex >= 0
       ? withoutClosedBlocks.slice(0, openBlockIndex)
@@ -343,7 +366,9 @@ function getVoiceReplyCompositionStepTimeout(
 ): number {
   const remaining = getRemainingVoiceReplyTimeout(handlerTimeout, startedAt);
   const stepTimeout = getVoiceReplyConfiguredTimeout(step);
-  return stepTimeout === undefined ? remaining : Math.min(stepTimeout, remaining);
+  return stepTimeout === undefined
+    ? remaining
+    : Math.min(stepTimeout, remaining);
 }
 
 function formatVoiceReplyExecutionFailure(
@@ -704,8 +729,8 @@ function parseButtonsCommentRows(
   body: string | undefined,
 ): TelegramOutboundButtonAction[][] {
   const attributes = parseButtonsCommentAttributes(head);
-  const prompt = body?.trim();
-  if (!attributes.label || !prompt) return [];
+  if (!attributes.label) return [];
+  const prompt = body?.trim() || attributes.label;
   return [[{ text: attributes.label, prompt }]];
 }
 

package/lib/polling.ts

@@ -97,7 +97,7 @@ export interface TelegramPollingRuntimeDeps<TContext> {
   setPollingController: (controller: AbortController | undefined) => void;
   stopTypingLoop: () => unknown;
   runPollLoop: (ctx: TContext, signal: AbortSignal) => Promise<void>;
-  updateStatus: (ctx: TContext) => void;
+  updateStatus: (ctx: TContext, message?: string) => void;
   createAbortController?: () => AbortController;
 }
 

package/lib/prompts.ts

@@ -17,7 +17,7 @@ Telegram bridge extension is active.
 - 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-->\`. The callback prompt is routed back as a normal Telegram turn.`;
+- 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

@@ -785,6 +785,9 @@ export interface TelegramAgentEndHookRuntimeDeps<
   resetRuntimeState: () => void;
   updateStatus: (ctx: TContext) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
+  requestDeferredDispatchNextQueuedTelegramTurn: (
+    dispatch: (ctx: TContext) => void,
+  ) => void;
   clearPreview: (chatId: number) => Promise<void>;
   setPreviewPendingText: (text: string) => void;
   finalizeMarkdownPreview: TelegramAgentEndRuntimeDeps<TTurn>["finalizeMarkdownPreview"];
@@ -882,7 +885,9 @@ export function createTelegramAgentEndHook<
       resetRuntimeState: deps.resetRuntimeState,
       updateStatus: () => deps.updateStatus(ctx),
       dispatchNextQueuedTelegramTurn: () => {
-        setTimeout(() => deps.dispatchNextQueuedTelegramTurn(ctx), 0);
+        deps.requestDeferredDispatchNextQueuedTelegramTurn(
+          deps.dispatchNextQueuedTelegramTurn,
+        );
       },
       clearPreview: deps.clearPreview,
       setPreviewPendingText: deps.setPreviewPendingText,
@@ -1020,15 +1025,18 @@ export interface TelegramSessionStateApplier<TQueueItem, TModel> {
   applyShutdownState: (state: TelegramSessionShutdownState<TQueueItem>) => void;
 }
 
-export interface TelegramSessionStartRuntimeDeps<TModel = unknown> {
+export interface TelegramSessionStartRuntimeDeps<TContext, TModel = unknown> {
+  ctx: TContext;
   currentModel: TModel | undefined;
   loadConfig: () => Promise<void>;
   applyState: (state: TelegramSessionStartState<TModel>) => void;
+  bindDeferredDispatchContext?: (ctx: TContext) => void;
   prepareTempDir: () => Promise<unknown>;
   updateStatus: () => void;
 }
 
 export interface TelegramSessionShutdownRuntimeDeps<TQueueItem> {
+  unbindDeferredDispatchContext?: () => void;
   applyState: (state: TelegramSessionShutdownState<TQueueItem>) => void;
   clearPendingMediaGroups: () => void;
   clearModelMenuState: () => void;
@@ -1047,8 +1055,10 @@ export interface TelegramSessionLifecycleHookRuntimeDeps<
   getCurrentModel: (ctx: TContext) => TModel | undefined;
   loadConfig: () => Promise<void>;
   applySessionStartState: (state: TelegramSessionStartState<TModel>) => void;
+  bindDeferredDispatchContext?: (ctx: TContext) => void;
   prepareTempDir: () => Promise<unknown>;
   updateStatus: (ctx: TContext) => void;
+  unbindDeferredDispatchContext?: () => void;
   applySessionShutdownState: (
     state: TelegramSessionShutdownState<TQueueItem>,
   ) => void;
@@ -1185,18 +1195,20 @@ export function buildTelegramSessionShutdownState<
   };
 }
 
-export async function startTelegramSessionRuntime<TModel = unknown>(
-  deps: TelegramSessionStartRuntimeDeps<TModel>,
+export async function startTelegramSessionRuntime<TContext, TModel = unknown>(
+  deps: TelegramSessionStartRuntimeDeps<TContext, TModel>,
 ): Promise<void> {
   await deps.loadConfig();
   deps.applyState(buildTelegramSessionStartState(deps.currentModel));
   await deps.prepareTempDir();
+  deps.bindDeferredDispatchContext?.(deps.ctx);
   deps.updateStatus();
 }
 
 export async function shutdownTelegramSessionRuntime<TQueueItem>(
   deps: TelegramSessionShutdownRuntimeDeps<TQueueItem>,
 ): Promise<void> {
+  deps.unbindDeferredDispatchContext?.();
   deps.applyState(buildTelegramSessionShutdownState<TQueueItem>());
   deps.clearPendingMediaGroups();
   deps.clearModelMenuState();
@@ -1235,8 +1247,10 @@ export function createTelegramSessionLifecycleRuntime<
     getCurrentModel: deps.getCurrentModel,
     loadConfig: deps.loadConfig,
     applySessionStartState: stateApplier.applyStartState,
+    bindDeferredDispatchContext: deps.bindDeferredDispatchContext,
     prepareTempDir: deps.prepareTempDir,
     updateStatus: deps.updateStatus,
+    unbindDeferredDispatchContext: deps.unbindDeferredDispatchContext,
     applySessionShutdownState: stateApplier.applyShutdownState,
     clearPendingMediaGroups: deps.clearPendingMediaGroups,
     clearModelMenuState: deps.clearModelMenuState,
@@ -1261,9 +1275,11 @@ export function createTelegramSessionLifecycleHooks<
     ): Promise<void> => {
       try {
         await startTelegramSessionRuntime({
+          ctx,
           currentModel: deps.getCurrentModel(ctx),
           loadConfig: deps.loadConfig,
           applyState: deps.applySessionStartState,
+          bindDeferredDispatchContext: deps.bindDeferredDispatchContext,
           prepareTempDir: deps.prepareTempDir,
           updateStatus: () => deps.updateStatus(ctx),
         });
@@ -1275,6 +1291,7 @@ export function createTelegramSessionLifecycleHooks<
     onSessionShutdown: async (): Promise<void> => {
       try {
         await shutdownTelegramSessionRuntime<TQueueItem>({
+          unbindDeferredDispatchContext: deps.unbindDeferredDispatchContext,
           applyState: deps.applySessionShutdownState,
           clearPendingMediaGroups: deps.clearPendingMediaGroups,
           clearModelMenuState: deps.clearModelMenuState,
@@ -1490,6 +1507,68 @@ export async function executeTelegramControlItemRuntime<TContext>(
   }
 }
 
+// --- Deferred Dispatch Runtime ---
+
+export interface TelegramDeferredQueueDispatchRuntimeDeps extends TelegramRuntimeEventRecorderPort {
+  delayMs?: number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => ReturnType<typeof setTimeout>;
+  clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+
+export interface TelegramDeferredQueueDispatchRuntime<TContext = unknown> {
+  bind: (ctx: TContext) => void;
+  unbind: () => void;
+  isBound: () => boolean;
+  request: (dispatchNextQueuedTelegramTurn: (ctx: TContext) => void) => void;
+}
+
+export function createTelegramDeferredQueueDispatchRuntime<TContext = unknown>(
+  deps: TelegramDeferredQueueDispatchRuntimeDeps = {},
+): TelegramDeferredQueueDispatchRuntime<TContext> {
+  let boundContext: TContext | undefined;
+  let generation = 0;
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  const delayMs = deps.delayMs ?? 0;
+  const setTimer =
+    deps.setTimer ??
+    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> =>
+      setTimeout(callback, ms));
+  const clearTimer =
+    deps.clearTimer ??
+    ((timer: ReturnType<typeof setTimeout>): void => clearTimeout(timer));
+  const clearTimers = (): void => {
+    for (const timer of timers) clearTimer(timer);
+    timers.clear();
+  };
+  return {
+    bind: (ctx) => {
+      boundContext = ctx;
+      generation += 1;
+    },
+    unbind: () => {
+      boundContext = undefined;
+      generation += 1;
+      clearTimers();
+    },
+    isBound: () => boundContext !== undefined,
+    request: (dispatchNextQueuedTelegramTurn) => {
+      if (boundContext === undefined) return;
+      const scheduledGeneration = generation;
+      let timer: ReturnType<typeof setTimeout>;
+      timer = setTimer(() => {
+        timers.delete(timer);
+        if (generation !== scheduledGeneration || boundContext === undefined)
+          return;
+        dispatchNextQueuedTelegramTurn(boundContext);
+      }, delayMs);
+      timers.add(timer);
+    },
+  };
+}
+
 // --- Dispatch Runtime ---
 
 export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
@@ -1516,6 +1595,7 @@ export interface TelegramQueueDispatchControllerDeps<
   getQueuedItems: () => TelegramQueueItem<TContext>[];
   setQueuedItems: (items: TelegramQueueItem<TContext>[]) => void;
   canDispatch: (ctx: TContext) => boolean;
+  hasDispatchContext?: () => boolean;
   updateStatus: (ctx: TContext, error?: string) => void;
   sendTextReply: TelegramControlRuntimeDeps<TContext>["sendTextReply"];
   onPromptDispatchStart: (ctx: TContext, chatId: number) => void;
@@ -1567,6 +1647,7 @@ export function createTelegramQueueDispatchRuntime<TContext = unknown>(
       isIdle: deps.isIdle,
       hasPendingMessages: deps.hasPendingMessages,
     }),
+    hasDispatchContext: deps.hasDispatchContext,
     updateStatus: deps.updateStatus,
     sendTextReply: deps.sendTextReply,
     onPromptDispatchStart: deps.onPromptDispatchStart,
@@ -1582,6 +1663,7 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
   let controlDispatchPending = false;
   const controller: TelegramQueueDispatchController<TContext> = {
     dispatchNext: (ctx) => {
+      if (deps.hasDispatchContext && !deps.hasDispatchContext()) return;
       if (controlDispatchPending) {
         deps.updateStatus(ctx);
         return;
@@ -1603,6 +1685,7 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
             recordRuntimeEvent: deps.recordRuntimeEvent,
             onSettled: () => {
               controlDispatchPending = false;
+              if (deps.hasDispatchContext && !deps.hasDispatchContext()) return;
               deps.updateStatus(ctx);
               controller.dispatchNext(ctx);
             },

package/lib/routing.ts

@@ -41,7 +41,7 @@ export interface TelegramInboundRouteRuntimeDeps<
   >;
   bridgeRuntime: TelegramBridgeRuntime;
   activeTurnRuntime: Queue.TelegramActiveTurnStore;
-  mediaGroupRuntime: Media.TelegramMediaGroupController<TMessage>;
+  mediaGroupRuntime: Media.TelegramMediaGroupController<TMessage, TContext>;
   telegramQueueStore: Queue.TelegramQueueStateStore<TContext>;
   queueMutationRuntime: Queue.TelegramQueueMutationController<TContext>;
   modelMenuRuntime: Menu.TelegramModelMenuRuntime<TModel>;

package/lib/runtime.ts

@@ -353,7 +353,6 @@ export function createTelegramTypingLoopStarter<TContext>(
           deps.recordRuntimeEvent?.("typing", error, {
             chatId: targetChatId,
           });
-          deps.updateStatus(ctx, `typing failed: ${message}`);
         }
       },
     });

package/package.json

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