@llblab/pi-kit 0.37.0 → 0.37.1

package/node_modules/@llblab/pi-telegram/docs/architecture.md

@@ -106,7 +106,7 @@ Only the live cleanup origin uses the approved historical-protection reduction.
 - `preview` / `replies` / `rendering`: throttled native Rich Markdown draft delivery, native final reply delivery, reply parameters, transport-limit chunking, and remaining Telegram HTML rendering (bold, italic, strikethrough, spoilers, code, links) for bridge-owned UI/compatibility surfaces.
 - `delivery`: public extension operational-view delivery, active-turn/instance/aggregate/authorized target policy, logical chunk handles, per-target ordering, runtime generation fencing, and the process-local runtime membrane. Its bridge adapter composes the established UI/compat reply renderer with narrow bus-aware Telegram API and ownership ports; it never exposes bot clients or Pi contexts.
 - `activity`: public normalized Pi lifecycle registration, activity/source identity, assistant segment and reasoning normalization, executed-tool events, non-blocking per-handler queues, delivery contexts, compatibility adapters, and shutdown fencing. Internal publication/command-work and handler drain notifications share the lifecycle-owned captured-session/transport observer with companion queues and API target counters; bindings/root wire those neutral ports into routing's existing leader cleanup scheduler, never into deletion authority. Routing retains busy/unproven-idle delivery hints without early admission, preserves ordinary timers, and lets semantic settlement or post-settlement output drain request fresh checks. The same domain extends assistant-output observation for connected companion projection: eligible completed local/autonomous public segments retain source order and deduplicate event identity. `bindings` assembles observation, authority, sender, and failure-projection ports; routing owns exact delivery authority, outbound composes established transformations and reply delivery, and Bot API domains implement transport. No separate proactive state-machine domain exists.
-- `outbound-markup`: top-level assistant action comment/fence parsing, shared JSON/CML grammar, attribute parsing, voice reply planning, and preview/delivery stripping.
+- `outbound-markup`: delimiter-based assistant action comments, top-level button fence parsing, shared JSON/CML grammar, attribute parsing, voice reply planning, and preview/delivery stripping.
 - `outbound`: outbound text transformations, voice/button artifact delivery, and generated callback actions.
 - `generative-apps`: managed deterministic application identity, canonical installation and explicit replacement, content-addressed module loading, state timelines, cross-process transition serialization, bounded executable-plus-argv adaptation, `telegram_bind`, and pre-model-queue `app::method` invocation. It does not own Telegram transport, arbitrary shell execution, or the external application adapted by one Generative App.
 - `outbound-attachments`: `telegram_attach`, queued outbound files, stat/limit checks, ordinary photo/document delivery, and narrow single-artifact Rich Message planning/sending for probe-confirmed photo/video/audio formats. It owns known-failure fallback eligibility and ambiguous-send no-replay classification through structural error contracts without importing Bot API helpers.
@@ -685,7 +685,7 @@ Native typing during compaction follows connected-instance activity rather than
 - Thread-targeted typing is sent only to the concrete thread. Aggregate `All` mirroring is intentionally omitted because duplicating every keepalive multiplies shared-chat flood pressure. Compaction completion, failure, or timeout stops only a loop actually started by the compaction observer; a pre-existing agent-owned loop remains active. Ownership is sticky across a repeated compaction start, whose shared-loop start reports `false` for the observer's own running loop. Authority loss and shutdown still stop the keyed loop.
 - Pi `ui_prompt_start` pauses typing while an extension-owned local prompt waits for the operator; `ui_prompt_end` emits the matching Activity boundary and resumes typing whenever agent or compaction work remains unsettled.
 
-At every connected instance `agent_start`, the lifecycle binding starts Telegram's native `…typing` indicator in that instance's assigned target, whether the run came from Telegram, the local TUI, or an autonomous continuation such as Grow Loop. Terminal `Active` remains Telegram-turn-specific; the native indicator answers the separate question of whether the instance is doing agent work. Streaming keepalives reuse a valid typing owner with the same session generation, transport and target rather than revoking its pending HTTP/IPC action. Fresh context wrappers may reuse that owner within a proven generation; without generation evidence, context identity must match. Explicit queue dispatch and Telegram prompt handoff still replace the owner. Queue dispatch carries the queued turn's exact target into typing before `agent_start`, rather than reducing it to a chat ID. In Threaded Mode, missing or invalid Thread targets are refused before starting a loop or invoking the API; mode changes also invalidate a captured Classic chat-only loop. A rejected start never replaces an existing valid Thread loop. The starter also requires the captured Pi context and session generation to remain current at start, queued send, tick and late failure boundaries, even if the transport epoch is unchanged; replacing a context object in place cannot revive old activity. Message activity hooks capture generation across awaited preview work, and agent-start bindings recheck it before post-await activity/typing, so an obsolete finally or continuation cannot acquire replacement ownership. The typing sender carries its captured loop/context/generation/transport assertion as process-local call authority: direct API issuance rechecks it after queued work, and the follower caller rechecks it after registration waits and immediately before socket issuance without putting callbacks in IPC data. Automatic typing uses one HTTP attempt with no transport-family fallback or delayed replay, including forwarded calls; a future keepalive is a fresh owner-checked attempt. An already issued HTTP/RPC cannot be retroactively unsent. Each loop refreshes its exact target every three seconds and keeps one action in flight. The leader API runtime coalesces identical chat/thread/action calls for two seconds, admits different Threads independently, and shares a real Telegram 429 `retry_after` fence across every Thread key in that chat. A pending-request count retains that shared state until every concurrent action settles, so completion of a faster peer cannot orphan a late 429; expired gates prune opportunistically and each gate family retains at most 256 active keys. Suppression never schedules a delayed retry. A failed typing action remains a structured diagnostic but cannot project `error` onto an otherwise healthy connected/leader/follower status. Assistant message start/update hooks still re-arm typing during Telegram-owned turns so transient provider/model errors do not leave a continuing run without activity feedback, and agent/session completion stops it.
+At every connected instance `agent_start`, the lifecycle binding starts Telegram's native `…typing` indicator in that instance's assigned target, whether the run came from Telegram, the local TUI, or an autonomous continuation such as Grow Loop. Terminal `Active` remains Telegram-turn-specific; the native indicator answers the separate question of whether the instance is doing agent work. Streaming keepalives reuse a valid typing owner with the same session generation, transport and target rather than revoking its pending HTTP/IPC action. Fresh context wrappers may reuse that owner within a proven generation; without generation evidence, context identity must match. Explicit queue dispatch and Telegram prompt handoff still replace the owner. Queue dispatch carries the queued turn's exact target into typing before `agent_start`, rather than reducing it to a chat ID. In Threaded Mode, missing or invalid Thread targets are refused before starting a loop or invoking the API; mode changes also invalidate a captured Classic chat-only loop. A rejected start never replaces an existing valid Thread loop. The starter also requires the captured Pi context and session generation to remain current at start, queued send, tick and late failure boundaries, even if the transport epoch is unchanged; replacing a context object in place cannot revive old activity. Message activity hooks capture generation across awaited preview work, and agent-start bindings recheck it before post-await activity/typing, so an obsolete finally or continuation cannot acquire replacement ownership. The typing sender carries its captured loop/context/generation/transport assertion as process-local call authority: direct API issuance rechecks it after queued work, and the follower caller rechecks it after registration waits and immediately before socket issuance without putting callbacks in IPC data. Automatic typing uses one HTTP attempt with no transport-family fallback or delayed replay, including forwarded calls; a future keepalive is a fresh owner-checked attempt. An already issued HTTP/RPC cannot be retroactively unsent. An ended loop supplies a process-local cancellation observation: only a typed API authority refusal with no underlying failure and paired with that proof is omitted from API failure logs, while the call still rejects without success or retry. If authority expires while handling a real HTTP/network failure, the authority error retains that failure as its cause and the API recorder logs the original failure. Active-owner refusals and HTTP/network failures keep their diagnostics; the cancellation observation never crosses IPC. Each loop refreshes its exact target every three seconds and keeps one action in flight. The leader API runtime coalesces identical chat/thread/action calls for two seconds, admits different Threads independently, and shares a real Telegram 429 `retry_after` fence across every Thread key in that chat. A pending-request count retains that shared state until every concurrent action settles, so completion of a faster peer cannot orphan a late 429; expired gates prune opportunistically and each gate family retains at most 256 active keys. Suppression never schedules a delayed retry. A failed typing action remains a structured diagnostic but cannot project `error` onto an otherwise healthy connected/leader/follower status. Assistant message start/update hooks still re-arm typing during Telegram-owned turns so transient provider/model errors do not leave a continuing run without activity feedback, and agent/session completion stops it.
 
 ### Rendering And Delivery
 
