@llblab/pi-kit 0.2.0 → 0.3.0

package/AGENTS.md

@@ -24,6 +24,7 @@
 - Expose only resources declared by each included package. Prefer published distribution entrypoints over source entrypoints when both exist.
 - Do not copy extension source, Skills, or documentation into this repository.
 - Preserve package independence: a kit release may advance any subset of included extensions without forcing lockstep extension releases.
+- Derive the kit version bump from the highest dependency bump in the synchronized release cohort: dependency patch-only updates require a kit patch bump, while any dependency minor update requires a kit minor bump. Do not let lower-level dependency bumps force a larger kit bump.
 - Use English for public and repository-facing text.
 - Do not commit, publish, tag, create a remote repository, or mutate Pi settings without explicit authorization.
 

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.3.0 - 2026-09-01
+
+- `Telegram Minor Release`: Advances `@llblab/pi-telegram` to `0.42.0`, bringing tolerant JSON and compact CML action parsing, positional voice action cells, Thread-aware generated-button prompts, and focused proactive control-surface guidance into the bundled kit.
+- `Release Cohort Policy`: Codifies that the kit follows the highest dependency bump in each synchronized cohort, so dependency patch-only updates produce kit patches while any dependency minor update produces a kit minor.
+
 ## 0.2.0 - 2026-08-31
 
 - `Actors Minor Releases`: Advances `@llblab/pi-actors` to `0.52.0`, bringing root-owned follow-ups, durable completion epochs, presentation acknowledgment, recovery-safe scheduling, explicit urgent steering, and settled packed-package parity into the bundled kit.

package/README.md

@@ -9,7 +9,7 @@
 | `@llblab/pi-actors` | `0.52.0` | Extension and Skills |
 | `@llblab/pi-codex-usage` | `0.9.4` | Extension |
 | `@llblab/pi-grow-loop` | `0.7.3` | Extension and Skills |
-| `@llblab/pi-telegram` | `0.41.0` | Extension and Skills |
+| `@llblab/pi-telegram` | `0.42.0` | Extension and Skills |
 
 Versions are exact by design. Updating an extension does not change an installed kit until this repository explicitly advances that dependency and publishes a new kit version.
 

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.42.0: Compact Action Grammar
+
+- `Adaptive Action Grammar`: Extracts the first semantically valid JSON or positional CML payload from noisy `telegram_button` and `telegram_voice` envelopes, tolerates bounded trailing commas and unmatched matrix noise, keeps malformed named JSON on the JSON path, and retains legacy attribute parsing as undocumented compatibility.
+- `Voice Action Cells`: Adds compact `{text}`, `{text|lang}`, and `{text|lang|rate}` voice actions while preserving JSON for multiline, named, and escape-heavy payloads; each voice comment remains one independent artifact and matrix-shaped voice payloads fail closed.
+- `Thread-Aware Buttons`: Tags prompts created by generated-button callbacks with the same resolved Telegram Thread label as ordinary inbound turns, preserving current local labels, persisted bindings, target routing, queue ordering, and callback selection behavior.
+- `Focused Agent Guidance`: Makes generated control surfaces proactively emit useful emoji-led prompt buttons, keeps Telegram action syntax under the bridge owner, and moves specialized delivery, configuration, diagnosis, layout, state, and capability guidance behind conditional references to reduce default context without dropping safety constraints.
+
+## 0.41.1: Focused Operator Status Hotfix
+
+- `Next Turn Feedback`: Replies one Pi-aligned fully bold abort notice to the aborted Telegram turn, falls back to the `/next` command for local work, preserves completed intermediate output, and suppresses pending aborted assistant text so one forced transition no longer produces a contradictory second reply.
+- `Status Telemetry`: Keeps the Tokens row compact with input/output totals and moves cache read/write plus the latest cache-hit rate into a dedicated Cache row.
+- `Reply Transcription`: Runs replied voice and other media through the inbound handler/provider pipeline and appends provenance-scoped outputs inside the reply context, including Guest Mode, instead of leaving quoted audio as an untranscribed attachment.
+- `Information Hierarchy`: Brings access-denial and Threaded Mode chooser headings back under the common fully bold emoji-led sentence/colon contract.
+
 ## 0.41.0: Connected Companion Presence
 
 - `Always-On Projection`: Treats authorized Telegram connection as the public-output boundary for local, autonomous, and unclassified Pi work, always delivering completed visible blocks in order instead of exposing an independent proactive-push opt-out.

package/node_modules/@llblab/pi-telegram/README.md

