@llblab/pi-telegram 0.6.1 → 0.6.3

package/README.md

@@ -135,11 +135,11 @@ If you ask pi for a file or generated artifact (e.g., _"generate a shell script
 
 ### Assistant-Authored Outbound Actions
 
-Assistant replies can include hidden outbound blocks. `telegram_voice` and `telegram_button` are not pi tools; they are assistant-authored HTML comments that the bridge removes from Telegram text and handles after `agent_end`. Action comments are recognized only as top-level column-zero blocks outside fenced code, quotes, and lists, so documentation examples remain literal. This is faster than agent-side tool calls because the agent only writes correctly formatted Markdown in its normal answer; the extension builds the configured voice pipeline, button markup, and callback routing itself without registering or invoking extra transport/TTS/text-to-OGG tools.
+Assistant replies can include hidden outbound blocks. `telegram_voice` and `telegram_button` are not pi tools; they are assistant-authored HTML comments that the bridge removes from Telegram text and handles after `agent_end`. Recognized blocks must start at column zero on a top-level line outside fenced code, quotes, and lists, so documentation examples remain literal. The agent writes normal Markdown; the extension owns voice generation, button markup, callback routing, and delivery.
 
 #### Voice
 
-Voice blocks synthesize their body and upload it as a native Telegram `sendVoice` OGG/Opus message. The body may be a concise companion summary, but it does not have to follow that format; write the text you want spoken and keep it TTS-friendly:
+Voice blocks synthesize their text and upload it as a native Telegram `sendVoice` OGG/Opus message. Use body form for multiline text, `text="..."` for explicit one-line text with optional attributes, and the colon shorthand for a one-line voice with no attributes. The spoken text may be a concise companion summary, but it does not have to follow that format; write what you want spoken and keep it TTS-friendly:
 
 ```md
 Full technical answer stays readable as text.
@@ -147,6 +147,10 @@ Full technical answer stays readable as text.
 <!-- telegram_voice lang=ru rate=+30%
 Text to synthesize as a Telegram voice message.
 -->
+
+<!-- telegram_voice lang=ru rate=+30% text="Short spoken companion summary." -->
+
+<!-- telegram_voice: Short spoken companion summary. -->
 ```
 
 Outbound voice is disabled unless a matching `outboundHandlers[]` entry is configured. Multiple `telegram_voice` blocks in one reply are synthesized and sent independently, preserving each block's attributes. The bridge uses the same [command-template contract](./docs/command-templates.md) as inbound attachment handlers: split the template into args, substitute placeholders, execute without a shell, and use stdout as the result channel for a single template.
@@ -171,19 +175,21 @@ 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. If the prompt should equal the label, the body can be omitted:
+Button blocks attach inline quick replies to the final text. Use one independent `telegram_button` block per action. If the prompt should equal the label, use the colon shorthand. If the prompt differs, use the inline `prompt="..."` attribute for one-line prompts or the body form for multiline prompts:
 
 ```md
 I can continue.
 
-<!-- telegram_button label="Continue"
-Continue with the current plan.
+<!-- telegram_button label=Continue prompt="Continue with the current plan." -->
+
+<!-- telegram_button label="Show risks"
+List the main risks first.
 -->
 
-<!-- telegram_button label="OK" -->
+<!-- telegram_button: 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).
+Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
 
 ## Streaming
 

package/docs/architecture.md

@@ -23,23 +23,23 @@ Naming rule: because the repository already scopes this codebase to Telegram, ex
 
 Current runtime areas use these ownership boundaries:
 
-| Domain                              | Owns                                                                                                                                                              |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `index.ts`                          | Single composition root for live pi/Telegram ports, session state, API-bound transport adapters, and status updates                                               |
-| `api`                               | Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, runtime error recording       |
-| `config` / `setup`                  | Persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, config persistence                             |
-| `locks` / `polling`                 | Singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, poll-loop runtime wiring                     |
-| `updates` / `routing`               | Update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition                                        |
-| `media` / `turns` / `attachment-handlers` | Text/media extraction, media-group debounce, inbound downloads, turn building/editing, image reads, attachment-handler matching/execution/fallback output    |
-| `queue`                             | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing |
-| `runtime`                           | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding  |
-| `model` / `menu` / `commands`       | Model identity/thinking levels, scoped model resolution, in-flight switching, inline status/model/thinking UI, slash commands, bot command registration           |
-| `preview` / `replies` / `rendering` | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots                     |
-| `outbound-handlers`                 | Assistant-authored outbound comments, generated reply artifacts, inline-keyboard callbacks, and post-`agent_end` outbound action delivery                         |
-| `attachments`                       | `telegram_attach` registration, outbound attachment queueing, stat/limit checks, photo/document delivery classification                                           |
-| `status`                            | Status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, grouped pi diagnostics                                                 |
-| `lifecycle` / `prompts` / `pi`      | pi hook registration, Telegram-specific before-agent prompt injection, centralized direct pi SDK imports and context adapters                                     |
-| `command-templates`                 | Portable shell-free command-template standard helpers, composition expansion, placeholder substitution, and executable resolution                                  |
+| Domain                                    | Owns                                                                                                                                                              |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.ts`                                | Single composition root for live pi/Telegram ports, session state, API-bound transport adapters, and status updates                                               |
+| `api`                                     | Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, runtime error recording       |
+| `config` / `setup`                        | Persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, config persistence                             |
+| `locks` / `polling`                       | Singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, poll-loop runtime wiring                     |
+| `updates` / `routing`                     | Update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition                                        |
+| `media` / `turns` / `attachment-handlers` | Text/media extraction, media-group debounce, inbound downloads, turn building/editing, image reads, attachment-handler matching/execution/fallback output         |
+| `queue`                                   | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing |
+| `runtime`                                 | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding  |
+| `model` / `menu` / `commands`             | Model identity/thinking levels, scoped model resolution, in-flight switching, inline status/model/thinking UI, slash commands, bot command registration           |
+| `preview` / `replies` / `rendering`       | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots                     |
+| `outbound-handlers`                       | Assistant-authored outbound comments, generated reply artifacts, inline-keyboard callbacks, and post-`agent_end` outbound action delivery                         |
+| `attachments`                             | `telegram_attach` registration, outbound attachment queueing, stat/limit checks, photo/document delivery classification                                           |
+| `status`                                  | Status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, grouped pi diagnostics                                                 |
+| `lifecycle` / `prompts` / `pi`            | pi hook registration, Telegram-specific before-agent prompt injection, centralized direct pi SDK imports and context adapters                                     |
+| `command-templates`                       | Portable shell-free command-template standard helpers, composition expansion, placeholder substitution, and executable resolution                                 |
 
 Boundary invariants:
 
@@ -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, 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.
+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 body text, `text="..."`, or colon shorthand 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; the `telegram_button: Label` shorthand uses the same text for label and prompt, `prompt="..."` supports explicit one-line prompts, and body-form buttons use the body as the prompt. 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/outbound-handlers.md

@@ -49,9 +49,13 @@ Full text answer stays here.
 <!-- telegram_voice lang=ru rate=+30%
 Text to synthesize as a Telegram voice message.
 -->
+
+<!-- telegram_voice lang=ru rate=+30% text="Short spoken companion summary." -->
+
+<!-- telegram_voice: Short spoken companion summary. -->
 ```
 
-The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` block to `type: "voice"`, generates one file per block, and sends each file as an independent Telegram-native voice message. The opening `<!-- telegram_voice` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown.
+The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` block to `type: "voice"`, generates one file per block, and sends each file as an independent Telegram-native voice message. The opening `<!-- telegram_voice` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown. Body-form comments leave the opening line unclosed until the body-ending `-->`; closed heads can use `text="..."` for explicit one-line spoken text.
 
 ## Built-In Voice Placeholders
 
@@ -59,7 +63,7 @@ Voice outbound handlers receive these runtime placeholders:
 
 | Placeholder | Value                                                    |
 | ----------- | -------------------------------------------------------- |
-| `{text}`    | Voice block body                                         |
+| `{text}`    | Voice text from body, `text="..."`, or colon shorthand |
 | `{lang}`    | Optional markup override such as `lang=ru`               |
 | `{rate}`    | Optional markup override such as `rate=+30%`             |
 | `{mp3}`     | Flat temp artifact path under `~/.pi/agent/tmp/telegram` |
@@ -75,26 +79,27 @@ 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; omit the body when the prompt should equal the label:
+Assistant replies can include independent button blocks. The prompt is sent back to pi when the user taps the button; use the colon shorthand when the prompt should equal the label, `prompt="..."` for one-line prompts, or the body form for multiline prompts:
 
 ```md
 I can continue.
 
-<!-- telegram_button label="OK"
-Continue with the current plan.
--->
+<!-- telegram_button label=Continue prompt="Continue with the current plan." -->
 
 <!-- telegram_button label="Show risks"
 List the main risks first.
 -->
 
-<!-- telegram_button label="Done" -->
+<!-- telegram_button: Done -->
 ```
 
 Rules:
 
-- `telegram_button label="Label"` creates one independent button row whose prompt is the block body, or the label itself when the body is omitted.
+- `telegram_button: Label` creates one independent label-only button row whose prompt equals the label.
+- `telegram_button label="Label" prompt="Prompt"` creates one independent button row whose prompt is the `prompt` attribute.
+- `telegram_button label="Label"` with a body creates one independent button row whose prompt is the block body.
 - 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.
+- Keep the canonical body form as `<!-- telegram_button label="Label"` + body + `-->`; closed heads must use `prompt="..."` or the colon shorthand to create a button.
 - 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.
 
@@ -105,8 +110,8 @@ Buttons are built in and do not need a command template because they are pure Te
 The extension injects Telegram-specific system prompt guidance so agents know the fast path:
 
 - Write the full technical answer as normal Markdown.
-- Add `telegram_voice` when a Telegram-native voice message is useful; the block body is the text to synthesize and may be a companion summary, but no specific summary format is required.
-- Add `telegram_button label="..."` for quick replies that should come back as normal Telegram prompts.
+- Add `telegram_voice` when a Telegram-native voice message is useful; use body text, `text="..."`, or colon shorthand for the text to synthesize. A companion summary is optional, no specific summary format is required.
+- Add `telegram_button: ...` when label equals prompt, `telegram_button label="..." prompt="..."` for one-line prompts, or `telegram_button label="..."` with a body for multiline prompts. If the reply contains only button/voice comment blocks, add a short visible marker (for example `Choose one:`) before them so Telegram always has a visible parent message for attachment.
 - Do not call or register TTS/text-to-OGG/Telegram transport tools for voice or buttons; the bridge owns the configured outbound-handler pipeline and delivery.
 
 This keeps the agent focused on semantics and lets the bridge handle low-latency Telegram adaptation.

package/index.ts

@@ -33,7 +33,10 @@ type RuntimeTelegramQueueItem = Queue.TelegramQueueItem<Pi.ExtensionContext>;
 
 export default function (pi: Pi.ExtensionAPI) {
   const piRuntime = Pi.createExtensionApiRuntimePorts(pi);
+  const { getThinkingLevel, sendUserMessage, setModel, setThinkingLevel } =
+    piRuntime;
   const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
+  const { abort, lifecycle, queue, setup, typing } = bridgeRuntime;
   const configStore = Config.createTelegramConfigStore();
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const activeTurnRuntime = Queue.createTelegramActiveTurnStore();
@@ -46,10 +49,21 @@ export default function (pi: Pi.ExtensionAPI) {
   const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
     getBotToken: configStore.getBotToken,
   });
-  const mediaGroupRuntime =
-    Media.createTelegramMediaGroupController<Api.TelegramMessage>();
+  const recordRuntimeEvent = runtimeEvents.record;
+  const getContextModel = Pi.getExtensionContextModel;
+  const isIdle = Pi.isExtensionContextIdle;
+  const hasPendingMessages = Pi.hasExtensionContextPendingMessages;
+  const compact = Pi.compactExtensionContext;
+  const mediaGroupRuntime = Media.createTelegramMediaGroupController<
+    Api.TelegramMessage,
+    Pi.ExtensionContext
+  >();
   const telegramQueueStore =
     Queue.createTelegramQueueStore<Pi.ExtensionContext>();
+  const deferredQueueDispatchRuntime =
+    Queue.createTelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>({
+      recordRuntimeEvent,
+    });
   const pollingControllerState = Polling.createTelegramPollingControllerState();
   const { getStatusLines, updateStatus } =
     Status.createTelegramBridgeStatusRuntime<
@@ -62,9 +76,9 @@ export default function (pi: Pi.ExtensionAPI) {
       ),
       getActiveSourceMessageIds: activeTurnRuntime.getSourceMessageIds,
       hasActiveTurn: activeTurnRuntime.has,
-      hasDispatchPending: bridgeRuntime.lifecycle.hasDispatchPending,
-      isCompactionInProgress: bridgeRuntime.lifecycle.isCompactionInProgress,
-      getActiveToolExecutions: bridgeRuntime.lifecycle.getActiveToolExecutions,
+      hasDispatchPending: lifecycle.hasDispatchPending,
+      isCompactionInProgress: lifecycle.isCompactionInProgress,
+      getActiveToolExecutions: lifecycle.getActiveToolExecutions,
       hasPendingModelSwitch: pendingModelSwitchStore.has,
       getQueuedItems: telegramQueueStore.getQueuedItems,
       formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
@@ -75,25 +89,26 @@ export default function (pi: Pi.ExtensionAPI) {
     Pi.ExtensionContext,
     ActivePiModel
   >({
-    getContextModel: Pi.getExtensionContextModel,
+    getContextModel,
     updateStatus,
   });
   const queueMutationRuntime =
     Queue.createTelegramQueueMutationController<Pi.ExtensionContext>({
       ...telegramQueueStore,
-      getNextPriorityReactionOrder:
-        bridgeRuntime.queue.getNextPriorityReactionOrder,
+      getNextPriorityReactionOrder: queue.getNextPriorityReactionOrder,
       incrementNextPriorityReactionOrder:
-        bridgeRuntime.queue.incrementNextPriorityReactionOrder,
+        queue.incrementNextPriorityReactionOrder,
       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,
+      },
+    );
 
   // --- Telegram API ---
 
@@ -111,19 +126,19 @@ export default function (pi: Pi.ExtensionAPI) {
     prepareTempDir,
   } = Api.createDefaultTelegramBridgeApiRuntime({
     getBotToken: configStore.getBotToken,
-    recordRuntimeEvent: runtimeEvents.record,
+    recordRuntimeEvent,
   });
 
   // --- Message Delivery & Preview ---
 
   const promptDispatchRuntime =
     Runtime.createTelegramPromptDispatchRuntime<Pi.ExtensionContext>({
-      lifecycle: bridgeRuntime.lifecycle,
-      typing: bridgeRuntime.typing,
+      lifecycle,
+      typing,
       getDefaultChatId: activeTurnRuntime.getChatId,
       sendTypingAction,
       updateStatus,
-      recordRuntimeEvent: runtimeEvents.record,
+      recordRuntimeEvent,
     });
 
   // --- Reply Runtime Wiring ---
@@ -144,16 +159,17 @@ export default function (pi: Pi.ExtensionAPI) {
   const dispatchNextQueuedTelegramTurn =
     Queue.createTelegramQueueDispatchRuntime<Pi.ExtensionContext>({
       ...telegramQueueStore,
-      isCompactionInProgress: bridgeRuntime.lifecycle.isCompactionInProgress,
+      isCompactionInProgress: lifecycle.isCompactionInProgress,
       hasActiveTurn: activeTurnRuntime.has,
-      hasDispatchPending: bridgeRuntime.lifecycle.hasDispatchPending,
-      isIdle: Pi.isExtensionContextIdle,
-      hasPendingMessages: Pi.hasExtensionContextPendingMessages,
+      hasDispatchPending: lifecycle.hasDispatchPending,
+      isIdle,
+      hasPendingMessages,
+      hasDispatchContext: deferredQueueDispatchRuntime.isBound,
       updateStatus,
       sendTextReply,
-      recordRuntimeEvent: runtimeEvents.record,
+      recordRuntimeEvent,
       ...promptDispatchRuntime,
-      sendUserMessage: piRuntime.sendUserMessage,
+      sendUserMessage,
     }).dispatchNext;
   const previewRuntime = Preview.createTelegramAssistantPreviewRuntime({
     getActiveTurn: activeTurnRuntime.get,
@@ -173,15 +189,15 @@ export default function (pi: Pi.ExtensionAPI) {
       Pi.ExtensionContext,
       Model.ScopedTelegramModel<ActivePiModel>
     >({
-      isIdle: Pi.isExtensionContextIdle,
+      isIdle,
       getPendingModelSwitch: pendingModelSwitchStore.get,
       setPendingModelSwitch: pendingModelSwitchStore.set,
       getActiveTurn: activeTurnRuntime.get,
-      getAbortHandler: bridgeRuntime.abort.getHandler,
-      hasAbortHandler: bridgeRuntime.abort.hasHandler,
-      getActiveToolExecutions: bridgeRuntime.lifecycle.getActiveToolExecutions,
-      allocateItemOrder: bridgeRuntime.queue.allocateItemOrder,
-      allocateControlOrder: bridgeRuntime.queue.allocateControlOrder,
+      getAbortHandler: abort.getHandler,
+      hasAbortHandler: abort.hasHandler,
+      getActiveToolExecutions: lifecycle.getActiveToolExecutions,
+      allocateItemOrder: queue.allocateItemOrder,
+      allocateControlOrder: queue.allocateControlOrder,
       appendQueuedItem: queueMutationRuntime.append,
       updateStatus,
     });
@@ -192,12 +208,12 @@ export default function (pi: Pi.ExtensionAPI) {
     runtime: modelMenuRuntime,
     createSettingsManager: Pi.createSettingsManager,
     getActiveModel: currentModelRuntime.get,
-    getThinkingLevel: piRuntime.getThinkingLevel,
+    getThinkingLevel,
     buildStatusHtml: Status.createTelegramStatusHtmlBuilder({
       getActiveModel: currentModelRuntime.get,
     }),
     storeModelMenuState: modelMenuRuntime.storeState,
-    isIdle: Pi.isExtensionContextIdle,
+    isIdle,
     canOfferInFlightModelSwitch: modelSwitchController.canOfferInFlightSwitch,
     sendTextReply,
     editInteractiveMessage,
@@ -206,6 +222,39 @@ export default function (pi: Pi.ExtensionAPI) {
 
   // --- Polling ---
 
+  const inboundRouteRuntime = Routing.createTelegramInboundRouteRuntime<
+    Api.TelegramUpdate,
+    Api.TelegramMessage,
+    Api.TelegramCallbackQuery,
+    Pi.ExtensionContext,
+    ActivePiModel
+  >({
+    configStore,
+    bridgeRuntime,
+    activeTurnRuntime,
+    mediaGroupRuntime,
+    telegramQueueStore,
+    queueMutationRuntime,
+    modelMenuRuntime,
+    currentModelRuntime,
+    modelSwitchController,
+    menuActions,
+    buttonActionStore,
+    attachmentHandlerRuntime,
+    updateStatus,
+    dispatchNextQueuedTelegramTurn,
+    answerCallbackQuery,
+    sendTextReply,
+    setMyCommands,
+    downloadFile: downloadTelegramBridgeFile,
+    getThinkingLevel,
+    setThinkingLevel,
+    setModel,
+    isIdle,
+    hasPendingMessages,
+    compact,
+    recordRuntimeEvent,
+  });
   const pollingRuntime = Polling.createTelegramPollingControllerRuntime<
     Api.TelegramUpdate,
     Pi.ExtensionContext
@@ -216,42 +265,10 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: configStore.persist,
-    handleUpdate: Routing.createTelegramInboundRouteRuntime<
-      Api.TelegramUpdate,
-      Api.TelegramMessage,
-      Api.TelegramCallbackQuery,
-      Pi.ExtensionContext,
-      ActivePiModel
-    >({
-      configStore,
-      bridgeRuntime,
-      activeTurnRuntime,
-      mediaGroupRuntime,
-      telegramQueueStore,
-      queueMutationRuntime,
-      modelMenuRuntime,
-      currentModelRuntime,
-      modelSwitchController,
-      menuActions,
-      buttonActionStore,
-      attachmentHandlerRuntime,
-      updateStatus,
-      dispatchNextQueuedTelegramTurn,
-      answerCallbackQuery,
-      sendTextReply,
-      setMyCommands,
-      downloadFile: downloadTelegramBridgeFile,
-      getThinkingLevel: piRuntime.getThinkingLevel,
-      setThinkingLevel: piRuntime.setThinkingLevel,
-      setModel: piRuntime.setModel,
-      isIdle: Pi.isExtensionContextIdle,
-      hasPendingMessages: Pi.hasExtensionContextPendingMessages,
-      compact: Pi.compactExtensionContext,
-      recordRuntimeEvent: runtimeEvents.record,
-    }).handleUpdate,
-    stopTypingLoop: bridgeRuntime.typing.stop,
+    handleUpdate: inboundRouteRuntime.handleUpdate,
+    stopTypingLoop: typing.stop,
     updateStatus,
-    recordRuntimeEvent: runtimeEvents.record,
+    recordRuntimeEvent,
   });
   const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
     lock: lockRuntime,
@@ -259,32 +276,35 @@ export default function (pi: Pi.ExtensionAPI) {
     startPolling: pollingRuntime.start,
     stopPolling: pollingRuntime.stop,
     updateStatus,
-    recordRuntimeEvent: runtimeEvents.record,
+    recordRuntimeEvent,
+  });
+  const queueSessionLifecycle = Queue.createTelegramSessionLifecycleRuntime<
+    Pi.ExtensionContext,
+    RuntimeTelegramQueueItem,
+    ActivePiModel
+  >({
+    getCurrentModel: getContextModel,
+    loadConfig: configStore.load,
+    setQueuedItems: telegramQueueStore.setQueuedItems,
+    setCurrentModel: currentModelRuntime.set,
+    setPendingModelSwitch: pendingModelSwitchStore.set,
+    syncCounters: queue.syncCounters,
+    syncFlags: lifecycle.syncFlags,
+    bindDeferredDispatchContext: deferredQueueDispatchRuntime.bind,
+    prepareTempDir,
+    updateStatus,
+    unbindDeferredDispatchContext: deferredQueueDispatchRuntime.unbind,
+    clearPendingMediaGroups: mediaGroupRuntime.clear,
+    clearModelMenuState: modelMenuRuntime.clear,
+    getActiveTurnChatId: activeTurnRuntime.getChatId,
+    clearPreview: previewRuntime.clear,
+    clearActiveTurn: activeTurnRuntime.clear,
+    clearAbort: abort.clearHandler,
+    stopPolling: lockedPollingRuntime.suspend,
+    recordRuntimeEvent,
   });
   const sessionLifecycleRuntime = Lifecycle.appendTelegramLifecycleHooks(
-    Queue.createTelegramSessionLifecycleRuntime<
-      Pi.ExtensionContext,
-      RuntimeTelegramQueueItem,
-      ActivePiModel
-    >({
-      getCurrentModel: Pi.getExtensionContextModel,
-      loadConfig: configStore.load,
-      setQueuedItems: telegramQueueStore.setQueuedItems,
-      setCurrentModel: currentModelRuntime.set,
-      setPendingModelSwitch: pendingModelSwitchStore.set,
-      syncCounters: bridgeRuntime.queue.syncCounters,
-      syncFlags: bridgeRuntime.lifecycle.syncFlags,
-      prepareTempDir,
-      updateStatus,
-      clearPendingMediaGroups: mediaGroupRuntime.clear,
-      clearModelMenuState: modelMenuRuntime.clear,
-      getActiveTurnChatId: activeTurnRuntime.getChatId,
-      clearPreview: previewRuntime.clear,
-      clearActiveTurn: activeTurnRuntime.clear,
-      clearAbort: bridgeRuntime.abort.clearHandler,
-      stopPolling: lockedPollingRuntime.suspend,
-      recordRuntimeEvent: runtimeEvents.record,
-    }),
+    queueSessionLifecycle,
     { onSessionStart: lockedPollingRuntime.onSessionStart },
   );
 
@@ -292,19 +312,19 @@ export default function (pi: Pi.ExtensionAPI) {
 
   Attachments.registerTelegramAttachmentTool(pi, {
     getActiveTurn: activeTurnRuntime.get,
-    recordRuntimeEvent: runtimeEvents.record,
+    recordRuntimeEvent,
   });
 
   Commands.registerTelegramBridgeCommands(pi, {
     promptForConfig: Setup.createTelegramSetupPromptRuntime({
       getConfig: configStore.get,
       setConfig: configStore.set,
-      setupGuard: bridgeRuntime.setup,
+      setupGuard: setup,
       getMe: Api.fetchTelegramBotIdentity,
       persistConfig: configStore.persist,
       startPolling: lockedPollingRuntime.start,
       updateStatus,
-      recordRuntimeEvent: runtimeEvents.record,
+      recordRuntimeEvent,
     }),
     getStatusLines,
     reloadConfig: configStore.load,
@@ -316,66 +336,71 @@ export default function (pi: Pi.ExtensionAPI) {
 
   // --- Lifecycle Hooks ---
 
+  const agentEndResetter = Runtime.createTelegramAgentEndResetter({
+    abort,
+    typing,
+    clearActiveTurn: activeTurnRuntime.clear,
+    resetToolExecutions: lifecycle.resetActiveToolExecutions,
+    clearPendingModelSwitch: modelSwitchController.clearPendingSwitch,
+    clearDispatchPending: lifecycle.clearDispatchPending,
+  });
+  const queuedAttachmentSender =
+    Attachments.createTelegramQueuedAttachmentSender({
+      sendMultipart: callMultipart,
+      sendTextReply,
+      recordRuntimeEvent,
+    });
+  const outboundReplyPlanner =
+    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
+  const outboundReplyArtifactSender =
+    OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+      execCommand: CommandTemplates.execCommandTemplate,
+      sendMultipart: callMultipart,
+      sendTextReply,
+      getHandlers: configStore.getOutboundHandlers,
+      recordRuntimeEvent,
+    });
+  const agentLifecycleHooks = Queue.createTelegramAgentLifecycleHooks<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    unknown
+  >({
+    setAbortHandler: Runtime.createTelegramContextAbortHandlerSetter(abort),
+    getQueuedItems: telegramQueueStore.getQueuedItems,
+    hasPendingDispatch: lifecycle.hasDispatchPending,
+    hasActiveTurn: activeTurnRuntime.has,
+    resetToolExecutions: lifecycle.resetActiveToolExecutions,
+    resetPendingModelSwitch: modelSwitchController.clearPendingSwitch,
+    setQueuedItems: telegramQueueStore.setQueuedItems,
+    clearDispatchPending: lifecycle.clearDispatchPending,
+    setActiveTurn: activeTurnRuntime.set,
+    createPreviewState: previewRuntime.resetState,
+    startTypingLoop: promptDispatchRuntime.startTypingLoop,
+    updateStatus,
+    getActiveTurn: activeTurnRuntime.get,
+    extractAssistant: Replies.extractLatestAssistantMessageText,
+    getPreserveQueuedTurnsAsHistory: lifecycle.shouldPreserveQueuedTurnsAsHistory,
+    resetRuntimeState: agentEndResetter,
+    dispatchNextQueuedTelegramTurn,
+    requestDeferredDispatchNextQueuedTelegramTurn:
+      deferredQueueDispatchRuntime.request,
+    clearPreview: previewRuntime.clear,
+    setPreviewPendingText: previewRuntime.setPendingText,
+    finalizeMarkdownPreview: previewRuntime.finalizeMarkdown,
+    sendMarkdownReply,
+    sendTextReply,
+    sendQueuedAttachments: queuedAttachmentSender,
+    planOutboundReply: outboundReplyPlanner,
+    sendOutboundReplyArtifacts: outboundReplyArtifactSender,
+    getActiveToolExecutions: lifecycle.getActiveToolExecutions,
+    setActiveToolExecutions: lifecycle.setActiveToolExecutions,
+    triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,
+  });
   Lifecycle.registerTelegramLifecycleHooks(pi, {
     ...sessionLifecycleRuntime,
+    ...agentLifecycleHooks,
     onBeforeAgentStart: Prompts.createTelegramBeforeAgentStartHook(),
     onModelSelect: currentModelRuntime.onModelSelect,
-    ...Queue.createTelegramAgentLifecycleHooks<
-      Queue.PendingTelegramTurn,
-      Pi.ExtensionContext,
-      unknown
-    >({
-      setAbortHandler: Runtime.createTelegramContextAbortHandlerSetter(
-        bridgeRuntime.abort,
-      ),
-      getQueuedItems: telegramQueueStore.getQueuedItems,
-      hasPendingDispatch: bridgeRuntime.lifecycle.hasDispatchPending,
-      hasActiveTurn: activeTurnRuntime.has,
-      resetToolExecutions: bridgeRuntime.lifecycle.resetActiveToolExecutions,
-      resetPendingModelSwitch: modelSwitchController.clearPendingSwitch,
-      setQueuedItems: telegramQueueStore.setQueuedItems,
-      clearDispatchPending: bridgeRuntime.lifecycle.clearDispatchPending,
-      setActiveTurn: activeTurnRuntime.set,
-      createPreviewState: previewRuntime.resetState,
-      startTypingLoop: promptDispatchRuntime.startTypingLoop,
-      updateStatus,
-      getActiveTurn: activeTurnRuntime.get,
-      extractAssistant: Replies.extractLatestAssistantMessageText,
-      getPreserveQueuedTurnsAsHistory:
-        bridgeRuntime.lifecycle.shouldPreserveQueuedTurnsAsHistory,
-      resetRuntimeState: Runtime.createTelegramAgentEndResetter({
-        abort: bridgeRuntime.abort,
-        typing: bridgeRuntime.typing,
-        clearActiveTurn: activeTurnRuntime.clear,
-        resetToolExecutions: bridgeRuntime.lifecycle.resetActiveToolExecutions,
-        clearPendingModelSwitch: modelSwitchController.clearPendingSwitch,
-        clearDispatchPending: bridgeRuntime.lifecycle.clearDispatchPending,
-      }),
-      dispatchNextQueuedTelegramTurn,
-      clearPreview: previewRuntime.clear,
-      setPreviewPendingText: previewRuntime.setPendingText,
-      finalizeMarkdownPreview: previewRuntime.finalizeMarkdown,
-      sendMarkdownReply,
-      sendTextReply,
-      sendQueuedAttachments: Attachments.createTelegramQueuedAttachmentSender({
-        sendMultipart: callMultipart,
-        sendTextReply,
-        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,
-    }),
     onMessageStart: previewRuntime.onMessageStart,
     onMessageUpdate: previewRuntime.onMessageUpdate,
   });

package/lib/config.ts

@@ -3,6 +3,7 @@
  * Owns persisted bot/session pairing state, local config storage, authorization policy, and first-user pairing side effects
  */
 
+import { existsSync } from "node:fs";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -64,12 +65,9 @@ export interface TelegramConfigStoreOptions {
 export async function readTelegramConfig(
   configPath: string,
 ): Promise<TelegramConfig> {
-  try {
-    const content = await readFile(configPath, "utf8");
-    return JSON.parse(content) as TelegramConfig;
-  } catch {
-    return {};
-  }
+  if (!existsSync(configPath)) return {};
+  const content = await readFile(configPath, "utf8");
+  return JSON.parse(content) as TelegramConfig;
 }
 
 export async function writeTelegramConfig(

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

@@ -106,6 +106,16 @@ interface TelegramTopLevelFenceState {
   length: number;
 }
 
+function isTelegramActionCommentContent(content: string): boolean {
+  const normalizedContent = content.replace(/^\s+/, "");
+  const [head = ""] = normalizedContent.split(/\r?\n/, 1);
+  return ["telegram_voice", "telegram_button"].some((command) => {
+    if (!head.startsWith(command)) return false;
+    const nextChar = head[command.length];
+    return nextChar === undefined || /\s|:/.test(nextChar);
+  });
+}
+
 function getMarkdownLineEnd(markdown: string, offset: number): number {
   const newlineIndex = markdown.indexOf("\n", offset);
   return newlineIndex === -1 ? markdown.length : newlineIndex + 1;
@@ -144,6 +154,28 @@ function isTopLevelClosingFence(
   );
 }
 
+function collectInlineClosedTelegramActionBody(
+  markdown: string,
+  bodyStart: number,
+  commentContent: string,
+): { content: string; end: number } | undefined {
+  const bodyLineEnd = getMarkdownLineEnd(markdown, bodyStart);
+  const bodyLine = getMarkdownLineText(markdown, bodyStart, bodyLineEnd);
+  const closeLineEnd = getMarkdownLineEnd(markdown, bodyLineEnd);
+  const closeLine = getMarkdownLineText(markdown, bodyLineEnd, closeLineEnd);
+  const hasRecoverableBody =
+    isTelegramActionCommentContent(commentContent) &&
+    bodyLine.trim() !== "" &&
+    !bodyLine.startsWith("<!--") &&
+    !bodyLine.startsWith("-->") &&
+    closeLine === "-->";
+  if (!hasRecoverableBody) return undefined;
+  return {
+    content: `${commentContent.trimEnd()}\n${bodyLine}`,
+    end: bodyLineEnd + 3,
+  };
+}
+
 function collectTopLevelHtmlComments(markdown: string): {
   comments: TelegramTopLevelHtmlComment[];
   openCommentStart?: number;
@@ -168,9 +200,23 @@ function collectTopLevelHtmlComments(markdown: string): {
     if (line.startsWith("<!--")) {
       const closeIndex = markdown.indexOf("-->", offset + 4);
       if (closeIndex === -1) return { comments, openCommentStart: offset };
-      const end = closeIndex + 3;
-      const raw = markdown.slice(offset, end);
-      comments.push({ raw, content: raw.slice(4, -3), start: offset, end });
+      let end = closeIndex + 3;
+      let raw = markdown.slice(offset, end);
+      let content = raw.slice(4, -3);
+      const closeColumn = closeIndex - offset;
+      const closesOnOpeningLine = closeIndex < lineEnd;
+      const hasOnlyWhitespaceAfterClose =
+        line.slice(closeColumn + 3).trim() === "";
+      const inlineBody =
+        closesOnOpeningLine && hasOnlyWhitespaceAfterClose
+          ? collectInlineClosedTelegramActionBody(markdown, lineEnd, content)
+          : undefined;
+      if (inlineBody) {
+        end = inlineBody.end;
+        raw = markdown.slice(offset, end);
+        content = inlineBody.content;
+      }
+      comments.push({ raw, content, start: offset, end });
       offset = getMarkdownLineEnd(markdown, end);
       continue;
     }
@@ -239,18 +285,29 @@ function parseTopLevelTelegramComment(
   };
 }
 
+function parseTelegramCommentAttributes(input: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  for (const match of input.matchAll(
+    /([A-Za-z_][A-Za-z0-9_-]*)=(?:"([^"]*)"|'([^']*)'|(\S+))/g,
+  )) {
+    const key = match[1];
+    const value = (match[2] ?? match[3] ?? match[4] ?? "").trim();
+    if (value) attributes[key] = value;
+  }
+  return attributes;
+}
+
 function parseVoiceReplyAttributes(input: string): {
   lang?: string;
   rate?: string;
+  text?: string;
 } {
-  const attributes: { lang?: string; rate?: string } = {};
-  for (const token of input.trim().split(/\s+/).filter(Boolean)) {
-    const [rawKey, ...valueParts] = token.split("=");
-    const value = valueParts.join("=").trim();
-    if (rawKey === "lang" && value) attributes.lang = value;
-    if (rawKey === "rate" && value) attributes.rate = value;
-  }
-  return attributes;
+  const attributes = parseTelegramCommentAttributes(input);
+  return {
+    ...(attributes.lang ? { lang: attributes.lang } : {}),
+    ...(attributes.rate ? { rate: attributes.rate } : {}),
+    ...(attributes.text ? { text: attributes.text } : {}),
+  };
 }
 
 function parseVoiceCommentBody(
@@ -267,7 +324,8 @@ function parseVoiceCommentBody(
   if (trimmedHead.startsWith(":")) {
     return { attrs: "", text: trimmedHead.slice(1).trim() };
   }
-  return { attrs: trimmedHead, text: "" };
+  const attrs = parseVoiceReplyAttributes(trimmedHead);
+  return { attrs: trimmedHead, text: attrs.text ?? "" };
 }
 
 function normalizeMarkdownAfterVoiceExtraction(markdown: string): string {
@@ -712,26 +770,36 @@ function normalizeMarkdownAfterButtonExtraction(markdown: string): string {
   return markdown.replace(/\n{3,}/g, "\n\n").trim();
 }
 
-function parseButtonsCommentAttributes(input: string): { label?: string } {
-  const attributes: { label?: string } = {};
-  for (const match of input.matchAll(
-    /([A-Za-z_][A-Za-z0-9_-]*)=(?:"([^"]*)"|'([^']*)'|(\S+))/g,
-  )) {
-    const key = match[1];
-    const value = match[2] ?? match[3] ?? match[4] ?? "";
-    if (key === "label" && value.trim()) attributes.label = value.trim();
-  }
-  return attributes;
+function parseButtonsCommentAttributes(input: string): {
+  label?: string;
+  prompt?: string;
+} {
+  const attributes = parseTelegramCommentAttributes(input);
+  return {
+    ...(attributes.label ? { label: attributes.label } : {}),
+    ...(attributes.prompt ? { prompt: attributes.prompt } : {}),
+  };
 }
 
 function parseButtonsCommentRows(
   head: string,
   body: string | undefined,
 ): TelegramOutboundButtonAction[][] {
-  const attributes = parseButtonsCommentAttributes(head);
-  if (!attributes.label) return [];
-  const prompt = body?.trim() || attributes.label;
-  return [[{ text: attributes.label, prompt }]];
+  const trimmedHead = head.trim();
+  if (body === undefined) {
+    if (trimmedHead.startsWith(":")) {
+      const label = trimmedHead.slice(1).trim();
+      return label ? [[{ text: label, prompt: label }]] : [];
+    }
+    const attributes = parseButtonsCommentAttributes(head);
+    return attributes.label && attributes.prompt
+      ? [[{ text: attributes.label, prompt: attributes.prompt }]]
+      : [];
+  }
+  const label = parseButtonsCommentAttributes(head).label;
+  const prompt = body.trim();
+  if (!label || !prompt) return [];
+  return [[{ text: label, prompt }]];
 }
 
 export function createTelegramButtonActionStore(

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

@@ -9,15 +9,22 @@ import { TELEGRAM_PREFIX } from "./turns.ts";
 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.
-- 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.`;
+
+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.
+- \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains attachment-handler stdout such as transcriptions or extracted text for those attachments.
+
+Telegram-visible output:
+- Telegram is often phone-width; prefer narrow table columns because wide monospace tables can become unreadable.
+- For requested/generated files, call tool \`telegram_attach(local_path)\`; mentioning a local path in text does not send it.
+
+Native outbound actions:
+- Use top-level column-zero hidden Markdown comments outside code, quotes, and lists; the bridge handles them after agent_end, so do not call or register transport/TTS/text-to-OGG tools.
+- \`telegram_voice\`: text is synthesized through the configured outbound-handler pipeline. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line voice, or \`<!-- telegram_voice: Short summary -->\` for one-line voice with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
+- \`telegram_button\`: callback prompt is routed back as a normal Telegram turn. Use \`<!-- telegram_button: OK -->\` when prompt equals label, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\` for one-line prompts, or body form \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\` for multiline prompts.
+- If only hidden action comments would remain, add visible parent text like "Choose one:".
+`;
 
 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.1",
+  "version": "0.6.3",
   "private": false,
   "description": "Better Telegram DM bridge extension for pi",
   "type": "module",