@@ -714,14 +714,14 @@ Outbound files staged during an active Telegram turn are delivered after that tu
 
 The channel-post journal records only this agent path's own publication intent. `prepare` is exact and idempotent; `beginPublication` durably changes one prepared operation to outcome-unknown before any future non-idempotent send; only `confirmPublished` records the returned numeric channel/message identity. A retry never regains issuance from outcome-unknown or published state. The store validates profile and token fingerprint, refuses malformed/duplicate/over-capacity state, and lists newest retained records without claiming Telegram history. The public-`@username` direct-leader sender now uses the tool-call ID to prepare and begin this journal transition before `sendRichMessage`, then records the returned numeric channel/message identity plus bounded username/title observed by `getChat`. Retained outcome-unknown state refuses automatic replay. Bounded agent-facing listing is available locally. Exact edit/delete journal transitions fence each tool-call mutation as outcome-unknown before direct-leader `editMessageText` or `deleteMessage`, and require the same mutation ID to confirm edited or deleted state. Numeric-channel publication requires explicit `channel: true`; direct-leader `getChat` must prove the exact negative ID and channel type before issuance, and the send response must preserve that identity. Cross-process regressions prove one winner for concurrent publication/edit/delete issuance and no restart regrant. Reads fail closed before parsing links, foreign/loose files, unsupported no-follow platforms, identity races, or oversized input. No legacy post schema is migrated: absent state starts empty and unknown versions/fields fail closed. The 0.44 downgrade checker leaves this inert journal untouched because old code cannot issue its effects. Only an explicit successful list returns retained authored Markdown. Channel publication/list/mutation failures and runtime events use fixed messages without retained content, token, path, or arbitrary transport detail. Production-helper regressions model a lost successful caller ACK and an ambiguous send response: the same operation returns retained success or refuses outcome-unknown without a second transport call. The retry uses a freshly opened replacement store, proving durable behavior across helper replacement/restart. A native entrypoint regression disconnects/reconnects direct ownership and proves both retained success and ambiguous outcome avoid a second `sendRichMessage`. Sender-rights and live rollout evidence remain separate 0.45.0 work. Channel media posts upload one local `.jpg`/`.jpeg`/`.png`/`.webp` photo or `.mp4` video through the multipart transport with `text` as the HTML caption; kind, byte size (photo ≤ 10 MiB, video ≤ 50 MiB), and 1024 visible caption characters are validated before issuance, and unsupported types or albums are rejected rather than downgraded to links. The journal binds the inspected kind/file name/byte size/SHA-256 media identity and caption, so duplicate requests and lost acknowledgements never re-upload. A media-post edit replaces the caption through `editMessageCaption` with the same Markdown-to-HTML rendering, where `||spoiler||` now renders as `<tg-spoiler>`.
 
-Assistant-authored final-message actions use hidden top-level comments, with an additional fenced wrapper for in-body buttons:
+Assistant-authored final-message actions use hidden HTML comments, with an additional fenced wrapper for in-body buttons:
 
 - `telegram_voice` accepts one positional compact action cell or JSON object and creates one voice artifact through configured outbound handlers, programmatic voice handlers, or registered synthesis providers.
 - `telegram_button` accepts a JSON object, adaptive JSON/CML matrix, or positional Compact Matrix Literal. Named JSON objects and positional cells may coexist, with commas optional only between completed matrix or row elements. Each top-level cell creates one full-width row, while a nested row groups buttons horizontally without an artificial parser-width cap; every callback enqueues its configured prompt text as a normal Telegram prompt turn. The JSON-first grammar, positional trim/escape rules, atomic rejection, and renderer-owned width policy are specified in [Adaptive Button Literal](./compact-matrix-literal.md).
 
-Standalone column-zero triple-backtick `telegram_button` blocks reuse the same cell/matrix grammar and callback store, including adjacent complete cells and matrices whose normalized rows concatenate in source order, and compile to native Rich Markdown button rows between paragraphs. Rendering validates each complete block before registering any callbacks, escapes label text, preserves disabled cells, and leaves larger enclosing fences literal. Previews hide complete and unfinished action fences. HTML mode projects those controls into the footer. In-body callbacks acknowledge without rewriting the Rich message; selected-style highlighting remains footer-only.
+Standalone `telegram_button` fenced blocks reuse the same cell/matrix grammar and callback store, including adjacent complete cells and matrices whose normalized rows concatenate in source order, and compile to native Rich Markdown button rows between paragraphs. Rendering validates each complete block before registering any callbacks, escapes label text, preserves disabled cells, and leaves enclosing fenced examples literal. Opening and closing lines allow spaces/tabs; openings accept three or more backticks or tildes, optional whitespace before the exact `telegram_button` name, and trailing whitespace. Closures must use the same marker and at least the opening length, with no other text. Previews hide complete and unfinished action fences. HTML mode projects those controls into the footer. In-body callbacks acknowledge without rewriting the Rich message; selected-style highlighting remains footer-only.
 
-Action recognition remains restricted to top-level column-zero comments and exact-name button fences so nested examples cannot trigger voice, buttons, or callbacks. The Telegram surface independently strips every complete assistant-authored HTML comment from previews and final delivery regardless of Markdown position or comment owner; an unclosed comment is withheld through the remaining tail, and a comment-only result sends no text message. Pi's terminal transcript and model context remain unchanged.
+Complete HTML action comments activate solely by their delimiters and accepted payload, independent of whitespace, adjacent text, lists, quotes or code fences. Same-line comments are independent. Escape the opening delimiter as `&lt;!--` to show a literal example; backticks and backslashes do not disable an action comment. Exact-name button fences retain their separate top-level recognition rules. The Telegram surface independently strips every complete assistant-authored HTML comment from previews and final delivery regardless of Markdown position or comment owner; an unclosed comment is withheld through the remaining tail, and a comment-only result sends no text message. Pi's terminal transcript and model context remain unchanged.
 
 Unknown callback data outside owned prefixes is forwarded as `[callback] <data>` only after built-in and extension handlers decline it.
 

