@llblab/pi-telegram 0.6.2 → 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:
 
@@ -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,6 +49,11 @@ export default function (pi: Pi.ExtensionAPI) {
   const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
     getBotToken: configStore.getBotToken,
   });
+  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
@@ -54,7 +62,7 @@ export default function (pi: Pi.ExtensionAPI) {
     Queue.createTelegramQueueStore<Pi.ExtensionContext>();
   const deferredQueueDispatchRuntime =
     Queue.createTelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>({
-      recordRuntimeEvent: runtimeEvents.record,
+      recordRuntimeEvent,
     });
   const pollingControllerState = Polling.createTelegramPollingControllerState();
   const { getStatusLines, updateStatus } =
@@ -68,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,
@@ -81,16 +89,15 @@ 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 =
@@ -99,7 +106,7 @@ export default function (pi: Pi.ExtensionAPI) {
         getHandlers: configStore.getAttachmentHandlers,
         execCommand: CommandTemplates.execCommandTemplate,
         getCwd: Pi.getExtensionContextCwd,
-        recordRuntimeEvent: runtimeEvents.record,
+        recordRuntimeEvent,
       },
     );
 
@@ -119,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 ---
@@ -152,17 +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,
@@ -182,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,
     });
@@ -201,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,
@@ -215,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
@@ -225,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,
@@ -268,34 +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,
-      bindDeferredDispatchContext: deferredQueueDispatchRuntime.bind,
-      prepareTempDir,
-      updateStatus,
-      unbindDeferredDispatchContext: deferredQueueDispatchRuntime.unbind,
-      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 },
   );
 
@@ -303,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,
@@ -327,68 +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,
-      requestDeferredDispatchNextQueuedTelegramTurn:
-        deferredQueueDispatchRuntime.request,
-      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/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/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/package.json

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