@llblab/pi-telegram 0.5.1 → 0.6.0

package/README.md

@@ -102,6 +102,7 @@ Run these inside pi, not Telegram:
 - `👎` removes a waiting turn from the queue. Telegram Bot API does not expose ordinary DM message-deletion events through the polling path used here, so queue removal is bound to the dislike reaction.
 - Reactions apply to any waiting Telegram turn, including text, voice, files, images, and media groups. For media groups, a reaction on any message in the group applies to the whole queued turn.
 - If you edit a Telegram message while it is still waiting in the queue, the queued turn is updated instead of creating a duplicate prompt. Edits after a turn has already started may not affect the active run.
+- Telegram replies to earlier text or caption messages are forwarded as `[reply]` context for normal prompts, while slash commands still parse from the new message text only.
 - Inbound images, albums, and files are saved to `~/.pi/agent/tmp/telegram`. Unhandled local file paths are included in the prompt, handled attachment output is injected into the prompt text, and inbound images are forwarded to pi as image inputs. Inbound downloads default to a 50 MiB limit and can be adjusted with `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES`.
 - Queue reactions depend on Telegram delivering `message_reaction` updates for your bot and chat type.
 
@@ -114,31 +115,73 @@ Run these inside pi, not Telegram:
   "attachmentHandlers": [
     {
       "type": "voice",
-      "template": "~/.pi/agent/skills/mistral-stt/scripts/transcribe.mjs {file} {lang} {model}",
-      "args": ["file", "lang", "model"],
-      "defaults": {
-        "lang": "ru",
-        "model": "voxtral-mini-latest"
-      }
+      "template": "/path/to/stt1 --file {file} --lang {lang=ru}",
+      "timeout": 30000
     },
     {
       "mime": "audio/*",
-      "template": "~/.pi/agent/skills/groq-stt/scripts/transcribe.mjs {file} {lang} {model}",
-      "args": ["file", "lang", "model"],
-      "defaults": {
-        "lang": "ru",
-        "model": "whisper-large-v3-turbo"
-      }
+      "template": "/path/to/stt2 --file {file} --lang {lang=ru}",
+      "timeout": 30000
     }
   ]
 }
 ```
 
-Matching supports `mime`, `type`, or `match`; wildcards like `audio/*` are accepted. Template placeholders are substituted into command args, not shell text: `{file}` is the downloaded file path, `{mime}` is the MIME type, `{type}` is the Telegram attachment type, and `defaults` can provide additional values such as `{lang}` or `{model}`. Local attachments stay in the prompt under `[attachments] <directory>` with relative file entries; successful handler stdout is added under `[outputs]`; failed handlers record diagnostics and fall back to the next matching handler. The portable command-template contract is documented in [`docs/command-templates.md`](./docs/command-templates.md); Telegram-specific handler config is documented in [`docs/attachment-handlers.md`](./docs/attachment-handlers.md).
+Matching supports `mime`, `type`, or `match`; wildcards like `audio/*` are accepted. Handlers use `template`: a string is one command, and an array is ordered composition. Template placeholders are substituted into command args, not shell text: `{file}` is the downloaded file path, `{mime}` is the MIME type, `{type}` is the Telegram attachment type, and `defaults` or inline defaults such as `{lang=ru}` can provide additional values. Examples use explicit flag-style CLIs for readability; positional script forms are also supported when the script itself supports them. Local attachments stay in the prompt under `[attachments] <directory>` with relative file entries; successful handler stdout is added under `[outputs]`; failed handlers record diagnostics and fall back to the next matching handler. The portable command-template contract is documented in [`docs/command-templates.md`](./docs/command-templates.md); Telegram-specific handler config is documented in [`docs/attachment-handlers.md`](./docs/attachment-handlers.md).
 
 ### Requesting Files
 
-If you ask pi for a file or generated artifact (e.g., _"generate a shell script and attach it"_), pi will call the `telegram_attach` tool, and the extension will send the file alongside its next Telegram reply. Outbound attachments default to a 50 MiB limit and can be adjusted with `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`.
+If you ask pi for a file or generated artifact (e.g., _"generate a shell script and attach it"_), pi can call the `telegram_attach` tool, and the extension will send the file alongside its next Telegram reply. `telegram_attach` is the only pi tool registered by `pi-telegram`; use it for ordinary files, not for Telegram-native voice or buttons. Outbound attachments default to a 50 MiB limit and can be adjusted with `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`.
+
+### Assistant-Authored Outbound Actions
+
+Assistant replies can include hidden outbound blocks. `telegram_voice` and `telegram_button` are not pi tools; they are assistant-authored HTML comments that the bridge removes from Telegram text and handles after `agent_end`. Action comments are recognized only as top-level column-zero blocks outside fenced code, quotes, and lists, so documentation examples remain literal. This is faster than agent-side tool calls because the agent only writes correctly formatted Markdown in its normal answer; the extension builds the configured voice pipeline, button markup, and callback routing itself without registering or invoking extra transport/TTS/text-to-OGG tools.
+
+#### Voice
+
+Voice blocks synthesize their body and upload it as a native Telegram `sendVoice` OGG/Opus message. The body may be a concise companion summary, but it does not have to follow that format; write the text you want spoken and keep it TTS-friendly:
+
+```md
+Full technical answer stays readable as text.
+
+<!-- telegram_voice lang=ru rate=+30%
+Text to synthesize as a Telegram voice message.
+-->
+```
+
+Outbound voice is disabled unless a matching `outboundHandlers[]` entry is configured. Multiple `telegram_voice` blocks in one reply are synthesized and sent independently, preserving each block's attributes. The bridge uses the same [command-template contract](./docs/command-templates.md) as inbound attachment handlers: split the template into args, substitute placeholders, execute without a shell, and use stdout as the result channel for a single template.
+
+A TTS plus MP3-to-OGG setup can be expressed as `template: [...]`. The bridge provides `{text}`, `{mp3}`, and `{ogg}` to every step; top-level `args`/`defaults` apply to all steps unless a step defines private values, top-level `timeout` wraps the whole sequence, and each step's stdout is passed to the next step's stdin by default. Use `"output": "ogg"` when the artifact path should come from the generated `{ogg}` value instead of final stdout:
+
+```json
+{
+  "outboundHandlers": [
+    {
+      "type": "voice",
+      "template": [
+        "/path/to/tts --text {text} --lang {lang=ru} --rate {rate=+30%} --write-media {mp3}",
+        "ffmpeg -y -i {mp3} -c:a libopus -b:a 32k -ar 16000 -ac 1 -vbr on {ogg}"
+      ],
+      "output": "ogg",
+      "timeout": 60000
+    }
+  ]
+}
+```
+
+#### Buttons
+
+Button blocks attach inline quick replies to the final text. Use one independent `telegram_button` block per action; its `label` is shown in Telegram and its body is sent back to pi when tapped:
+
+```md
+I can continue.
+
+<!-- telegram_button label="Continue"
+Continue with the current plan.
+-->
+```
+
+Button prompts are routed back into the normal Telegram queue as prompt turns. Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
 
 ## Streaming
 

package/docs/README.md

@@ -7,4 +7,5 @@ Living index of project documentation in `/docs`.
 - [architecture.md](./architecture.md) — Overview of the Telegram bridge runtime, queueing model, rendering pipeline, and interactive controls
 - [command-templates.md](./command-templates.md) — Portable command-template standard core
 - [attachment-handlers.md](./attachment-handlers.md) — Local `pi-telegram` attachment-handler config, placeholders, and fallbacks
+- [outbound-handlers.md](./outbound-handlers.md) — Local `pi-telegram` outbound-handler config, voice/button markup, artifact outputs, and callback routing
 - [locks.md](./locks.md) — Shared `locks.json` standard for singleton extension ownership

package/docs/architecture.md

@@ -23,21 +23,23 @@ Naming rule: because the repository already scopes this codebase to Telegram, ex
 
 Current runtime areas use these ownership boundaries:
 
-| Domain | Owns |
-| ------ | ---- |
-| `index.ts` | Single composition root for live pi/Telegram ports, session state, API-bound transport adapters, and status updates |
-| `api` | Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, runtime error recording |
-| `config` / `setup` | Persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, config persistence |
-| `locks` / `polling` | Singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, poll-loop runtime wiring |
-| `updates` / `routing` | Update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition |
-| `media` / `turns` / `handlers` | Text/media extraction, media-group debounce, inbound downloads, turn building/editing, image reads, attachment-handler matching/execution/fallback output |
-| `queue` | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing |
-| `runtime` | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding |
-| `model` / `menu` / `commands` | Model identity/thinking levels, scoped model resolution, in-flight switching, inline status/model/thinking UI, slash commands, bot command registration |
-| `preview` / `replies` / `rendering` | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots |
-| `attachments` | `telegram_attach` registration, outbound attachment queueing, stat/limit checks, photo/document delivery classification |
-| `status` | Status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, grouped pi diagnostics |
-| `lifecycle` / `prompts` / `pi` | pi hook registration, Telegram-specific before-agent prompt injection, centralized direct pi SDK imports and context adapters |
+| Domain                              | Owns                                                                                                                                                              |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.ts`                          | Single composition root for live pi/Telegram ports, session state, API-bound transport adapters, and status updates                                               |
+| `api`                               | Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, runtime error recording       |
+| `config` / `setup`                  | Persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, config persistence                             |
+| `locks` / `polling`                 | Singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, poll-loop runtime wiring                     |
+| `updates` / `routing`               | Update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition                                        |
+| `media` / `turns` / `attachment-handlers` | Text/media extraction, media-group debounce, inbound downloads, turn building/editing, image reads, attachment-handler matching/execution/fallback output    |
+| `queue`                             | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing |
+| `runtime`                           | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding  |
+| `model` / `menu` / `commands`       | Model identity/thinking levels, scoped model resolution, in-flight switching, inline status/model/thinking UI, slash commands, bot command registration           |
+| `preview` / `replies` / `rendering` | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots                     |
+| `outbound-handlers`                 | Assistant-authored outbound comments, generated reply artifacts, inline-keyboard callbacks, and post-`agent_end` outbound action delivery                         |
+| `attachments`                       | `telegram_attach` registration, outbound attachment queueing, stat/limit checks, photo/document delivery classification                                           |
+| `status`                            | Status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, grouped pi diagnostics                                                 |
+| `lifecycle` / `prompts` / `pi`      | pi hook registration, Telegram-specific before-agent prompt injection, centralized direct pi SDK imports and context adapters                                     |
+| `command-templates`                 | Portable shell-free command-template standard helpers, composition expansion, placeholder substitution, and executable resolution                                  |
 
 Boundary invariants:
 
@@ -71,13 +73,14 @@ Telegram bot configuration stays in `~/.pi/agent/telegram.json`; singleton runti
 2. Each update offset is persisted only after the update handler succeeds; repeated handler failures are bounded so one poisoned update cannot stall polling forever
 3. The bridge filters to the paired private user
 4. Media groups are coalesced into a single Telegram turn when needed
-5. Files are streamed into `~/.pi/agent/tmp/telegram` with a default 50 MiB size limit, partial-download cleanup on failures, and stale temp cleanup on session start; operators can tune the limit with `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES`
-6. Configured inbound attachment handlers may run on downloaded files by MIME wildcard, Telegram attachment type, or generic match selector; command templates receive safe command-arg substitution for `{file}`/`{mime}`/`{type}`
-7. Matching handlers are tried in config order: a non-zero exit records diagnostics and falls back to the next matching handler, while the first successful handler stops the chain
-8. Local attachments stay visible under `[attachments] <directory>` with relative file entries, and handler stdout is appended under `[outputs]` before the agent sees the turn; failed handlers omit output while keeping the attachment entry
-9. A `PendingTelegramTurn` is created and queued locally
-10. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
-11. The queue dispatcher sends the turn into pi only when dispatch is safe
+5. Slash command parsing uses only the new message text/caption, while Telegram `reply_to_message` text/caption is injected later as prompt-only `[reply]` context for normal queued turns
+6. Files are streamed into `~/.pi/agent/tmp/telegram` with a default 50 MiB size limit, partial-download cleanup on failures, and stale temp cleanup on session start; operators can tune the limit with `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES`
+7. Configured inbound attachment handlers may run on downloaded files by MIME wildcard, Telegram attachment type, or generic match selector; command templates receive safe command-arg substitution for `{file}`/`{mime}`/`{type}`
+8. Matching handlers are tried in config order: a non-zero exit records diagnostics and falls back to the next matching handler, while the first successful handler stops the chain
+9. Local attachments stay visible under `[attachments] <directory>` with relative file entries, and handler stdout is appended under `[outputs]` before the agent sees the turn; failed handlers omit output while keeping the attachment entry
+10. A `PendingTelegramTurn` is created and queued locally
+11. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
+12. The queue dispatcher sends the turn into pi only when dispatch is safe
 
 ### Queue Safety Model
 
@@ -90,12 +93,12 @@ Queued items now use two explicit dimensions:
 
 Admission contract:
 
-| Admission             | Examples                                             | Queue shape                                                          | Dispatch rank |
-| --------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | ------------- |
-| Immediate execution   | `/compact`, `/stop`, `/help`, `/start`               | Does not enter the Telegram queue; `/stop` also clears queued items  | N/A           |
+| Admission             | Examples                                                     | Queue shape                                                          | Dispatch rank |
+| --------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- | ------------- |
+| Immediate execution   | `/compact`, `/stop`, `/help`, `/start`                       | Does not enter the Telegram queue; `/stop` also clears queued items  | N/A           |
 | Control queue         | Model-switch continuation turns and future deferred controls | `queueLane: control`; accepts control items and continuation prompts | 0             |
-| Priority prompt queue | A waiting prompt promoted by `👍`                    | `kind: prompt`, `queueLane: priority`                                | 1             |
-| Default prompt queue  | Normal Telegram text/media turns                     | `kind: prompt`, `queueLane: default`                                 | 2             |
+| Priority prompt queue | A waiting prompt promoted by `👍`                            | `kind: prompt`, `queueLane: priority`                                | 1             |
+| Default prompt queue  | Normal Telegram text/media turns                             | `kind: prompt`, `queueLane: default`                                 | 2             |
 
 The command action itself carries its execution mode, and the queue domain exposes lane contracts for admission mode, dispatch rank, and allowed item kinds. Queue append and planning paths validate lane admission so a malformed control/default or other invalid lane pairing fails predictably instead of silently changing priority. This lets synthetic control actions and Telegram prompts share one stable ordering model while still rendering distinctly in status output. In the pi status bar, busy labels distinguish `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`; priority prompts are marked with `⬆` while control items keep markers such as `⚡`.
 
@@ -152,6 +155,8 @@ Telegram prompt responses use explicit delivery context to attach outbound text,
 
 Outbound files are sent only after the active Telegram turn completes, must be staged through the `telegram_attach` tool, are staged atomically per tool call, are checked against a default 50 MiB limit configurable through `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`, and use file-backed multipart blobs so large sends do not require preloading whole files into memory.
 
+Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes the block body through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, top-level `timeout` wraps the whole sequence, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn. This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
+
 ## Interactive Controls
 
 The bridge exposes Telegram-side session controls in addition to regular chat forwarding.

package/docs/attachment-handlers.md

@@ -13,27 +13,19 @@ This document is the local adaptation of the portable [Command Template Standard
   "attachmentHandlers": [
     {
       "type": "voice",
-      "template": "~/.pi/agent/skills/mistral-stt/scripts/transcribe.mjs {file} {lang} {model}",
-      "args": ["file", "lang", "model"],
-      "defaults": {
-        "lang": "ru",
-        "model": "voxtral-mini-latest"
-      }
+      "template": "/path/to/stt1 --file {file} --lang {lang=ru}",
+      "timeout": 30000
     },
     {
       "mime": "audio/*",
-      "template": "~/.pi/agent/skills/groq-stt/scripts/transcribe.mjs {file} {lang} {model}",
-      "args": ["file", "lang", "model"],
-      "defaults": {
-        "lang": "ru",
-        "model": "whisper-large-v3-turbo"
-      }
+      "template": "/path/to/stt2 --file {file} --lang {lang=ru}",
+      "timeout": 30000
     }
   ]
 }
 ```
 
-Handlers match by `type`, `mime`, or `match`. Wildcards such as `audio/*` are accepted. Each matching handler must provide a `template`; optional `args` and `defaults` document or fill placeholder values.
+Handlers match by `type`, `mime`, or `match`. Wildcards such as `audio/*` are accepted. Each matching handler must provide `template`; a string is one command, and an array is ordered composition. Top-level `args` and `defaults` apply to composed steps unless a step defines private values; top-level `timeout` wraps the whole sequence instead of being inherited by leaves. Legacy configs may still use `pipe` as a local alias.
 
 ## Template Placeholders
 
@@ -45,16 +37,16 @@ Attachment handlers support these built-in placeholders:
 | `{mime}`    | MIME type if known                                               |
 | `{type}`    | Attachment kind such as `voice`, `audio`, `document`, or `photo` |
 
-`defaults` may provide additional placeholder values such as `{lang}` or `{model}`. `args` documents supported placeholders and may also encode defaults in compact form, for example `"file,lang=ru,model=voxtral-mini-latest"`.
+`defaults` may provide additional placeholder values such as `{lang}` or `{model}`. `args` is only a string-array declaration of supported placeholders; defaults belong in `defaults` or inline placeholders such as `{lang=ru}`. Examples prefer explicit flag-style CLIs for readability, but positional forms such as `/path/to/stt {file} {lang=ru} {model=voxtral-mini-latest}` are equally valid when the target script supports them.
 
-If a template has no `{file}` placeholder, the downloaded file path is appended as the last command arg.
+If a top-level one-step handler template has no `{file}` placeholder, the downloaded file path is appended as the last command arg for backwards compatibility. Composition steps are plain command templates and do not receive implicit file-path args; include `{file}` explicitly where needed.
 
 ## Ordered Fallbacks
 
-A handler list is ordered. For each attachment, matching handlers run in list order and stop after the first successful handler.
+A handler list is ordered. For each attachment, matching handlers run in list order and stop after the first successful handler. A composed handler counts as one handler for fallback purposes: if any step fails, the next matching handler is tried.
 
 If a matching handler fails with a non-zero exit code, the runtime records diagnostics and tries the next matching handler. If every matching handler fails, the attachment remains visible in the prompt as a normal local file reference.
 
 ## Prompt Output
 
-Local attachments stay in the prompt under `[attachments] <directory>` with relative file entries. Successful handler stdout is added under `[outputs]`. Empty output and failed handler output are omitted from the prompt text.
+Local attachments stay in the prompt under `[attachments] <directory>` with relative file entries. Successful handler stdout is added under `[outputs]`. For composed handlers, each step receives the previous step's stdout on stdin by default, and stdout from the last successful step is used as the handler output. Empty output and failed handler output are omitted from the prompt text.

package/docs/command-templates.md

@@ -1,34 +1,77 @@
 # Command Template Standard
 
-Command templates are the stable integration format for deterministic local automation.
+Command templates are the portable integration format for deterministic local automation. Extensions may choose their own config files, selectors, placeholder sources, and examples, but should preserve this core contract.
 
-This document is the portable core. Extensions may adapt local examples, placeholder sources, and config locations, but should preserve this contract to stay compatible with the shared command-template model.
+## Shape
 
-## Definition
+A command template is either a command-line string or an ordered array of command-template leaves:
 
-A command template is a single command-line string with named placeholders:
+```json
+{
+  "template": "/path/to/stt --file {file} --lang {lang=ru}"
+}
+```
 
-```text
-~/bin/transcribe {file} {lang}
+When the surrounding schema already implies a command template, the compact string form is equivalent:
+
+```json
+"/path/to/stt --file {file} --lang {lang=ru}"
 ```
 
-## Execution Contract
+There is no portable `command` field. The command is derived from `template`: after splitting, the first word is the executable and the remaining words are argv args. Templates do not infer flags: `{file}` is one positional arg; `--file {file}` is a flag arg plus its value.
+
+Common object fields:
+
+| Field      | Meaning                                                                                                               |
+| ---------- | --------------------------------------------------------------------------------------------------------------------- |
+| `template` | Required command string or ordered composition array                                                                  |
+| `args`     | Optional placeholder-name declarations only; never stores defaults                                                    |
+| `defaults` | Placeholder default values by name                                                                                    |
+| `timeout`  | Optional execution timeout in milliseconds                                                                            |
+| `output`   | Optional result selector; default is `"stdout"`, artifact-producing handlers may name a runtime value such as `"ogg"` |
+
+Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
 
-The runtime must:
+## Execution
 
-1. Split the template into shell-like words, honoring simple single quotes, double quotes, and backslash escapes
+A runtime must:
+
+1. Split the template into shell-like words with simple single quotes, double quotes, and backslash escapes
 2. Substitute placeholders inside each split word
-3. Execute the first word as the command and the remaining words as args
-4. Avoid evaluating the template through a shell
-5. Treat exit code `0` as success and non-zero exit as failure
-6. Use stdout as the result channel
-7. Use stderr only for diagnostics
+3. Execute command + args directly, without shell evaluation
+4. Treat exit code `0` as success and non-zero as failure
+5. Use stdout as the default result channel and stderr only for diagnostics
+
+Implementations may expand `~` in command position and may resolve relative command paths against the caller cwd.
+
+## Placeholders
+
+Supported forms:
+
+| Form             | Meaning                                          |
+| ---------------- | ------------------------------------------------ |
+| `{name}`         | Required value from runtime values or `defaults` |
+| `{name=default}` | Inline default when no value is provided         |
 
-Implementations may expand `~` in the command position and may resolve relative command paths against the caller cwd.
+Resolution order is runtime values → `defaults` → inline default → error.
 
-## Quoting Model
+```json
+{
+  "template": "/path/to/tts --text {text} --lang {lang=ru} --rate {rate=+30%}"
+}
+```
 
-Placeholder values are not shell-escaped because templates are not executed through a shell. A value containing spaces remains one command arg when it replaces one split word:
+With runtime values `{ "text": "hello" }`, argv is:
+
+```text
+["--text", "hello", "--lang", "ru", "--rate", "+30%"]
+```
+
+Use `defaults` for visible configuration data; use inline defaults for compact local literals. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
+
+## Quoting
+
+Placeholder values are not shell-escaped because no shell is used. A value containing spaces remains one argv item when it replaces one split word:
 
 ```text
 template="echo {text}"
@@ -36,10 +79,10 @@ text="hello world"
 args=["hello world"]
 ```
 
-A placeholder can also be embedded inside one word:
+A placeholder may also be embedded inside one word:
 
 ```text
-template="tool --file={file}"
+template="/path/to/tool --file={file}"
 file="/tmp/a b.ogg"
 args=["--file=/tmp/a b.ogg"]
 ```
@@ -50,26 +93,53 @@ Use quotes only for literal template words that should contain spaces before pla
 template="echo 'literal words' {text}"
 ```
 
-## Storage Vocabulary
+## Composition
 
-JSON storage is part of the standard vocabulary, but not one universal schema. Extensions may store command templates in different config files and surrounding shapes.
+`template: [...]` means sequential composition; each leaf is a command template executed with one shared runtime value map:
 
-Common field names:
+```json
+{
+  "template": [
+    "/path/to/tts --text {text} --lang {lang=ru} --out {mp3}",
+    "ffmpeg -y -i {mp3} -c:a libopus {ogg}"
+  ],
+  "output": "ogg"
+}
+```
 
-| Field      | Meaning                                                                                    |
-| ---------- | ------------------------------------------------------------------------------------------ |
-| `template` | Command-line template string, usually attached to a named capability or handler            |
-| `args`     | Declared placeholder names, represented as a string or array according to the local schema |
-| `defaults` | Object mapping placeholder names to default values                                         |
+Composition rules:
+
+- Execute leaves in order and stop on the first non-zero exit
+- Treat the whole composition as one handler for selector matching and fallback
+- Top-level `args` and `defaults` apply to every leaf unless the leaf defines private values
+- Leaf `args` replace inherited `args`; leaf `defaults` merge over inherited defaults; `timeout` and `output` are not inherited into leaves
+- Top-level `timeout` wraps the whole sequence; leaf `timeout` applies only to that leaf within the remaining total budget
+- Each leaf receives the previous leaf's stdout on stdin by default, while the final leaf stdout remains the default composition result
+- Each leaf still applies its own inline defaults
+
+```json
+{
+  "template": [
+    "/path/to/tts --text {text} --lang {lang} --out {mp3}",
+    {
+      "template": "ffmpeg -y -i {mp3} -c:a {codec} {ogg}",
+      "defaults": { "codec": "libopus" }
+    }
+  ],
+  "args": ["text", "lang", "mp3", "ogg"],
+  "defaults": { "lang": "en" },
+  "output": "ogg"
+}
+```
 
-Config file locations, selectors, labels, descriptions, and surrounding registry shapes belong to each extension's local adaptation.
+`output` selects the primary result channel. Omitted `output` means `"stdout"`, and explicitly writing `"output": "stdout"` is valid standard syntax. Artifact-producing handlers may instead name a runtime value or placeholder path, e.g. `"ogg"` or `"{ogg}"`.
 
-## Tool Boundary
+Legacy local schemas may accept `pipe` as an alias, but the portable standard is `template: [...]`.
 
-Agent tools are a separate abstraction. A tool name is not a portable command template because the pi extension API currently exposes tool registration and metadata, but not a public extension-to-extension `executeTool(name, args)` call.
+## Tool Boundary
 
-Until such an API exists, extensions should prefer command templates for deterministic local automation.
+Agent tools are a separate abstraction. A tool name is not a portable command template because the pi extension API exposes tool registration metadata, not a public extension-to-extension `executeTool(name, args)` contract. Until such an API exists, extensions should use command templates for deterministic local automation.
 
 ## Compatibility
 
-Consumers should share this template contract, not private registry fields or implementation details from any specific extension.
+Consumers should share this contract, not private registry fields or implementation details from any specific extension.

package/docs/outbound-handlers.md

@@ -0,0 +1,110 @@
+# Outbound Handlers
+
+`pi-telegram` maps hidden assistant-authored HTML comments to Telegram-native outbound actions.
+
+This is intentionally prompt-driven: the agent writes normal Markdown plus small hidden top-level blocks, and the bridge performs the transport work after `agent_end`. `telegram_voice` and `telegram_button` are not pi tools. Outbound behavior is an emergent result of the assistant prompt, configured command-template handlers, generated artifacts, and reply delivery. That avoids extra agent-side tool calls, avoids fragile parameter plumbing inside the conversation, and minimizes latency because text, voice, and buttons are planned in one standard assistant reply.
+
+This document is the local outbound adaptation of the portable [Command Template Standard](./command-templates.md).
+
+## Standard
+
+An outbound handler is selected by `type`. Assistant markup maps to handler types:
+
+| Markup            | Handler type | Telegram action                                    |
+| ----------------- | ------------ | -------------------------------------------------- |
+| `telegram_voice`  | `voice`      | Generate OGG/Opus and call `sendVoice`             |
+| `telegram_button` | Built-in     | Attach an inline keyboard button to the final text |
+
+Configured command-template handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args`, `defaults`, and `timeout` apply to all composed steps unless a step defines private values. `output` selects the primary artifact path when the handler produces a file instead of stdout text. Legacy configs may still use `pipe`, but `template: [...]` is the preferred standard shape.
+
+## Voice Handler Config
+
+`telegram.json` may define `outboundHandlers`:
+
+```json
+{
+  "outboundHandlers": [
+    {
+      "type": "voice",
+      "template": [
+        "/path/to/tts --text {text} --lang {lang=ru} --rate {rate=+30%} --write-media {mp3}",
+        "ffmpeg -y -i {mp3} -c:a libopus -b:a 32k -ar 16000 -ac 1 -vbr on {ogg}"
+      ],
+      "output": "ogg",
+      "timeout": 120000
+    }
+  ]
+}
+```
+
+If a matching voice handler fails, the bridge tries the next matching `type: "voice"` handler.
+
+## Voice Markup
+
+Assistant replies can include a hidden voice block:
+
+```md
+Full text answer stays here.
+
+<!-- telegram_voice lang=ru rate=+30%
+Text to synthesize as a Telegram voice message.
+-->
+```
+
+The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` block to `type: "voice"`, generates one file per block, and sends each file as an independent Telegram-native voice message. The opening `<!-- telegram_voice` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown.
+
+## Built-In Voice Placeholders
+
+Voice outbound handlers receive these runtime placeholders:
+
+| Placeholder | Value                                                    |
+| ----------- | -------------------------------------------------------- |
+| `{text}`    | Voice block body                                         |
+| `{lang}`    | Optional markup override such as `lang=ru`               |
+| `{rate}`    | Optional markup override such as `rate=+30%`             |
+| `{mp3}`     | Flat temp artifact path under `~/.pi/agent/tmp/telegram` |
+| `{ogg}`     | Flat temp artifact path under `~/.pi/agent/tmp/telegram` |
+
+Temp artifacts use unique flat names such as `<uuid>-voice.mp3` and `<uuid>-voice.ogg`. The bridge does not create per-handler directory trees.
+
+## Output
+
+For composed handlers, `output` selects the primary artifact after the composition completes. Omitted `output` means `"stdout"`, so the final step should print the generated OGG/Opus path. `"output": "ogg"` means the generated file path comes from `{ogg}`. A value such as `"{ogg}"` is equivalent. Composition also follows the command-template standard where each step's stdout is provided as stdin to the next step by default.
+
+For one-step `template` handlers, stdout remains the default result channel: the command should print the generated OGG/Opus path.
+
+## Buttons Markup
+
+Assistant replies can include independent button blocks. The block body is the prompt sent back to pi when the user taps the button:
+
+```md
+I can continue.
+
+<!-- telegram_button label="OK"
+Continue with the current plan.
+-->
+
+<!-- telegram_button label="Show risks"
+List the main risks first.
+-->
+```
+
+Rules:
+
+- `telegram_button label="Label"` creates one independent button row whose prompt is the block body.
+- The opening `<!-- telegram_button` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown.
+- Use one block per button; this mirrors HTML's singular element model and avoids a nested button DSL inside comments.
+- Button actions are stored in memory with short `callback_data`; Telegram never sees the full prompt in the button payload.
+
+Buttons are built in and do not need a command template because they are pure Telegram reply markup plus callback routing.
+
+## Prompt Contract
+
+The extension injects Telegram-specific system prompt guidance so agents know the fast path:
+
+- Write the full technical answer as normal Markdown.
+- Add `telegram_voice` when a Telegram-native voice message is useful; the block body is the text to synthesize and may be a companion summary, but no specific summary format is required.
+- Add `telegram_button label="..."` for quick replies that should come back as normal Telegram prompts.
+- Do not call or register TTS/text-to-OGG/Telegram transport tools for voice or buttons; the bridge owns the configured outbound-handler pipeline and delivery.
+
+This keeps the agent focused on semantics and lets the bridge handle low-latency Telegram adaptation.

package/index.ts

@@ -4,10 +4,11 @@
  */
 
 import * as Api from "./lib/api.ts";