package/node_modules/@llblab/pi-telegram/docs/compact-matrix-literal.md

@@ -154,7 +154,7 @@ For `telegram_button` hidden comments and fenced blocks:
 - Nested rows become horizontal keyboard rows; horizontal intent still requires the explicit nested array.
 - Invalid payloads are stripped with their recognized action comment and register no callbacks.
 
-The wrapper selects placement without changing cell semantics. A hidden `telegram_button` HTML comment builds the footer keyboard. A standalone column-zero fenced block opened by exactly three backticks plus `telegram_button` renders rows between paragraphs in Native Rich Markdown. A singleton JSON/CML object needs no array in either wrapper. Fenced content must be one complete group sequence without trailing envelope text; any invalid group rejects the entire block before callback registration. Larger outer fences and ordinary code blocks remain literal examples; unclosed action fences are withheld. Native Rich rows support at most eight buttons and must fit one message chunk; these are renderer constraints, not grammar limits. HTML compatibility places fenced controls in the footer. See [Outbound](./outbound.md) for delivery and callback behavior.
+The wrapper selects placement without changing cell semantics. A hidden `telegram_button` HTML comment builds the footer keyboard. A standalone fenced block opened by at least three backticks or tildes plus the exact name `telegram_button` renders rows between paragraphs in Native Rich Markdown. Delimiter lines accept horizontal indentation, optional whitespace before the name, and trailing spaces/tabs. Close on a separate line using the same marker and at least the opening length, with no other text. Enclosing code fences keep button-block examples literal. A singleton JSON/CML object needs no array in either wrapper. Fenced content must be one complete group sequence without trailing envelope text; any invalid group rejects the entire block before callback registration. Larger outer fences and ordinary code blocks remain literal examples; unclosed action fences are withheld. Native Rich rows support at most eight buttons and must fit one message chunk; these are renderer constraints, not grammar limits. HTML compatibility places fenced controls in the footer. See [Outbound](./outbound.md) for delivery and callback behavior.
 
 ````markdown
 Description.

package/node_modules/@llblab/pi-telegram/docs/generative-apps.md

@@ -49,7 +49,7 @@ An app name is a unique lowercase ASCII identifier accepted by the runtime's pat
 
 ## Inference-Bypass Syntax
 
-Compact Matrix Literal and full JSON buttons keep their existing `label + prompt` contract. App output may use hidden `telegram_button` comments for footer controls or standalone triple-backtick `telegram_button` blocks between paragraphs; both singleton cells and mixed matrices retain the same generation/revision-bound routing. In-body controls acknowledge clicks without recoloring the message; HTML compatibility moves them to the footer. A bound action is encoded entirely in the prompt string:
+Compact Matrix Literal and full JSON buttons keep their existing `label + prompt` contract. App output may use hidden `telegram_button` comments for footer controls or standalone `telegram_button` fenced blocks between paragraphs (three or more backticks or tildes, horizontal indentation/whitespace tolerated, same-marker closure no shorter than the opening); both singleton cells and mixed matrices retain the same generation/revision-bound routing. In-body controls acknowledge clicks without recoloring the message; HTML compatibility moves them to the footer. A bound action is encoded entirely in the prompt string:
 
 ```ebnf
 bound-action = app "::" method [ "(" json-value ")" ]

package/node_modules/@llblab/pi-telegram/docs/outbound.md

@@ -2,7 +2,7 @@
 
 `pi-telegram` maps hidden assistant-authored HTML comments to Telegram-native outbound actions.
 
-Normal Telegram-turn replies are intentionally prompt-driven: the agent writes Markdown plus small hidden top-level blocks, and the bridge performs transport after `agent_end`. `telegram_voice` and `telegram_button` are not Pi tools. Action activation remains restricted to recognized top-level column-zero comments, but Telegram preview and final delivery remove every assistant-authored `<!-- … -->` block regardless of Markdown position or owning extension. Unclosed comment tails are withheld, comment-only text plans send no message, and the Pi terminal transcript remains unchanged. For local/TUI-initiated work where the user explicitly asks to send something to Telegram, the bridge also exposes direct tools: `telegram_message` for Markdown text and `telegram_attach` for file delivery when no Telegram turn is active. In classic mode, direct local/TUI delivery requires this Pi instance to own `/telegram-connect`; in Threaded Mode, a registered follower may route direct-tool sends through the leader-owned bus transport. During an active Telegram turn, `telegram_message` rejects an implicit or same-turn target so ordinary final delivery remains the sole current-target response. Its `thread` argument accepts a case-insensitive live thread name or numeric id: the bridge preflights one live owner, sends visibly, then admits the text as a source-attributed turn in that instance. Unknown, ambiguous, same-target, offline, and cross-chat destinations fail before sending. Existing `chat_id` plus `thread_id` targeting stays compatible; registered followers use authenticated, generation-fenced bus routing. Outbound behavior combines assistant prompt markup, text command-template handlers, registered voice synthesis providers, generated artifacts, direct Telegram tools, and reply delivery. Direct `telegram_message` text is planned through the same reply markup path, so embedded top-level `telegram_button` comments become buttons attached to that text message.
+Normal Telegram-turn replies are intentionally prompt-driven: the agent writes Markdown plus small hidden HTML comments, and the bridge performs transport after `agent_end`. `telegram_voice` and `telegram_button` are not Pi tools. Complete action comments activate by their delimiters and accepted payload regardless of surrounding whitespace or Markdown, including code fences; Telegram preview and final delivery remove every assistant-authored `<!-- … -->` block regardless of Markdown position or owning extension. Unclosed comment tails are withheld, comment-only text plans send no message, and the Pi terminal transcript remains unchanged. For local/TUI-initiated work where the user explicitly asks to send something to Telegram, the bridge also exposes direct tools: `telegram_message` for Markdown text and `telegram_attach` for file delivery when no Telegram turn is active. In classic mode, direct local/TUI delivery requires this Pi instance to own `/telegram-connect`; in Threaded Mode, a registered follower may route direct-tool sends through the leader-owned bus transport. During an active Telegram turn, `telegram_message` rejects an implicit or same-turn target so ordinary final delivery remains the sole current-target response. Its `thread` argument accepts a case-insensitive live thread name or numeric id: the bridge preflights one live owner, sends visibly, then admits the text as a source-attributed turn in that instance. Unknown, ambiguous, same-target, offline, and cross-chat destinations fail before sending. Existing `chat_id` plus `thread_id` targeting stays compatible; registered followers use authenticated, generation-fenced bus routing. Outbound behavior combines assistant prompt markup, text command-template handlers, registered voice synthesis providers, generated artifacts, direct Telegram tools, and reply delivery. Direct `telegram_message` text is planned through the same reply markup path, so embedded `telegram_button` comments become buttons attached to that text message.
 
 Text handlers use the portable [Command Template Standard](./command-templates.md). Programmatic outbound handlers use `registerTelegramOutboundHandler(kind, handler)`. Voice replies can use configured command-template handlers or the provider API described in [Voice Integration](./voice.md).
 
@@ -163,11 +163,11 @@ Full text answer stays here.
 <!-- telegram_voice {"text":"First line.\nSecond line.","lang":"ru"} -->
 ```
 