@@ -10,7 +10,7 @@ It is a **runtime adapter**, not a remote terminal. Start or supervise work in t
 
 Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. While Telegram is connected, local, autonomous, and unclassified extension follow-up work also projects visible checkpoints and the final answer to the authorized Telegram target once and in order, preserving assistant-authored `telegram_button` comments as interactive prompt buttons. This connected companion projection is always active rather than configurable. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate `Activity` setting defaults to `verbose` so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose `quiet`. See [Outbound](docs/outbound.md#public-assistant-output) and the [configuration reference](docs/public-api.md#configuration-api).
 
-This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
+This repository is an actively maintained standalone fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 
 ## Install
 
@@ -218,11 +218,11 @@ Inbound files land under `<agent-dir>/tmp/telegram` and default to a 50 MiB limi
 
 ### Voice And Media
 
-Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Configure provider-neutral local/API pipelines and ordered fallbacks through [`telegram.json` command templates](./docs/voice.md#choose-an-integration-path). The default `manual` reply mode still supports intentional voice delivery through explicit `telegram_voice` actions; `mirror` and `always` add automatic voice policy. Explicit actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and one colon-free action marker.
+Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Configure provider-neutral local/API pipelines and ordered fallbacks through [`telegram.json` command templates](./docs/voice.md#choose-an-integration-path). The default `manual` reply mode still supports intentional voice delivery through explicit `telegram_voice` actions; `mirror` and `always` add automatic voice policy. Explicit actions prefer positional `{text}`, `{text|lang}`, or `{text|lang|rate}` cells and use JSON for multiline content, named fields, or escaping.
 
 ### Buttons And Callbacks
 
-Assistant replies can include top-level hidden `telegram_button` comments using a JSON object, adaptive JSON/CML matrix, positional Compact Matrix Literal (CML), or compact double-quoted attributes; `telegram_buttons` is a plural alias. One adaptive matrix may mix named JSON objects with positional CML cells, and commas between completed matrix or row elements are optional while JSON object internals remain strict. Top-level cells become full-width rows while nested rows group one or more buttons horizontally without an artificial parser-level width cap; generated surfaces default to five columns and use six to eight only for short position-bearing labels. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}` with `primary`, `success`, or `danger`; the optional style requires an explicit prompt. It trims atom boundaries, preserves non-structural text literally, and decodes only `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Buttons use `label` plus `prompt`, or the compact `value` key when both are identical. The action marker is colon-free for every payload form. The bridge strips the comments from visible text, renders inline buttons, and routes callbacks back into Pi as queued prompts or extension-owned callback actions. Button-only replies receive the standard `☑️ **Choose an option:**` heading as automatic visible fallback text. Once a generated prompt button is accepted, only that exact button switches to its optional `selected_style` (`primary` blue by default, `success` green, or `danger` red) without altering its agent-authored label or emoji; every style still queues the selected prompt.
+Assistant replies can include top-level hidden `telegram_button` comments containing a JSON object, adaptive JSON/CML matrix, or positional Compact Matrix Literal (CML). One adaptive matrix may mix named JSON objects with positional CML cells; separators are optional and one trailing comma is tolerated, including inside JSON objects. Top-level cells become full-width rows while nested rows group one or more buttons horizontally without an artificial parser-level width cap; generated surfaces default to five columns and use six to eight only for short position-bearing labels. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}` with `primary`, `success`, or `danger`; the optional style requires an explicit prompt. It trims atom boundaries, preserves non-structural text literally, and decodes only `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Buttons use `label` plus `prompt`, or the compact `value` key when both are identical. The bridge strips the comments from visible text, renders inline buttons, and routes callbacks back into Pi as queued prompts or extension-owned callback actions. Button-only replies receive the standard `☑️ **Choose an option:**` heading as automatic visible fallback text. Once a generated prompt button is accepted, only that exact button switches to its optional `selected_style` (`primary` blue by default, `success` green, or `danger` red) without altering its agent-authored label or emoji; every style still queues the selected prompt.
 
 ### Threaded Mode And Multi-Instance Bus
 

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

@@ -301,7 +301,7 @@ Immediate controls:
 - `/start` opens the main inline application menu.
 - `/model`, `/thinking`, `/queue`, and `/settings` are hidden shortcuts to menu sections.
 - `/compact` opens an inline confirmation dialog and then runs compaction when the bridge is idle.
-- `/next` dispatches the next queued turn, aborting Pi first when needed.
+- `/next` dispatches the next queued turn, aborting Pi first when needed. When an active Telegram turn is aborted, its single Pi-aligned informational notice replies to a pre-abort snapshot of that turn; otherwise the command message is the fallback target. Aborted pending assistant text is not projected as a second reply, while already completed intermediate output remains visible.
 - `/abort` aborts active work while preserving queued items. Abort-history preservation is enabled only for Telegram-owned active turns; later local/non-Telegram agent starts clear stale abort-history mode so the next Telegram prompt appends instead of absorbing old queued turns as history.
 - `/stop` aborts and clears waiting Telegram queue items.
 
@@ -336,7 +336,7 @@ Assistant delivery guarantees:
 - Model-authored Markdown is the source of truth; the bridge does not pre-render assistant Markdown to HTML unless the operator selects `assistant.rendering: "html"` for compatibility.
 - Before native Rich Markdown delivery, the bridge normalizes known Bot-API-fragile source forms without changing visible meaning, including space-after-marker blockquotes and dollar-prefixed ticker atoms that Telegram may otherwise treat as unterminated math.
 - Prompt context blocks use compact metadata (`[tag|key:value]`) as the stable inbound contract. `[telegram...]` names the current surface only: owner/current turns use `[telegram]` or `[telegram|thread:<name>]`; guest-mode turns use `[telegram|guest:<group-title-or-peer-username-or-id>]`. In a private Guest Mode turn the paired owner's `from` identity is never the guest: the remote private-chat identity wins, then non-owner caller metadata, with a non-bot replied peer available only as a final identity fallback when stronger conversation evidence is absent; username falls back to the remote display name and numeric id. Reply attribution still belongs independently in `[reply|from:...]`, and a replied bot can never define or replace the current `[telegram|guest:...]` location identity. Source authors for quoted/forwarded material and their files are carried by `[reply|from:<username-or-id>]`, `[forward|from:<username-or-id>]`, and `[attachments|from:<username-or-id>]`, while plain `[attachments]` remains current-turn attachments and is ordered before reply/forward/source context. Media embedded in inbound Telegram `rich_message` blocks is downloaded like ordinary message media and stays attached to its forward-source block instead of being mislabeled as current-user material.
-- Quoted rich replies use Telegram `rich_message` blocks as the prompt-context source when available, so `[reply]` context receives rendered plain text instead of raw `InputRichMessage.markdown` fallback text.
+- Quoted rich replies use Telegram `rich_message` blocks as the prompt-context source when available, so `[reply]` context receives rendered plain text instead of raw `InputRichMessage.markdown` fallback text. Replied media runs through the same inbound handlers and voice transcription providers as current-message media, with provenance-scoped `[outputs|from:…]` appended inside the reply block.
 - Long native Markdown replies are split only at Telegram Rich Message transport limits; oversized fenced code, display-math, and fully wrapped inline-formatting blocks are rewrapped per chunk so persisted Rich Markdown chunks remain structurally valid.
 - When Draft previews are enabled, streaming previews pass structurally closed assistant Markdown prefixes through to `sendRichMessageDraft` with ownership checks, voice suppression, and serialized flushes. Unclosed inline spans, links, fenced code, comments, and display-math blocks are held back until a safe boundary exists. Draft failures are recorded and the failing frame is skipped instead of degrading to raw plain-message previews, because partial Markdown can be invalid while the final message remains valid.
 - Preview flushes are serialized so older edits cannot race newer drafts; final delivery waits for active draft flushes and does not perform a post-final draft-clear call.
@@ -352,10 +352,10 @@ Final delivery attaches reply metadata only where requested. Reply parameters ap
 
 Outbound files staged during an active Telegram turn are delivered after that turn completes. They use `telegram_attach`, are checked atomically per tool call, and use configurable size limits before photo/document upload. When no Telegram turn is active, `telegram_attach` sends files immediately to the paired/default chat, an assigned follower thread, or an explicit `chat_id` plus optional `thread_id`; `telegram_message` provides direct local/TUI Markdown text delivery for explicit user requests and runs the same `telegram_button` markup planner so buttons attach to that text message. Direct local/TUI delivery is singleton-controlled: classic mode requires this Pi instance to own `/telegram-connect`, while Threaded Mode followers must be registered and route through the leader-owned transport. Already accepted active-turn reply/attachment delivery remains session-local.
 
-Assistant-authored final-message actions use hidden top-level comments with colon-free markers; colon-prefixed payloads are rejected:
+Assistant-authored final-message actions use hidden top-level comments:
 
-- `telegram_voice` accepts a JSON object or double-quoted HTML-like attributes and creates voice reply artifacts through configured outbound handlers, programmatic voice handlers, or registered synthesis providers.
-- `telegram_button` accepts a JSON object, adaptive JSON/CML matrix, positional Compact Matrix Literal, or double-quoted attributes; `telegram_buttons` aliases the same parser. 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).
+- `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).
 
 Preview delivery strips top-level action comments before streaming draft Markdown. Comments inside code fences, quotes, lists, or indented examples stay literal.
 
@@ -390,7 +390,7 @@ The bridge does not mirror arbitrary `ctx.ui.confirm/input/select/custom` prompt
 
 ## Diagnostics And Operational Behavior
 
-Status rendering distinguishes connected, active, dispatching, queued, tool-running, model-switching, and compacting states; the Telegram status menu gives compaction precedence over generic active or pending work. Its Tokens row mirrors Pi's terminal footer, including inline `R` cache-read tokens, `W` cache-write tokens, and `CH` for the latest assistant request's cache-read share of prompt tokens rather than a misleading cumulative-session ratio; the label remains distinct from companion-provided usage limits. Observed automatic compaction sends the same start and completion notices as the manual command without duplicating notices for command-owned compaction. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, status remains active instead of degrading to connected.
+Status rendering distinguishes connected, active, dispatching, queued, tool-running, model-switching, and compacting states; the Telegram status menu gives compaction precedence over generic active or pending work. Its compact Tokens row shows only input and output totals, while the adjacent Cache row groups `R` cache-read tokens, `W` cache-write tokens, and `CH` for the latest assistant request's cache-read share of prompt tokens rather than a misleading cumulative-session ratio; the labels remain distinct from companion-provided usage limits. Observed automatic compaction sends the same start and completion notices as the manual command without duplicating notices for command-owned compaction. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, status remains active instead of degrading to connected.
 
 Queue reaction behavior, lane-tail transitions, Keep/Skip independence, multi-reaction precedence, and the Bot API reaction-removal limitation are defined in [Priority, Reactions, Keep, and Skip](#priority-reactions-keep-and-skip). Reaction changes first flush a matching delayed text or media group so the governed turn exists before mutation, and dropping marked heads cannot leave status permanently queued.
 

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

@@ -1,6 +1,6 @@
 # Adaptive Button Literal
 
-> Status: Portable CML v3 standard implemented by the unreleased `pi-telegram` control-surface parser.
+> Status: Portable CML v3 button standard; `pi-telegram` also reuses its positional-cell mechanics for compact voice actions.
 
 Adaptive Button Literal is one bounded-depth matrix grammar over a shared button AST. It accepts strict JSON button objects, positional Compact Matrix Literal (CML) cells, or both in the same matrix and row. Commas between completed matrix or row elements are optional, so producers can progressively compress representation without changing runtime meaning.
 
@@ -85,9 +85,9 @@ atom-unit       := ordinary | "\|" | "\}" | "\\"
 ws              := *(SP | HTAB | CR | LF)
 ```
 