+import * as AttachmentHandlers from "./lib/attachment-handlers.ts";
 import * as Attachments from "./lib/attachments.ts";
 import * as Commands from "./lib/commands.ts";
+import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Config from "./lib/config.ts";
-import * as Handlers from "./lib/handlers.ts";
 import * as Lifecycle from "./lib/lifecycle.ts";
 import * as Locks from "./lib/locks.ts";
 import * as Media from "./lib/media.ts";
@@ -22,6 +23,7 @@ import * as Replies from "./lib/replies.ts";
 import * as Runtime from "./lib/runtime.ts";
 import * as Routing from "./lib/routing.ts";
 import * as Setup from "./lib/setup.ts";
+import * as OutboundHandlers from "./lib/outbound-handlers.ts";
 import * as Status from "./lib/status.ts";
 
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
@@ -35,6 +37,7 @@ export default function (pi: Pi.ExtensionAPI) {
   const configStore = Config.createTelegramConfigStore();
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const activeTurnRuntime = Queue.createTelegramActiveTurnStore();
+  const buttonActionStore = OutboundHandlers.createTelegramButtonActionStore();
   const pendingModelSwitchStore =
     Model.createPendingModelSwitchStore<
       Model.ScopedTelegramModel<ActivePiModel>
@@ -85,9 +88,9 @@ export default function (pi: Pi.ExtensionAPI) {
       updateStatus,
     });
   const attachmentHandlerRuntime =