-The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` action to a provider call, generates one file per action, and sends each file as an independent Telegram-native voice message. Prefer `{text}`, `{text|lang}`, or `{text|lang|rate}`. Use JSON when multiline content, named fields, or escaping earns the extra syntax; equivalent JSON `text` or `value` supplies the spoken payload, with explicit `text` taking precedence. Each comment creates one voice artifact, so voice cells do not accept button-style matrix composition. The opening marker must start at column zero on a top-level line outside fenced code, quotes, lists, and indented examples; otherwise it does not activate a voice action and is still removed from the Telegram surface.
+The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` action to a provider call, generates one file per action, and sends each file as an independent Telegram-native voice message. Prefer `{text}`, `{text|lang}`, or `{text|lang|rate}`. Use JSON when multiline content, named fields, or escaping earns the extra syntax; equivalent JSON `text` or `value` supplies the spoken payload, with explicit `text` taking precedence. Each comment creates one voice artifact, so voice cells do not accept button-style matrix composition. Complete voice comments activate anywhere, including inline, indented, quoted and fenced text; surrounding Markdown is not an action boundary. Escape the opening delimiter as `&lt;!--` for literal examples.
 
 ## Buttons Markup
 
-Assistant replies can include one or many button actions through a top-level `telegram_button` comment:
+Assistant replies can include one or many button actions through a `telegram_button` HTML comment:
 
 ```md
 I can continue.
@@ -181,15 +181,15 @@ Rules:
 
 - The payload may be a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row. Commas are optional between completed elements, and one trailing comma before a closing delimiter is tolerated; JSON object validation likewise tolerates trailing commas but does not invent missing values, property names, or internal separators. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style`; the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. A fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling, permitting an empty style atom in this form: `{|Next||1}`. An omitted fourth position stays enabled. JSON uses boolean `disabled`; legacy attributes accept `disabled="true"` or `disabled="false"`. Invalid disabled values reject the candidate matrix atomically. Disabled cells require no prompt or selected style: `{Next|||1}` is label-only and `{|||1}` is blank, equivalent to JSON `{"label":"Next","disabled":true}` and `{"disabled":true}`. They retain their row and label, serialize as `{ text, disabled: {} }` (non-breaking-space text for a blank cell), and register no callback, prompt, or bound app action. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`.
 - Use `label` plus `prompt`, or the compact `value` key when both strings are identical. If only `label`, only `prompt`, one-field `{value}`, or prompt-only `{|prompt}` is present, that string supplies both visible label and queued prompt. An explicit counterpart takes precedence over `value`. Use JSON with `\n` escapes for multiline prompts.
-- The opening marker must start at column zero on a top-level line outside fenced code, quotes, lists, and indented examples; otherwise it does not activate a button action and is still removed from the Telegram surface.
+- Complete HTML comments activate by their delimiters and accepted payload, regardless of indentation, surrounding text, lists, quotes or code fences. Multiple comments on one line are independent. Escape the opening delimiter as `&lt;!--` for literal examples; backticks and backslashes do not disable action comments.
 - Prefer one matrix comment for multiple buttons. Each top-level JSON object or CML cell becomes one full-width inline-keyboard row in source order; a nested row groups one or more buttons horizontally. The parser imposes no artificial per-row width cap; empty rows, malformed cells, unknown/trailing CML escapes, a fourth unescaped CML separator, empty enabled-cell prompts or three-atom styles, invalid disabled flags, empty one-atom cells, unknown selected styles, and deeper nesting are rejected atomically. Multi-atom cells may omit the label; four-atom cells may additionally omit the selected style, and disabled cells may omit the prompt. Generated surfaces default to five columns and expand to six through eight only for short position-bearing labels. Repeated singular comments remain valid.
 - Button actions are stored in memory with short `callback_data`; Telegram never sees the full prompt in the button payload.
-- Standalone column-zero fences opened by exactly three backticks and `telegram_button` use the same singleton/matrix JSON/CML grammar. Button wrappers accept adjacent complete JSON/CML cells and matrices with optional commas between groups. Their normalized rows concatenate in source order: `[{A|a}] [{B|b}]` equals `[{A|a}{B|b}]`; a singleton cell is one vertical row and horizontal peers still require a row nested inside a matrix. Any invalid group in a fence rejects the entire block before callback registration. Complete valid blocks become native `<tg-button-row>` elements in `InputRichMessage.markdown`, at their original positions. Each row supports at most eight buttons and must fit a Rich Message chunk; validation precedes callback registration for the entire block. Labels are escaped, prompts never enter the native markup, and disabled cells have no callback. Missing closures, trailing payload garbage, and invalid blocks produce no controls. Other language names and enclosing code examples stay literal. Draft previews withhold complete and unfinished action fences without registering actions. HTML compatibility projects fenced rows into the bottom keyboard before comment-authored footer rows; source ordering within each group is retained.
+- Standalone fences opened by at least three backticks or tildes and the exact name `telegram_button` use the same singleton/matrix JSON/CML grammar. Delimiter lines accept horizontal indentation, optional spaces/tabs before the name, and trailing whitespace. A closing line must use the same marker with at least the opening length and only surrounding horizontal whitespace; inline, quoted/list-prefixed delimiters and name suffixes do not activate a block. Button wrappers accept adjacent complete JSON/CML cells and matrices with optional commas between groups. Their normalized rows concatenate in source order: `[{A|a}] [{B|b}]` equals `[{A|a}{B|b}]`; a singleton cell is one vertical row and horizontal peers still require a row nested inside a matrix. Any invalid group in a fence rejects the entire block before callback registration. Complete valid blocks become native `<tg-button-row>` elements in `InputRichMessage.markdown`, at their original positions. Each row supports at most eight buttons and must fit a Rich Message chunk; validation precedes callback registration for the entire block. Labels are escaped, prompts never enter the native markup, and disabled cells have no callback. Missing closures, trailing payload garbage, and invalid blocks produce no controls. Other language names and enclosing code examples stay literal. Draft previews withhold complete and unfinished action fences without registering actions. HTML compatibility projects fenced rows into the bottom keyboard before comment-authored footer rows; source ordering within each group is retained.
 - In-body controls share prompt/app dispatch, TTL, generation/revision checks, and sent-message target ownership with footer controls. Their acknowledgement is the selection feedback; `selected_style` does not recolor the Rich body. No callback-triggered body rewrite is introduced, preventing a stale click from overwriting newer app output. The operator confirmed the post-reload current-client smoke: singleton CML and mixed JSON/CML in-body rows, their ordinary prompt callbacks, a labeled disabled control, and the separate footer callback work as intended. Client type was not recorded. The operator also confirmed that HTML mode projects the in-body groups into the bottom keyboard as intended. Second-client coverage, follower routing, blank cells, and app-method dispatch/revision rejection remain live-gated. Bot API evidence: `InputRichBlockButtons` / Rich Markdown `tg-button-row` and `RichMessageButton` use ordinary `callback_data` and support disabled controls.
 - After Telegram accepts a generated footer button callback as a queued prompt, the bridge changes that exact button to its configured selection style without changing agent-authored text or emoji. Set `selected_style` to `primary` (blue), `success` (green), or `danger` (red); omitted or invalid values fall back to `primary`. The style never suppresses queue admission. Other choices stay visually unchanged and remain available; the callback acknowledgement remains the fallback on clients that do not render button styles.
 - When generated button markup is the entire assistant reply, the bridge supplies the standard `☑️ **Choose an option:**` heading as visible message text so Telegram has a message to which it can attach the inline keyboard.
 
-Do not emit inline comments after visible text, standalone button actions, or tool calls for ordinary Telegram-turn buttons. The agent writes Markdown plus hidden comments; the bridge strips comments and attaches Telegram `reply_markup` after `agent_end`. For local/TUI-originated direct sends, put the same Markdown and `telegram_button` comments in `telegram_message(text)`.
+Prefer separate comment lines for readability; inline comments also activate. Do not use tool calls for ordinary Telegram-turn buttons. The agent writes Markdown plus hidden comments; the bridge strips comments and attaches Telegram `reply_markup` after `agent_end`. For local/TUI-originated direct sends, put the same Markdown and `telegram_button` comments in `telegram_message(text)`.
 
 Buttons are built in and do not need a command template because they are pure Telegram reply markup plus callback routing.
 
@@ -203,8 +203,8 @@ The extension injects prompt guidance by context:
 - For Telegram-originated turns, the compact note routes the agent to `telegram-bridge` for voice/button/direct-delivery/Threaded Mode/formatting/debug guidance and to `show-me` when the user needs a visual explanation of work or behavior.
 - For ordinary Telegram-originated answers, write the full technical answer as phone-width Markdown. `show-me` may instead deliver a focused self-contained HTML artifact when explicitly requested or when spatial density earns it, while keeping the immediate reply useful.
 - Add `telegram_voice` with positional CML by default or JSON when multiline content, named fields, or escaping requires it. A companion summary is optional, no specific summary format is required.
-- Add `telegram_button` with a JSON object, JSON matrix, or positional CML. Use a hidden comment for footer placement or a standalone triple-backtick `telegram_button` block for placement between paragraphs. Prefer one matrix for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` and boolean `disabled` are optional. Keep at least one useful enabled action on an interactive surface. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
-- For ordinary Telegram-turn replies, do not call transport tools for voice or buttons; the bridge owns delivery, while registered voice synthesis providers own TTS and OGG/Opus conversion. For explicit local/TUI direct sends, `telegram_message` may include top-level `telegram_button` comments in its Markdown text because those buttons are attached to that text message.
+- Add `telegram_button` with a JSON object, JSON matrix, or positional CML. Use a hidden comment for footer placement or a standalone `telegram_button` fenced block for placement between paragraphs. Prefer one matrix for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` and boolean `disabled` are optional. Keep at least one useful enabled action on an interactive surface. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
+- For ordinary Telegram-turn replies, do not call transport tools for voice or buttons; the bridge owns delivery, while registered voice synthesis providers own TTS and OGG/Opus conversion. For explicit local/TUI direct sends, `telegram_message` may include `telegram_button` comments in its Markdown text because those buttons are attached to that text message.
 - Prefer meaningful visible parent text when it adds context; for a button-only answer, rely on the bridge's automatic `☑️ **Choose an option:**` fallback rather than manufacturing duplicate text.
 
 This keeps the agent focused on semantics, prevents Telegram action syntax from leaking into normal local replies, and lets the bridge handle low-latency Telegram adaptation.

package/node_modules/@llblab/pi-telegram/docs/public-api.md

@@ -68,7 +68,7 @@ An unbound Thread chooser offers **⛔️ Cancel routing** to the current paired
 
 ### Tools and assistant-authored actions
 
-Every assistant-authored HTML comment is transport-private on Telegram: previews and final replies remove `<!-- … -->` blocks regardless of Markdown nesting or which extension owns the comment, while only recognized top-level column-zero comments can activate voice or buttons. Unclosed comment tails are withheld and a comment-only result sends no text message; Pi's terminal transcript remains unchanged.
+Every assistant-authored HTML comment is transport-private on Telegram: previews and final replies remove `<!-- … -->` blocks regardless of Markdown nesting or which extension owns the comment, and complete recognized comments activate voice or buttons independently of surrounding whitespace or Markdown, including code fences. Escape the opening delimiter as `&lt;!--` for literal examples. Unclosed comment tails are withheld and a comment-only result sends no text message; Pi's terminal transcript remains unchanged.
 
 - `telegram_bind({ app, script, argument? } | { app, method, argument? })` installs and initializes one canonical managed Generative App module under `<agent-dir>/genapps/<app>/<app>.mjs`, or invokes one named method on an installed app. Installation rejects silent replacement and noncanonical/symlink sources. Methods receive immutable JSON state, one optional JSON argument, cancellation, revision, and a bounded non-shell process port; successful state changes commit to `state.json` plus `states.jsonl`, while output-only methods leave history unchanged. After one-shot `tgbtn` resolution, a complete `app::method` or `app::method(<strict JSON>)` prompt invokes the installed app before Pi queue admission and sends its planned Markdown/buttons directly; malformed or failed bound actions never fall back to a model prompt. Direct app-output buttons retain hidden source revisions and stale actions fail before method execution; sibling processes serialize transitions and recover dead lock owners. Bound actions send a fresh message by default and retain the clicked button's selected state on its prior surface. A result may opt into `viewMode: "edit"` to replace the callback message and keyboard in place, with one fresh-send fallback only for that explicit action. Agent-mediated initial-surface revisions, process-birth lock proof, automatic refresh, and voice output are not implemented.
 - `telegram_attach(paths, chat_id?, thread_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files before any separate final text; with `assistant.rendering: "rich"`, exactly one PNG/JPEG, MP4, or MP3 artifact plus non-empty final Markdown can become one reply-anchored Rich Message with media first. HTML mode, multiple/unsupported files, Guest Mode, and voice outputs retain their established paths. Outside Telegram turns the tool sends files directly to the paired/default chat, the registered follower's assigned thread, or an explicit `chat_id` plus optional `thread_id` when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus.
@@ -77,7 +77,7 @@ Every assistant-authored HTML comment is transport-private on Telegram: previews
 - `telegram_message(text, chat_id?, media?, channel?, thread_id?, thread?)` sends a direct Telegram Markdown message when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. A public `@username`, or an exact negative numeric channel ID with `channel: true`, is passed as `chat_id` without a local registry; channel delivery requires the direct leader, and Telegram enforces whether the bot has channel posting permission. Channel delivery accepts `media` as one local `.jpg`/`.jpeg`/`.png`/`.webp` photo or `.mp4` video (photo ≤ 10 MiB, video ≤ 50 MiB), uploaded through multipart `sendPhoto`/`sendVideo` with `text` as its HTML caption (≤ 1024 visible characters); unsupported media types and albums are rejected before issuance, and the durable channel-post journal binds media identity and caption so duplicate or lost-acknowledgement retries never re-upload. `thread` accepts a live numeric Thread id or its current acknowledged display title; name matching is case-insensitive and fails closed when absent or ambiguous, while delivery captures the numeric target. During an active Telegram turn, omitted targeting and an explicit target equal to that turn are rejected so the ordinary final-reply path remains the sole current-target response; an explicit different chat/thread target remains allowed. Outside active turns, paired/default local/TUI delivery remains unchanged. Top-level `telegram_button` comments inside `text` are parsed with the same planner used for normal replies and attached to that message; buttons are never standalone Telegram messages.
 - The bundled `telegram-bridge` Skill owns action syntax, target routing, Threaded Mode, formatting, Generative App operation, and profile-specific debugging guidance. The bundled `show-me` Skill owns portable evidence-honest explanations and adapts them to phone-width Markdown or self-contained HTML artifacts when Telegram is the active surface. The regular prompt routes applicable turns to these and the other bundled Skills. Compiled npm/git installations expose them through the package `pi.skills` manifest so Pi resource filters remain authoritative; a raw TypeScript checkout under Pi's `extensions` directory contributes its source Skill root at runtime instead. `telegram_attach`, `telegram_bind`, and `telegram_message` remain registered but are model-active only while this instance owns direct transport or holds a live follower registration; disconnect/loss suppresses their schemas and prompt metadata, and recovery restores only the operator's previously active pi-telegram subset.
 - `telegram_voice` hidden comments request Telegram-native voice delivery through `{text}`, `{text|lang}`, `{text|lang|rate}`, or a JSON object. JSON is the fallback for multiline content, named fields, or escaping; equivalent `text` or `value` supplies the spoken payload, with explicit `text` taking precedence.
-- `telegram_button` hidden comments create footer buttons; standalone column-zero triple-backtick `telegram_button` blocks create button rows between paragraphs in Native Rich Markdown. Both accept the same singleton or mixed JSON/CML matrix and share prompt/app routing; both wrappers also accept adjacent complete JSON/CML cells and matrices with optional separators, concatenating their normalized rows in source order. Cells remain singleton rows and nested horizontal rows retain their grouping. Native rows allow at most eight buttons and must fit one Rich Message chunk; invalid or incomplete blocks register nothing. Drafts hide action fences. HTML compatibility projects fenced controls into the footer. In-body clicks acknowledge without recoloring the Rich body; selected-style highlighting remains footer-only. One marker accepts a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row; separators are optional and one trailing comma is tolerated at matrix, row, and JSON-object boundaries. Top-level cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}`, `{label|prompt}`, prompt-only `{|prompt}`, or the corresponding three-atom form with `selected_style`; an omitted label uses the existing prompt-as-label fallback, and the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. A fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling; an omitted fourth position stays enabled, and the third atom may be empty in this form (`{|Next||1}`). JSON uses boolean `disabled`. Disabled cells need no prompt or selected style: `{Next|||1}` is label-only and `{|||1}` is blank (JSON `{"label":"Next","disabled":true}` and `{"disabled":true}`). The Telegram renderer supplies a non-breaking space only when the label is empty. Disabled cells stay visible but carry `disabled: {}` instead of callback data and register no prompt or bound action; invalid disabled values reject the candidate matrix. It trims atom boundaries and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. Use top-level column-zero action wrappers, outside quotes, lists, or enclosing code examples. Ordinary code fences and larger outer fences preserve literal examples; bare JSON/CML in prose never activates.
+- `telegram_button` hidden comments create footer buttons; standalone `telegram_button` fenced blocks create button rows between paragraphs in Native Rich Markdown. Delimiter lines tolerate horizontal indentation and whitespace before the exact name. Open with at least three backticks or tildes; close on a separate line with the same marker and no shorter a run, allowing only surrounding spaces/tabs. Enclosing code fences keep button-block examples literal. Both accept the same singleton or mixed JSON/CML matrix and share prompt/app routing; both wrappers also accept adjacent complete JSON/CML cells and matrices with optional separators, concatenating their normalized rows in source order. Cells remain singleton rows and nested horizontal rows retain their grouping. Native rows allow at most eight buttons and must fit one Rich Message chunk; invalid or incomplete blocks register nothing. Drafts hide action fences. HTML compatibility projects fenced controls into the footer. In-body clicks acknowledge without recoloring the Rich body; selected-style highlighting remains footer-only. One marker accepts a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row; separators are optional and one trailing comma is tolerated at matrix, row, and JSON-object boundaries. Top-level cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}`, `{label|prompt}`, prompt-only `{|prompt}`, or the corresponding three-atom form with `selected_style`; an omitted label uses the existing prompt-as-label fallback, and the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. A fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling; an omitted fourth position stays enabled, and the third atom may be empty in this form (`{|Next||1}`). JSON uses boolean `disabled`. Disabled cells need no prompt or selected style: `{Next|||1}` is label-only and `{|||1}` is blank (JSON `{"label":"Next","disabled":true}` and `{"disabled":true}`). The Telegram renderer supplies a non-breaking space only when the label is empty. Disabled cells stay visible but carry `disabled: {}` instead of callback data and register no prompt or bound action; invalid disabled values reject the candidate matrix. It trims atom boundaries and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. HTML action comments activate regardless of surrounding Markdown; escape their opening delimiter for literal examples. Button fences require standalone delimiter lines outside enclosing code examples and quote/list prefixes, but allow horizontal indentation. Bare JSON/CML in prose never activates.
 
 Prompt guidance is context-aware: local/TUI prompts see only explicit direct-delivery guidance, while Telegram-originated turns receive the full action-comment syntax and phone-width output contract.
 