-`boundary` occurs only after one complete element and before another. It may contain one comma or no comma. Element delimiters make empty adjacency unambiguous. Leading, repeated, and trailing commas are invalid.
+`boundary` occurs after one complete element. It may contain one comma or no comma; one trailing comma before a closing row or matrix delimiter is also tolerated. Element delimiters keep empty adjacency unambiguous. Leading and repeated commas remain invalid.
 
-A `json-object` is one complete strict JSON object. Its property commas, strings, escaping, nested values, and other internals remain ordinary strict JSON; comma optionality applies only between matrix or row elements.
+A `json-object` is one complete JSON object. Strict JSON is attempted first; a bounded recovery removes commas immediately before `}` or `]` outside strings and retries. Property names, strings, escaping, nested values, and all other internals remain strict; missing property commas are not invented.
 
 Rows cannot contain rows. The grammar never recurses beyond one row inside the top-level matrix.
 
@@ -111,29 +111,31 @@ A conforming parser:
 
 1. Attempts strict JSON first for sources beginning with `{` or `[`. Successful JSON is validated only against the existing button matrix schema and never reinterpreted.
 2. If strict JSON parsing fails, parses the original source with the adaptive grammar.
-3. Tries one complete strict JSON object at each cell boundary before positional interpretation.
-4. Accepts at most one optional comma between completed matrix or row elements.
-5. Rejects leading, repeated, trailing, or property-level omitted commas.
+3. Tries one complete strict JSON object, then bounded trailing-comma recovery, at each cell boundary before positional interpretation.
+4. Keeps JSON-shaped named objects on the JSON path when validation fails instead of exposing their source as positional text.
+5. Accepts at most one comma between elements or immediately before a closing row or matrix delimiter, while rejecting leading, repeated, or property-level omitted commas.
 6. Rejects empty atoms, matrices, rows, and nesting deeper than one row.
 7. Decodes only `\|`, `\}`, and `\\` in positional cells.