-    Handlers.createTelegramAttachmentHandlerRuntime<Pi.ExtensionContext>({
+    AttachmentHandlers.createTelegramAttachmentHandlerRuntime<Pi.ExtensionContext>({
       getHandlers: configStore.getAttachmentHandlers,
-      execCommand: piRuntime.exec,
+      execCommand: CommandTemplates.execCommandTemplate,
       getCwd: Pi.getExtensionContextCwd,
       recordRuntimeEvent: runtimeEvents.record,
     });
@@ -230,6 +233,7 @@ export default function (pi: Pi.ExtensionAPI) {
       currentModelRuntime,
       modelSwitchController,
       menuActions,
+      buttonActionStore,
       attachmentHandlerRuntime,
       updateStatus,
       dispatchNextQueuedTelegramTurn,
@@ -358,6 +362,16 @@ export default function (pi: Pi.ExtensionAPI) {
         sendTextReply,
         recordRuntimeEvent: runtimeEvents.record,
       }),
+      planOutboundReply: OutboundHandlers.createTelegramOutboundReplyPlanner(
+        buttonActionStore,
+      ),
+      sendOutboundReplyArtifacts: OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+        execCommand: CommandTemplates.execCommandTemplate,
+        sendMultipart: callMultipart,
+        sendTextReply,
+        getHandlers: configStore.getOutboundHandlers,
+        recordRuntimeEvent: runtimeEvents.record,
+      }),
       getActiveToolExecutions: bridgeRuntime.lifecycle.getActiveToolExecutions,
       setActiveToolExecutions: bridgeRuntime.lifecycle.setActiveToolExecutions,
       triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,