package/node_modules/@llblab/pi-telegram/lib/outbound-buttons.ts

@@ -15,7 +15,7 @@ import {
   parseTelegramActionPayloadRows,
   parseTelegramButtonPayloadRows,
   replaceTelegramButtonFences,
-  replaceTopLevelHtmlComments,
+  replaceTelegramHtmlComments,
 } from "./outbound-markup.ts";
 import {
   type PendingTelegramTurn,
@@ -237,8 +237,21 @@ export function planTelegramButtonReply(
       ),
     );
   };
+  const footerKeyboard: TelegramOutboundButtonMarkup["inline_keyboard"] = [];
+  const stripped = replaceTelegramHtmlComments(markdown, (comment) => {
+    const command = "telegram_button";
+    const normalizedContent = comment.content
+      .replace(/^\s+/, "")
+      .replace(/^!/, "");
+    if (!normalizedContent.startsWith(command)) return comment.raw;
+    const payloadRows = parseTelegramActionPayloadRows(comment, command);
+    if (!payloadRows) return "";
+    const rows = buildRows(payloadRows, false);
+    if (rows) footerKeyboard.push(...rows);
+    return "";
+  });
   const withRichButtons = replaceTelegramButtonFences(
-    markdown,
+    stripped,
     (payload, closed) => {
       if (!closed) return "";
       const payloadRows = parseTelegramButtonPayloadRows(payload);
@@ -253,19 +266,8 @@ export function planTelegramButtonReply(
       return `\n${rows.map(renderTelegramRichButtonRow).join("\n\n")}\n`;
     },
   );
-  const stripped = replaceTopLevelHtmlComments(withRichButtons, (comment) => {
-    const command = "telegram_button";
-    const normalizedContent = comment.content
-      .replace(/^\s+/, "")
-      .replace(/^!/, "");
-    if (!normalizedContent.startsWith(command)) return comment.raw;
-    const payloadRows = parseTelegramActionPayloadRows(comment, command);
-    if (!payloadRows) return "";
-    const rows = buildRows(payloadRows, false);
-    if (rows) keyboard.push(...rows);
-    return "";
-  });
-  const visibleMarkdown = normalizeMarkdownAfterButtonExtraction(stripped);
+  keyboard.push(...footerKeyboard);
+  const visibleMarkdown = normalizeMarkdownAfterButtonExtraction(withRichButtons);
   return {
     markdown:
       keyboard.length > 0 && !visibleMarkdown

package/node_modules/@llblab/pi-telegram/lib/outbound-markup.ts

@@ -1,12 +1,12 @@
 /**
  * Telegram outbound markup parsing helpers
  * Zones: telegram outbound, assistant markup
- * Owns top-level assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
+ * Owns delimiter-based assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
  */
 
 import { isWireRecord as isTelegramActionPayload } from "./wire.ts";
 
-export interface TelegramTopLevelHtmlComment {
+export interface TelegramHtmlComment {
   raw: string;
   content: string;
   start: number;
@@ -34,7 +34,7 @@ function getMarkdownLineText(
 function getTopLevelOpeningFence(
   line: string,
 ): TelegramTopLevelFenceState | undefined {
-  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})/);
+  const match = line.match(/^[ \t]*(`{3,}|~{3,})/);
   const sequence = match?.[1];
   if (!sequence) return undefined;
   return {
@@ -47,7 +47,7 @@ function isTopLevelClosingFence(
   line: string,
   fence: TelegramTopLevelFenceState,
 ): boolean {
-  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})([ \t]*)$/);
+  const match = line.match(/^[ \t]*(`{3,}|~{3,})[ \t]*$/);
   const sequence = match?.[1];
   return (
     !!sequence &&
@@ -56,38 +56,21 @@ function isTopLevelClosingFence(
   );
 }
 
-export function collectTopLevelHtmlComments(markdown: string): {
-  comments: TelegramTopLevelHtmlComment[];
+export function collectTelegramHtmlComments(markdown: string): {
+  comments: TelegramHtmlComment[];
   openCommentStart?: number;
 } {
-  const comments: TelegramTopLevelHtmlComment[] = [];
+  const comments: TelegramHtmlComment[] = [];
   let offset = 0;
-  let fence: TelegramTopLevelFenceState | undefined;
   while (offset < markdown.length) {
-    const lineEnd = getMarkdownLineEnd(markdown, offset);
-    const line = getMarkdownLineText(markdown, offset, lineEnd);
-    if (fence) {
-      if (isTopLevelClosingFence(line, fence)) fence = undefined;
-      offset = lineEnd;
-      continue;
-    }
-    const nextFence = getTopLevelOpeningFence(line);
-    if (nextFence) {
-      fence = nextFence;
-      offset = lineEnd;
-      continue;
-    }
-    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);
-      const content = raw.slice(4, -3);
-      comments.push({ raw, content, start: offset, end });
-      offset = getMarkdownLineEnd(markdown, end);
-      continue;
-    }
-    offset = lineEnd;
+    const start = markdown.indexOf("<!--", offset);
+    if (start === -1) break;
+    const closeIndex = markdown.indexOf("-->", start + 4);
+    if (closeIndex === -1) return { comments, openCommentStart: start };
+    const end = closeIndex + 3;
+    const raw = markdown.slice(start, end);
+    comments.push({ raw, content: raw.slice(4, -3), start, end });
+    offset = end;
   }
   return { comments };
 }
@@ -122,7 +105,7 @@ export function replaceTelegramButtonFences(
       continue;
     } else {
       fence = getTopLevelOpeningFence(line);
-      if (fence && /^```telegram_button[ \t]*$/.test(line)) {
+      if (fence && /^[ \t]*(?:`{3,}|~{3,})[ \t]*telegram_button[ \t]*$/.test(line)) {
         actionStart = offset;
         contentStart = end;
       }
@@ -136,11 +119,11 @@ export function replaceTelegramButtonFences(
   return result + markdown.slice(copied);
 }
 
-export function replaceTopLevelHtmlComments(
+export function replaceTelegramHtmlComments(
   markdown: string,
-  replacer: (comment: TelegramTopLevelHtmlComment) => string,
+  replacer: (comment: TelegramHtmlComment) => string,
 ): string {
-  const { comments } = collectTopLevelHtmlComments(markdown);
+  const { comments } = collectTelegramHtmlComments(markdown);
   if (comments.length === 0) return markdown;
   let result = "";
   let offset = 0;
@@ -152,32 +135,9 @@ export function replaceTopLevelHtmlComments(
   return result + markdown.slice(offset);
 }
 
-function findTopLevelOpenOrPartialHtmlCommentIndex(markdown: string): number {
-  const { openCommentStart } = collectTopLevelHtmlComments(markdown);
-  if (openCommentStart !== undefined) return openCommentStart;
-  let offset = 0;
-  let fence: TelegramTopLevelFenceState | undefined;
-  while (offset < markdown.length) {
-    const lineEnd = getMarkdownLineEnd(markdown, offset);
-    const line = getMarkdownLineText(markdown, offset, lineEnd);
-    const isLastLine = lineEnd >= markdown.length;
-    if (fence) {
-      if (isTopLevelClosingFence(line, fence)) fence = undefined;
-      offset = lineEnd;
-      continue;
-    }
-    const nextFence = getTopLevelOpeningFence(line);
-    if (nextFence) {
-      fence = nextFence;
-      offset = lineEnd;
-      continue;
-    }
-    if (isLastLine && (line === "<" || line === "<!" || line === "<!-")) {
-      return offset;
-    }
-    offset = lineEnd;
-  }
-  return -1;
+function findOpenOrPartialHtmlCommentIndex(markdown: string): number {
+  const start = markdown.indexOf("<!--");
+  return start >= 0 ? start : (markdown.match(/<(?:!-?)?$/u)?.index ?? -1);
 }
 
 function parseTolerantTelegramAttributes(
@@ -263,7 +223,7 @@ function blankTelegramActionSpan(
  * with every structured span blanked; implausible `[` starts are skipped without a parse attempt.
  */
 function scanTelegramActionComment<T>(
-  comment: TelegramTopLevelHtmlComment,
+  comment: TelegramHtmlComment,
   command: string,
   parseStructured: (content: string, offset: number) => T | undefined,
 ): { payload: T } | { attributeEnvelope: string } | undefined {
@@ -287,7 +247,7 @@ function scanTelegramActionComment<T>(
 }
 
 function parseTelegramActionPayload(
-  comment: TelegramTopLevelHtmlComment,
+  comment: TelegramHtmlComment,
   command: string,
 ): Record<string, unknown> | undefined {
   const scanned = scanTelegramActionComment(
@@ -594,7 +554,7 @@ export function parseTelegramButtonPayloadRows(
 }
 
 export function parseTelegramActionPayloadRows(
-  comment: TelegramTopLevelHtmlComment,
+  comment: TelegramHtmlComment,
   command: string,
 ): Record<string, unknown>[][] | undefined {
   const scanned = scanTelegramActionComment(
@@ -665,7 +625,7 @@ export function stripTelegramCommentMarkupForPreview(markdown: string): string {
     replaceTelegramButtonFences(markdown, () => ""),
   );
   const openBlockIndex =
-    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
+    findOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
   const previewMarkdown =
     openBlockIndex >= 0
       ? withoutClosedBlocks.slice(0, openBlockIndex)
@@ -678,7 +638,7 @@ export function stripTelegramCommentMarkupForDelivery(
 ): string {
   const withoutClosedBlocks = stripTelegramHtmlCommentBlocks(markdown);
   const openBlockIndex =
-    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
+    findOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
   const deliveryMarkdown =
     openBlockIndex >= 0
       ? withoutClosedBlocks.slice(0, openBlockIndex)
@@ -716,7 +676,7 @@ export function planTelegramVoiceReply(
   const voiceReplies: TelegramVoiceReplyItem[] = [];
   let lang: string | undefined;
   let rate: string | undefined;
-  const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
+  const stripped = replaceTelegramHtmlComments(markdown, (comment) => {
     const command = "telegram_voice";
     const normalizedContent = comment.content
       .replace(/^\s+/, "")

package/node_modules/@llblab/pi-telegram/lib/outbound.ts

@@ -849,11 +849,11 @@ export function createTelegramOutboundReplyPlanner(
       ...(options?.binding ? { binding: options.binding } : {}),
     });
 
-    // Button replies can also contain <!-- telegram_voice --> markup
-    const voiceReply = planTelegramVoiceReply(buttonReply.markdown);
+    // Extract voice from the original text before button-fence rendering consumes it.
+    const voiceReply = planTelegramVoiceReply(markdown);
 
     return {
-      markdown: voiceReply.markdown,
+      markdown: stripTelegramCommentMarkupForDelivery(buttonReply.markdown),
       ...(buttonReply.replyMarkup
         ? { replyMarkup: buttonReply.replyMarkup }
         : {}),

package/node_modules/@llblab/pi-telegram/lib/prompts.ts

@@ -34,7 +34,7 @@ export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "For an explicitly requested channel post, pass its exact numeric id or public @username as chat_id; no local channel registry is required, and Telegram remains the authority on the bot's posting permission.",
   "For an explicitly requested channel media post, pass one local .jpg/.jpeg/.png/.webp photo or .mp4 video as media; the text becomes its caption (max 1024 characters), and albums or other media types are rejected.",
   "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.",
-  "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
+  "Add buttons by embedding the same telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
   "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
 ] as const;
 

package/node_modules/@llblab/pi-telegram/lib/runtime.ts

@@ -360,7 +360,7 @@ export interface TelegramTypingLoopStarterDeps<
   getDefaultChatId: () => number | undefined;
   sendTypingAction: (
     chatId: number,
-    options?: { message_thread_id?: number; assertAuthority?: () => void },
+    options?: { message_thread_id?: number; assertAuthority?: () => void; isCancelled?: () => boolean },
   ) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   isContextActive?: (ctx: TContext) => boolean;
@@ -454,6 +454,7 @@ export function createTelegramTypingLoopStarter<TContext>(
         try {
           await deps.sendTypingAction(targetChatId, {
             ...actionOptions,
+            isCancelled: () => !active,
             // This stays process-local; adapters recheck it before HTTP/IPC issuance, not just loop ticks.
             assertAuthority() {
               if (!active || !canContinue()) throw new Error("Typing context authority changed.");

package/node_modules/@llblab/pi-telegram/lib/telegram-api.ts

@@ -407,8 +407,8 @@ export interface TelegramApiCallOptions {
 
 export class TelegramApiAuthorityError extends Error {
   readonly requestIssued: boolean;
-  constructor(requestIssued: boolean) {
-    super("Telegram API call authority is unavailable.");
+  constructor(requestIssued: boolean, options?: ErrorOptions) {
+    super("Telegram API call authority is unavailable.", options);
     this.name = "TelegramApiAuthorityError";
     this.requestIssued = requestIssued;
   }
@@ -418,11 +418,12 @@ export class TelegramApiAuthorityError extends Error {
 export function assertTelegramApiCallAuthority(
   assertAuthority: (() => void) | undefined,
   requestIssued: boolean,
+  errorOptions?: ErrorOptions,
 ): void {
   try {
     assertAuthority?.();
   } catch {
-    throw new TelegramApiAuthorityError(requestIssued);
+    throw new TelegramApiAuthorityError(requestIssued, errorOptions);
   }
 }
 
@@ -847,6 +848,8 @@ export interface TelegramBridgeApiRuntimeDeps {
 /** Typing issuance guard is local authority, never Bot API body or IPC data. */
 export interface TelegramTypingActionOptions extends Pick<TelegramApiCallOptions, "assertAuthority"> {
   message_thread_id?: number;
+  /** Diagnostic observation only: an ended loop does not grant issuance, success or retry. */
+  isCancelled?: () => boolean;
 }
 
 export interface TelegramBridgeApiRuntime extends Pick<
@@ -1649,7 +1652,7 @@ async function callTelegramWithRetry<TResponse>(
     } catch (error) {
       // Authority refusal is never a transport failure, retry grant or acknowledged success.
       if (error instanceof TelegramApiAuthorityError) throw error;
-      assertTelegramApiCallAuthority(assertAuthority, requestIssued);
+      assertTelegramApiCallAuthority(assertAuthority, requestIssued, { cause: error });
       const retryable =
         isRetryableTelegramApiError(error) &&
         !(
@@ -2189,11 +2192,14 @@ export function createTelegramBridgeApiRuntime(
             );
             return true as TResponse;
           }
-          deps.recordRuntimeEvent(
-            "api",
-            error,
-            withTelegramTransportDiagnostics(error, { method }),
-          );
+          const diagnosticError = error instanceof TelegramApiAuthorityError && Object.hasOwn(error, "cause")
+            ? error.cause : error;
+          if (!options?.isExpectedError?.(error))
+            deps.recordRuntimeEvent(
+              "api",
+              diagnosticError,
+              withTelegramTransportDiagnostics(diagnosticError, { method }),
+            );
           throw error;
         })
         .finally(() => {
@@ -2311,14 +2317,21 @@ export function createTelegramBridgeApiRuntime(
           : {}),
       }),
     sendTypingAction: createTelegramChatActionSender(
-      (chatId, action, options) =>
-        callRecorded<boolean>("sendChatAction", {
+      (chatId, action, options) => {
+        const isCancelled = options?.isCancelled;
+        return callRecorded<boolean>("sendChatAction", {
           chat_id: chatId,
           action,
           ...(options?.message_thread_id !== undefined
             ? { message_thread_id: options.message_thread_id }
             : {}),
-        }, { assertAuthority: options?.assertAuthority }),
+        }, {
+          assertAuthority: options?.assertAuthority,
+          ...(isCancelled ? {
+            isExpectedError: (error: unknown) => error instanceof TelegramApiAuthorityError && !Object.hasOwn(error, "cause") && isCancelled() === true,
+          } : {}),
+        });
+      },
       "typing",
     ),
     sendRecordVoiceAction: createTelegramChatActionSender(

package/node_modules/@llblab/pi-telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.58.1",
+  "version": "0.58.3",
   "private": false,
   "publishConfig": {
     "access": "public"