-8. Consumes exactly one complete payload and rejects trailing content.
-9. Returns no partial rows or cells after any failure.
-10. Runs in linear time over a host-bounded payload with fixed grammar depth.
+8. Extracts the first complete valid payload from a tolerant comment envelope and ignores unrelated text or isolated unmatched matrix brackets around it.
+9. Returns no partial rows or cells from a balanced malformed candidate.
+10. Runs over host-bounded payloads with fixed grammar depth.
 
 Malformed JSON-looking input receives no generic recovery. It is accepted only if it independently forms a complete valid adaptive literal.
 
-## Telegram Profile
+## Telegram Profiles
 
-For `telegram_button` and the exact `telegram_buttons` alias:
+For `telegram_button` comments:
 
 - JSON `value` keeps its existing label/prompt fallback semantics.
-- Positional `{value}` is equivalent to JSON `{"value":"value"}`.
+- Positional `{value}` is equivalent to JSON `{"value":"value"}`; a lone JSON `label` or `prompt` has the same both-fields shorthand semantics.
 - Positional `{label|prompt}` is equivalent to JSON `{"label":"label","prompt":"prompt"}`.
 - Positional `{label|prompt|selected_style}` is equivalent to the corresponding three-field JSON object.
 - Top-level cells become full-width rows.
 - Nested rows become horizontal keyboard rows.
 - Invalid payloads are stripped with their recognized action comment and register no callbacks.
 
+For `telegram_voice`, one positional cell maps `{text}`, `{text|lang}`, or `{text|lang|rate}` to one voice artifact. JSON object cells remain available for named fields, escaping, and multiline text. Voice comments do not accept matrix or row composition.
+
 Example:
 
 ```html
@@ -161,12 +163,12 @@ Accepted classes include:
 Rejected classes include:
 
 - Empty payloads, matrices, rows, labels, prompts, or style atoms.
-- Leading, repeated, or trailing element commas.
+- Leading or repeated element commas.
 - Missing commas between properties inside a JSON object.
 - Deeper row nesting.
 - Missing, crossed, or mismatched delimiters.
 - A third positional separator, unknown style, unknown escape, or trailing backslash.
-- Internal control characters and trailing garbage.
+- Internal control characters.
 - Valid JSON that fails the existing JSON action schema.
 
 Every rejected case proves zero callback registration.

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

@@ -67,7 +67,7 @@ Built-in placeholders for text handlers:
 
 ## Media/File Handlers
 
-Media/file handlers keep the legacy attachment-handler behavior: downloaded files are matched by `mime`, `type`, or `match`, then each file runs the first successful matching handler. Downloaded files with `mime: "text/plain"` or any `text/*` MIME type have a built-in fail-open handler that reads UTF-8 content into `[outputs]` when no configured handler produced output. Composition is useful for pipelines such as voice transcription followed by machine translation, so the agent receives translated `[outputs]` instead of the raw STT language.
+Media/file handlers keep the legacy attachment-handler behavior: downloaded files are matched by `mime`, `type`, or `match`, then each file runs the first successful matching handler. Attachments from a replied-to message use the same handler/provider pipeline independently; their `[outputs|from:…]` section remains inside that `[reply]` context after its attachment list instead of being attributed to the current message. Downloaded files with `mime: "text/plain"` or any `text/*` MIME type have a built-in fail-open handler that reads UTF-8 content into `[outputs]` when no configured handler produced output. Composition is useful for pipelines such as voice transcription followed by machine translation, so the agent receives translated `[outputs]` instead of the raw STT language.
 
 Built-in placeholders for media/file handlers:
 

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

@@ -129,43 +129,34 @@ Synthesis providers receive the extracted `telegram_voice` text plus optional `l
 
 ## Voice Markup
 
-Assistant replies can include hidden voice actions in either supported payload form:
+Assistant replies can include hidden voice actions as a positional compact cell or JSON object:
 
 ```md
 Full text answer stays here.
 
-<!-- telegram_voice {"value":"Short spoken companion summary.","lang":"ru","rate":"+30%"} -->
+<!-- telegram_voice {Short spoken companion summary.|ru|+30%} -->
 
-<!-- telegram_voice text="Short spoken companion summary." lang="ru" rate="+30%" -->
+<!-- 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. Equivalent `text` or `value` supplies the spoken payload, with explicit `text` taking precedence when both appear; `lang` and `rate` are optional. A colon after `telegram_voice` is rejected so both payload forms share one unambiguous action marker. Use JSON for long or escaped text and encode line breaks inside JSON strings as `\n`. The opening marker must start at column zero on a top-level line outside fenced code, quotes, lists, and indented examples; otherwise it remains literal Markdown.
+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 remains literal Markdown.
 
 ## Buttons Markup
 
-Assistant replies can include one or many button actions through one colon-free marker:
+Assistant replies can include one or many button actions through a top-level `telegram_button` comment:
 
 ```md
 I can continue.
 
-<!-- telegram_button {"label":"Continue","prompt":"Continue with the current plan.","selected_style":"primary"} -->
-
-<!-- telegram_button label="Show risks" prompt="List the main risks first." selected_style="danger" -->
-
-<!-- telegram_button {"value":"Done"} -->
-
-<!-- telegram_button [{"label":"⬆️ Up","prompt":"/"},[{"value":"⬅️ Previous"},{"value":"➡️ Next"}],{"label":"📁 etc","prompt":"/etc"}] -->
-
-<!-- telegram_buttons [[{"value":"Approve"},{"value":"Reject"}]] -->
-
 <!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
+
+<!-- telegram_button {"label":"▶️ Continue","prompt":"Continue with the current plan.","selected_style":"primary"} -->
 ```
 
 Rules:
 
-- `telegram_button` accepts a JSON object, adaptive JSON/CML matrix, positional [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted HTML-like attributes; `telegram_buttons` is an exact plural alias. Named JSON objects and positional cells may coexist in one matrix or row, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires a prompt and accepts only `primary`, `success`, or `danger`. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`. Shorthand, body, paired-comment, unquoted-attribute, and single-quoted-attribute forms are rejected.
-- A colon after either button marker is rejected so every payload form shares one unambiguous action marker.
-- Use `label` plus `prompt`, or the compact `value` key when both strings are identical. Explicit `label` or `prompt` takes precedence over its `value` fallback. Use JSON with `\n` escapes for multiline prompts.
+- 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}`, or `{label|prompt|selected_style}`; the optional third atom requires a prompt and accepts only `primary`, `success`, or `danger`. 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`, or one-field `{value}` 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 remains literal Markdown.
 - 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 third unescaped CML separator, empty atoms, unknown selected styles, and deeper nesting are rejected atomically. 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.
@@ -184,8 +175,8 @@ The extension injects prompt guidance by context:
 - For ordinary local/TUI prompts, the compact routing note points to the bundled `telegram-bridge` Skill and forbids Telegram use unless explicitly requested.
 - For Telegram-originated turns, the compact note routes the agent to `telegram-bridge`, which owns voice/button/direct-delivery/Threaded Mode/formatting/debug guidance.
 - For Telegram-originated turns, write the full technical answer as normal Markdown.
-- Add `telegram_voice` with either a JSON object or double-quoted attributes when a Telegram-native voice message is useful. A companion summary is optional, no specific summary format is required.
-- Add `telegram_button` with a JSON object, JSON matrix, or double-quoted attributes; `telegram_buttons` is an alias. Prefer one array for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` is optional. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
+- 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. Prefer one matrix for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` is optional. 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.
 - 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.
 

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

@@ -50,7 +50,7 @@ Stable commands inside the paired Telegram DM:
 
 - `/start` — pair when needed and open the main application menu.
 - `/compact` — open confirmation and compact when idle.
-- `/next` — dispatch the next queued turn, aborting active work first when needed.
+- `/next` — dispatch the next queued turn, aborting active work first when needed; one Pi-aligned informational reply anchors to a pre-abort snapshot of the Telegram turn or falls back to the command, and aborted pending assistant text is suppressed.
 - `/continue` — enqueue a priority `continue` prompt.
 - `/abort` — abort active work and keep the queue; abort-history is scoped to Telegram-owned active turns.
 - `/stop` — abort active Telegram-owned work and clear waiting Telegram queue items.
@@ -65,8 +65,8 @@ This command surface is a mobile companion subset, not a raw terminal-command br
 - `telegram_attach(paths, chat_id?, thread_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files for the active reply; with `assistant.rendering: "rich"`, exactly one PNG/JPEG, MP4, or MP3 artifact plus non-empty final Markdown can become one reply-anchored Rich Message. 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.
 - `telegram_message(text, chat_id?, thread_id?)` sends a direct Telegram Markdown message when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. 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 for requested cross-target delivery. 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 regular prompt routes applicable turns to that Skill. `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 either a JSON object or double-quoted attributes. Equivalent `text` or `value` supplies the spoken payload; explicit `text` takes precedence.
-- `telegram_button` hidden comments create inline buttons whose taps enqueue prompts. One marker accepts a JSON object, adaptive JSON/CML matrix, positional [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted attributes; `telegram_buttons` is an exact plural alias. Named JSON objects and positional cells may coexist in one matrix or row, and commas are optional only between completed elements. 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}`, or `{label|prompt|selected_style}`; the optional third atom requires a prompt and accepts only `primary`, `success`, or `danger`. 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 comments outside code, quotes, lists, and indented examples; do not emit standalone button actions.
+- `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 inline buttons whose taps enqueue prompts. 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}`, or `{label|prompt|selected_style}`; the optional third atom requires a prompt and accepts only `primary`, `success`, or `danger`. 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 comments outside code, quotes, lists, and indented examples; do not emit standalone button actions.
 
 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.
 
@@ -336,7 +336,7 @@ Contract:
 - Providers are synchronous because `/start` status text is rendered inline with the menu.
 - Return `undefined` when the line is not relevant for the active model.
 - Provider failures are isolated and skipped so optional companion status cannot break the core Telegram menu.
-- The bridge renders rows as `<Label>: <value>` in the same HTML status block as Status, Tokens, Cost, and Context, capitalizing the first label character for Telegram UI consistency. Tokens mirrors Pi's footer telemetry: `↑` input, `↓` output, `R` cache-read tokens, `W` cache-write tokens, and `CH` for the latest assistant request's `cacheRead / (input + cacheRead + cacheWrite)`, shown to one decimal place only after the session reports cache activity. The precise Tokens label avoids conflating token telemetry with companion-provided usage-limit rows.
+- The bridge renders rows as `<Label>: <value>` in the same HTML status block as Status, Tokens, Cache, Cost, and Context, capitalizing the first label character for Telegram UI consistency. Tokens contains only `↑` input and `↓` output totals. Cache groups `R` cache-read tokens, `W` cache-write tokens, and `CH` for the latest assistant request's `cacheRead / (input + cacheRead + cacheWrite)`, shown to one decimal place only after the session reports cache activity. These precise labels avoid conflating token telemetry with companion-provided usage-limit rows.
 
 ## Updates
 

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

@@ -428,6 +428,9 @@ export function createTelegramActivityBridgeRuntime(deps: {
     onAssistantEvent(event) {
       getRuntime()?.onAssistantEvent(event);
     },
+    onAssistantMessageEnd(stopReason) {
+      getRuntime()?.onAssistantMessageEnd(stopReason);
+    },
     onToolStart(event) {
       getRuntime()?.onToolStart(event);
     },
@@ -491,6 +494,7 @@ export interface TelegramActivityRuntime {
   recordInputSource: (source: TelegramActivityInputSource) => void;
   onAgentStart: (activeTelegramTarget?: TelegramActivityTarget) => void;
   onAssistantEvent: (event: TelegramAssistantStreamEvent) => void;
+  onAssistantMessageEnd: (stopReason?: string) => void;
   onToolStart: (event: {
     toolCallId: string;
     toolName: string;
@@ -677,6 +681,9 @@ export function createTelegramActivityRuntime(deps: {
       }
       if (event.type === "error") flushPendingSegment("terminal-partial");
     },
+    onAssistantMessageEnd(stopReason) {
+      if (stopReason === "aborted") pendingAssistantSegment = undefined;
+    },
     onToolStart(event) {
       emit({ type: "tool-start", ...event });
     },

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

@@ -1218,6 +1218,9 @@ export function registerTelegramLifecycleRuntimeHooks({
     },
     onMessageEnd(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      if (event.message.role === "assistant") {
+        activityRuntime.onAssistantMessageEnd(event.message.stopReason);
+      }
       terminalAssistantMessagePendingDelivery =
         event.message.role === "assistant" &&
         event.message.stopReason !== "toolUse" &&

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

@@ -1049,6 +1049,9 @@ export interface TelegramCommandRuntimeDeps<
     text: string,
     options?: { parseMode?: "HTML" },
   ) => Promise<void>;
+  getActiveTurnReply?: () =>
+    | ((text: string, options?: { parseMode?: "HTML" }) => Promise<void>)
+    | undefined;
   sendInteractiveMessage?: TelegramCompactConfirmationDeps["sendInteractiveMessage"];
   assertExecutionCurrent?: (message: TMessage) => void;
 }
@@ -1272,6 +1275,9 @@ export async function handleTelegramNextCommand(deps: {
     text: string,
     options?: { parseMode?: "HTML" },
   ) => Promise<void>;
+  getActiveTurnReply?: () =>
+    | ((text: string, options?: { parseMode?: "HTML" }) => Promise<void>)
+    | undefined;
 }): Promise<void> {
   deps.clearPendingModelSwitch();
   if (!deps.hasQueuedItems()) {
@@ -1282,16 +1288,19 @@ export async function handleTelegramNextCommand(deps: {
     return;
   }
   if (!deps.isIdle() && deps.hasAbortHandler()) {
+    const activeTurnReply = deps.getActiveTurnReply?.();
     deps.clearFoldForDispatch();
     deps.abortCurrentTurn();
     deps.updateStatus();
-    await deps.sendTextReply(
-      formatTelegramInformationHeading(
-        "⏩",
-        "Aborted! Dispatching next queued turn.",
-      ),
-      { parseMode: "HTML" },
+    const notice = formatTelegramInformationHeading(
+      "⏩",
+      "Operation aborted. Dispatching next queued turn.",
     );
+    if (activeTurnReply) {
+      await activeTurnReply(notice, { parseMode: "HTML" });
+    } else {
+      await deps.sendTextReply(notice, { parseMode: "HTML" });
+    }
     return;
   }
   if (!deps.isIdle()) {
@@ -1799,6 +1808,7 @@ async function handleTelegramCommandRuntime<
             deps.setFoldQueuedPromptsIntoHistory(false),
           updateStatus: updateStatusFor(commandCtx),
           sendTextReply: sendReplyFor(nextMessage),
+          getActiveTurnReply: deps.getActiveTurnReply,
         });
       },
       handleContinue: async (nextMessage, commandCtx) => {

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

@@ -366,6 +366,7 @@ export function extractTelegramReplyContextText(
 export function buildTelegramReplyContextBlock(
   message: TelegramMediaMessage,
   replyFiles: Pick<DownloadedTelegramFile, "path">[] = [],
+  replyOutputs: readonly string[] = [],
 ): string {
   const from = formatTelegramUser(message.reply_to_message?.from);
   const header = from ? `[reply|from:${from}]` : "[reply]";
@@ -379,10 +380,19 @@ export function buildTelegramReplyContextBlock(
     ? replyFiles.map((file) => `- /${basename(file.path)}`)
     : replyFiles.map((file) => `- ${file.path}`);
   const replyBlock = text ? `${header} ${text}` : header;
+  const sections = [replyBlock];
   if (fileLines.length > 0) {
-    return `${replyBlock}\n\n${attachmentHeader}\n${fileLines.join("\n")}`;
+    sections.push(`${attachmentHeader}\n${fileLines.join("\n")}`);
+  }
+  if (replyOutputs.length > 0) {
+    const outputHeader = `[outputs${from ? `|from:${from}` : ""}]`;
+    sections.push(
+      `${outputHeader}\n${replyOutputs.map((output) => `- ${output}`).join("\n")}`,
+    );
+  }
+  if (text || fileLines.length > 0 || replyOutputs.length > 0) {
+    return sections.join("\n\n");
   }
-  if (text) return replyBlock;
   return "";
 }
 

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

@@ -12,7 +12,6 @@ import type {
 } from "./keyboard.ts";
 import {
   parseTelegramActionPayloadRows,
-  parseTopLevelTelegramComment,
   replaceTopLevelHtmlComments,
 } from "./outbound-markup.ts";
 import {
@@ -113,8 +112,10 @@ function parseTelegramButtonAction(
   payload: Record<string, unknown>,
 ): TelegramOutboundButtonAction | undefined {
   const value = getTelegramButtonString(payload, "value");
-  const label = getTelegramButtonString(payload, "label") ?? value;
-  const prompt = getTelegramButtonString(payload, "prompt") ?? value;
+  const explicitLabel = getTelegramButtonString(payload, "label");
+  const explicitPrompt = getTelegramButtonString(payload, "prompt");
+  const label = explicitLabel ?? value ?? explicitPrompt;
+  const prompt = explicitPrompt ?? value ?? explicitLabel;
   if (!label || !prompt) return undefined;
   const selectedStyle = payload.selected_style;
   return {
@@ -179,10 +180,9 @@ export function planTelegramButtonReply(
 ): TelegramButtonReplyPlan {
   const keyboard: TelegramOutboundButtonMarkup["inline_keyboard"] = [];
   const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
-    const command = ["telegram_button", "telegram_buttons"].find((candidate) =>
-      parseTopLevelTelegramComment(comment, candidate),
-    );
-    if (!command) return comment.raw;
+    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 actionRows = payloadRows.map((payloadRow) =>
@@ -225,8 +225,9 @@ export function createTelegramButtonPromptTurn(options: {
   queueOrder: number;
   action: TelegramOutboundButtonAction;
   target?: TelegramQueueTarget;
+  telegramPrefix?: string;
 }): PendingTelegramTurn {
-  const prompt = `[telegram] ${options.action.prompt}`;
+  const prompt = `${options.telegramPrefix ?? "[telegram]"} ${options.action.prompt}`;
   return {
     kind: "prompt",
     chatId: options.chatId,