@llblab/pi-telegram 0.6.2 → 0.7.0

package/docs/architecture.md

@@ -2,18 +2,18 @@
 
 ## Overview
 
-`pi-telegram` is a session-local pi extension that binds one Telegram DM to one running pi session. The bridge owns four main responsibilities:
+`pi-telegram` is a session-local π extension that binds one Telegram DM to one running π session. The bridge owns four main responsibilities:
 
 - Poll Telegram updates and enforce single-user pairing
-- Translate Telegram messages and media into pi inputs
-- Stream and deliver pi responses back to Telegram
-- Manage Telegram-specific controls such as queue reactions, `/status`, `/model`, `/compact`, and `/stop`
+- Translate Telegram messages and media into π inputs
+- Stream and deliver π responses back to Telegram
+- Manage Telegram-specific controls such as queue reactions, π prompt-template commands, `/start` application menu sections, `/compact`, `/next`, `/abort`, and `/stop`
 
 ## Runtime Structure
 
 `index.ts` remains the extension entrypoint and composition root. Reusable runtime logic is split into flat domain files under `/lib` rather than into a deep local module tree.
 
-Architecture shorthand: this repository uses a `Flat Domain DAG`: cohesive bridge domains live as flat `/lib/*.ts` modules, local imports must form a directed acyclic graph, shared buckets are avoided, and `index.ts` wires live pi/Telegram ports plus session state.
+Architecture shorthand: this repository uses a `Flat Domain DAG`: cohesive bridge domains live as flat `/lib/*.ts` modules, local imports must form a directed acyclic graph, shared buckets are avoided, and `index.ts` wires live π/Telegram ports plus session state. Source-module opening comments include `Zones:` tags such as `telegram`, `pi agent`, `tui`, or `shared utils` so cross-cutting responsibility areas stay visible without folder nesting.
 
 Domain grouping rule: prefer cohesive domain files over atomizing every helper into its own file. A `shared` domain is allowed only for types or constants that genuinely span multiple bridge domains.
 
@@ -23,27 +23,29 @@ Naming rule: because the repository already scopes this codebase to Telegram, ex
 
 Current runtime areas use these ownership boundaries:
 
-| Domain                              | Owns                                                                                                                                                              |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `index.ts`                          | Single composition root for live pi/Telegram ports, session state, API-bound transport adapters, and status updates                                               |
-| `api`                               | Bot API transport shapes/helpers, retries, file download, temp-dir lifecycle, inbound limits, chat actions, lazy bot-token clients, runtime error recording       |
-| `config` / `setup`                  | Persisted bot/session pairing state, authorization, first-user pairing, token prompting, env fallback, validation, config persistence                             |
-| `locks` / `polling`                 | Singleton `locks.json` ownership, takeover/restart semantics, long-poll controller state, update offset persistence, poll-loop runtime wiring                     |
-| `updates` / `routing`               | Update classification/execution planning, paired authorization, reactions, edits, callbacks, and inbound route composition                                        |
-| `media` / `turns` / `attachment-handlers` | Text/media extraction, media-group debounce, inbound downloads, turn building/editing, image reads, attachment-handler matching/execution/fallback output    |
-| `queue`                             | Queue item contracts, lane admission/order, stores, mutations, dispatch readiness/runtime, prompt/control enqueueing, session and agent/tool lifecycle sequencing |
-| `runtime`                           | Session-local coordination primitives: counters, lifecycle flags, setup guard, abort handler, typing-loop timers, prompt-dispatch flags, agent-end reset binding  |
-| `model` / `menu` / `commands`       | Model identity/thinking levels, scoped model resolution, in-flight switching, inline status/model/thinking UI, slash commands, bot command registration           |
-| `preview` / `replies` / `rendering` | Preview lifecycle/transports, final reply delivery and reply parameters, Telegram HTML Markdown rendering, chunking, stable-preview snapshots                     |
-| `outbound-handlers`                 | Assistant-authored outbound comments, generated reply artifacts, inline-keyboard callbacks, and post-`agent_end` outbound action delivery                         |
-| `attachments`                       | `telegram_attach` registration, outbound attachment queueing, stat/limit checks, photo/document delivery classification                                           |
-| `status`                            | Status-bar/status-message rendering, queue-lane status views, redacted runtime event ring, grouped pi diagnostics                                                 |
-| `lifecycle` / `prompts` / `pi`      | pi hook registration, Telegram-specific before-agent prompt injection, centralized direct pi SDK imports and context adapters                                     |
-| `command-templates`                 | Portable shell-free command-template standard helpers, composition expansion, placeholder substitution, and executable resolution                                  |
+| Domain                                    | Owns                                                                                                                                                              |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.ts`                                | Single composition root for live π/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-model` / `menu-thinking` / `menu-status` / `menu` / `menu-queue` / `commands` | Model identity/thinking levels, scoped model resolution, in-flight switching, model-menu UI, thinking-menu UI, status-menu UI, inline application callback composition, queue-menu UI, slash commands, bot command registration |
+| `keyboard`                                | Shared Telegram inline-keyboard reply-markup structure; feature domains own callback semantics and button construction                                           |
+| `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 π diagnostics                                                  |
+| `lifecycle` / `prompts` / `prompt-templates` / `pi` | π hook registration, Telegram-specific before-agent prompt injection, π prompt-template discovery/expansion, 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:
 
 - Constants and state types live with their owning domains; do not reintroduce shared buckets such as `lib/constants.ts` or `lib/types.ts`
+- Shared Telegram inline-keyboard structure belongs to `keyboard`; application-control labels, callback data, and callback behavior stay in `menu`/`menu-model`/`menu-thinking`/`menu-status`/`menu-queue`; core queue mechanics stay in `queue`
 - Domain helpers use narrow structural projections when that avoids importing concrete wire DTOs or broader runtime objects unnecessarily
 - Preview appearance stays in `rendering`; preview transport/lifecycle stays in `preview`
 - Direct `node:*` file-operation imports stay in owning domains, not in `index.ts`
@@ -59,11 +61,11 @@ Boundary invariants:
 2. Otherwise use the first configured environment variable from the supported Telegram token list
 3. Fall back to the example placeholder when no real value exists
 
-Because `ctx.ui.input()` only exposes placeholder text, the bridge uses `ctx.ui.editor()` whenever a real default value must appear already filled in. The persisted `telegram.json` config is written with private `0600` permissions because it contains the bot token.
+Because `ctx.ui.input()` only exposes placeholder text, the bridge uses `ctx.ui.editor()` whenever a real default value must appear already filled in. The persisted `telegram.json` config is written through a private temp file plus atomic rename, then left with `0600` permissions because it contains the bot token.
 
 ## Runtime Ownership
 
-Telegram bot configuration stays in `~/.pi/agent/telegram.json`; singleton runtime ownership lives separately in `~/.pi/agent/locks.json` under `@llblab/pi-telegram`. `/telegram-connect` acquires or moves that lock before polling starts, and `/telegram-disconnect` stops polling and releases it. Session start may read the existing lock and resume polling when the lock already points at the current `pid`/`cwd`; after a full pi process restart, it may also replace a stale lock from the same `cwd` and resume polling automatically. Session start does not create new ownership from an inactive lock, a live external lock, or a stale lock from another directory. Session replacement suspends polling and ownership watchers without releasing the lock, allowing the next session-start hook in the same `pid`/`cwd` to resume from the existing explicit ownership. When a live external owner exists, `/telegram-connect` asks whether to move singleton ownership to the current pi instance. Active owners poll the lock while running through a snapshotted ownership context, so long-lived timers do not touch stale pi contexts after `/new`; they stop local polling when `locks.json` no longer points at their own `pid`/`cwd`, without deleting the new owner lock. Deleting `locks.json` resets runtime ownership without deleting Telegram configuration.
+Telegram bot configuration stays in `~/.pi/agent/telegram.json`; singleton runtime ownership lives separately in `~/.pi/agent/locks.json` under `@llblab/pi-telegram`. `/telegram-connect` acquires or moves that lock before polling starts, and `/telegram-disconnect` stops polling and releases it. Session start may read the existing lock and resume polling when the lock already points at the current `pid`/`cwd`; after a full π process restart, it may also replace a stale lock from the same `cwd` and resume polling automatically. Session start does not create new ownership from an inactive lock, a live external lock, or a stale lock from another directory. Session replacement suspends polling and ownership watchers without releasing the lock, allowing the next session-start hook in the same `pid`/`cwd` to resume from the existing explicit ownership. When a live external owner exists, `/telegram-connect` asks whether to move singleton ownership to the current π instance. Active owners poll the lock while running through a snapshotted ownership context, so long-lived timers do not touch stale π contexts after `/new`; they stop local polling when `locks.json` no longer points at their own `pid`/`cwd`, without deleting the new owner lock. Deleting `locks.json` resets runtime ownership without deleting Telegram configuration.
 
 ## Message And Queue Flow
 
@@ -80,11 +82,11 @@ Telegram bot configuration stays in `~/.pi/agent/telegram.json`; singleton runti
 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
+12. The queue dispatcher sends the turn into π only when dispatch is safe
 
 ### Queue Safety Model
 
-The bridge keeps its own Telegram queue and does not rely only on pi's internal pending-message state.
+The bridge keeps its own Telegram queue and does not rely only on π's internal pending-message state.
 
 Queued items now use two explicit dimensions:
 
@@ -95,24 +97,27 @@ 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           |
+| Immediate execution   | `/compact`, `/queue`, `/stop`, `/help`, `/start` | Does not enter the Telegram queue; `/help` opens the same menu as `/start`; `/stop` also clears queued items | N/A           |
+| Queued prompt command | `/continue`, `/template_name args` | `/continue` enqueues a Telegram-owned `continue` prompt; prompt-template commands expand the matching π template before entering the normal prompt queue | priority for `/continue`, otherwise default |
 | 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             |
+| Priority prompt queue | A waiting prompt promoted by `👍`, `⚡️`, `❤️`, or `🕊`      | `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 `⚡`.
+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 π status bar, busy labels distinguish `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`; priority prompts and priority control items are marked with `⚡`.
 
 A dispatched prompt remains in the queue until `agent_start` consumes it. That keeps the active Telegram turn bound correctly for previews, attachments, abort handling, and final reply delivery.
 
 Dispatch is gated by:
 
 - No active Telegram turn
-- No pending Telegram dispatch already sent to pi
+- No pending Telegram dispatch already sent to π
 - No compaction in progress
 - `ctx.isIdle()` being true
 - `ctx.hasPendingMessages()` being false
 
-This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Post-agent-end dispatch retries are scheduled through a session-bound deferred dispatcher that activates on session start, cancels timers on session shutdown, and skips callbacks from older generations before they touch `ExtensionContext`. Telegram `/status` and `/model` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
+This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. Post-agent-end dispatch retries are scheduled through a session-bound deferred dispatcher that activates on session start, cancels timers on session shutdown, and skips callbacks from older generations before they touch `ExtensionContext`. Telegram `/start` and hidden compatibility shortcuts `/status`, `/model`, `/thinking`, and `/queue` execute immediately; the dispatch controller still serializes any deferred control items so a queued control action must settle before the next queued action can dispatch.
+
+`/start` opens the main application menu: visible command help, compact command-only prompt-template rows when π exposes Telegram-compatible prompt-template names, status rows (`Status`, `Usage`, `Cost`, `Context`), and top-level buttons for model, thinking, and queue sections. The Queue button includes the current queued-item count. Hidden compatibility shortcuts `/help`, `/status`, `/model`, `/thinking`, and `/queue` jump directly to their corresponding menu screens. Command emoji come from the `commands` domain map so visible command descriptions and matching menu buttons share one fixed adornment source. Prompt-template commands use a fixed `🧩` marker, map π template names to Telegram-safe aliases such as `fix-tests` → `/fix_tests`, are registered in the Telegram bot command menu when the mapped command does not conflict with built-in bridge commands or hidden shortcuts, and expand before queueing because `ExtensionAPI.sendUserMessage()` intentionally bypasses π prompt-template expansion for extension-originated messages. Every submenu starts with a top Back row so navigation stays anchored near the original user message above the inline keyboard; model-menu scope and pagination controls sit directly under that top row before model choices, and tapping the pagination indicator opens a compact page picker headed by `<b>Choose a page:</b>`. `menu-model` owns model-menu state, scoped model pages, model callback planning, page-picker rendering, and model-menu rendering while `model` owns core model identity/switching semantics. `menu-thinking` owns thinking-menu text, reply markup, callback handling, and message rendering. `menu-status` owns status-menu payloads, status callback handling, and status-message rendering. `menu-queue` owns queue-menu UI only: queue items are rendered under a compact `<b>Queue:</b>` heading, top-to-bottom in dispatch order, numbered, and marked with `⚡` for priority prompts or `📎` for prompts with attachments. An empty queue renders bold message text plus the top Main menu button, not a disabled empty-state button. Selecting an item opens a submenu that displays the full queued prompt text with Back, priority toggle, and Cancel. If a callback targets an item that has already left the queue, the menu refreshes the list instead of applying a stale mutation.
 
 ### Abort Behavior
 
@@ -155,7 +160,7 @@ Telegram prompt responses use explicit delivery context to attach outbound text,
 
 Outbound files are sent only after the active Telegram turn completes, must be staged through the `telegram_attach` tool, are staged atomically per tool call, are checked against a default 50 MiB limit configurable through `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`, and use file-backed multipart blobs so large sends do not require preloading whole files into memory.
 
-Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes the block body through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, top-level `timeout` wraps the whole sequence, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text, or the button label when the body is omitted, as a normal Telegram prompt turn. This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
+Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes body text, `text="..."`, or colon shorthand through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, the default command timeout applies automatically, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn; the `telegram_button: Label` shorthand uses the same text for label and prompt, `prompt="..."` supports explicit one-line prompts, and body-form buttons use the body as the prompt. This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
 
 ## Interactive Controls
 
@@ -163,17 +168,21 @@ The bridge exposes Telegram-side session controls in addition to regular chat fo
 
 Current operator controls include:
 
-- `/status` for model, usage, cost, and context visibility, executed immediately from Telegram even while generation is active
-- Inline status buttons for model and thinking adjustments, applying idle selections immediately while still respecting busy-run restart rules; model-menu inputs are cached briefly and stored inline-menu states are pruned by TTL/LRU so old keyboards expire predictably
-- `/model` for interactive model selection, executed immediately from Telegram and supporting in-flight restart of the active Telegram-owned run on a newly selected model
-- `/compact` for Telegram-triggered pi session compaction when the bridge is idle
+- `/start` for the main application menu: command help, prompt-template commands, model, usage, cost, context visibility, and inline controls, executed immediately from Telegram even while generation is active
+- Inline application-menu buttons for model, thinking, and queue controls, applying idle selections immediately while still respecting busy-run restart rules; model-menu inputs are cached briefly and stored inline-menu states are pruned by TTL/LRU so old keyboards expire predictably
+- Hidden `/model` and `/thinking` shortcuts for opening the model and thinking sections directly while keeping settings out of the visible bot command menu
+- `/compact` for Telegram-triggered π session compaction when the bridge is idle
+- `/queue` for opening the queue section of the inline application menu; the same section is reachable from the status/main menu and supports top-anchored Back navigation, priority toggling, and cancellation
+- `/next` for dispatching the next queued turn, aborting the active run first when π is busy
+- `/continue` for enqueueing a Telegram-owned `continue` prompt, without aborting the current turn or forcing the next queued item
+- `/abort` for aborting the active Telegram-owned run while preserving queued items for manual continuation
 - `/stop` for aborting the active Telegram-owned run and clearing waiting Telegram queue items
-- `/telegram-status` for pi-side diagnostics as grouped line-by-line sections separated by blank lines: connection, polling, execution, queue, and the recent redacted runtime/API event ring. These sections include polling state, last update id, active turn source ids, pending dispatch, compaction state, active tool count, pending model-switch state, total queue depth, and queue-lane counts. The event ring records transport/API, polling/update, prompt-dispatch, control-action, typing, compaction, setup, session-lifecycle, and attachment queue/delivery failures; benign unchanged edit responses and unsupported empty draft-clear attempts are filtered out so expected preview transport noise does not obscure real failures
-- Queue reactions using `👍` and `👎` apply to waiting text, voice, file, image, and media-group turns by matching the turn's source Telegram message ids; `👎` acts as the canonical queue-removal path because ordinary Telegram DM message deletions are not exposed through the Bot API polling path this bridge uses
+- `/telegram-status` for π-side diagnostics as grouped line-by-line sections separated by blank lines: connection, polling, execution, queue, and the recent redacted runtime/API event ring. These sections include polling state, last update id, active turn source ids, pending dispatch, compaction state, active tool count, pending model-switch state, total queue depth, and queue-lane counts. The event ring records transport/API, polling/update, prompt-dispatch, control-action, typing, compaction, setup, session-lifecycle, and attachment queue/delivery failures; benign unchanged edit responses and unsupported empty draft-clear attempts are filtered out so expected preview transport noise does not obscure real failures
+- Queue reactions apply to waiting text, voice, file, image, and media-group turns by matching the turn's source Telegram message ids: `👍`, `⚡️`, `❤️`, and `🕊` promote waiting prompts, while `👎`, `👻`, `💔`, and `💩` remove waiting turns because ordinary Telegram DM message deletions are not exposed through the Bot API polling path this bridge uses
 
 ## In-Flight Model Switching
 
-When `/model` is used during an active Telegram-owned run, the bridge can emulate the interactive pi workflow of stopping, switching model, and continuing.
+When `/model` is used during an active Telegram-owned run, the bridge can emulate the interactive π workflow of stopping, switching model, and continuing.
 
 The current implementation does this by:
 
@@ -182,7 +191,7 @@ The current implementation does this by:
 3. Aborting the active Telegram turn immediately, or delaying the abort until the current tool finishes when a tool call is in flight
 4. Dispatching the continuation turn after the abort completes
 
-This behavior is intentionally limited to runs currently owned by the Telegram bridge. If pi is busy with non-Telegram work, the bridge still refuses the switch instead of hijacking unrelated session activity.
+This behavior is intentionally limited to runs currently owned by the Telegram bridge. If π is busy with non-Telegram work, the bridge still refuses the switch instead of hijacking unrelated session activity.
 
 ## Related
 

package/docs/attachment-handlers.md

@@ -1,6 +1,6 @@
 # Attachment Handlers
 
-`pi-telegram` can run ordered inbound attachment handlers after downloading files and before the Telegram turn enters the pi queue.
+`pi-telegram` can run ordered inbound attachment handlers after downloading files and before the Telegram turn enters the π queue.
 
 This document is the local adaptation of the portable [Command Template Standard](./command-templates.md).
 
@@ -13,19 +13,17 @@ This document is the local adaptation of the portable [Command Template Standard
   "attachmentHandlers": [
     {
       "type": "voice",
-      "template": "/path/to/stt1 --file {file} --lang {lang=ru}",
-      "timeout": 30000
+      "template": "/path/to/stt1 --file {file} --lang {lang=ru}"
     },
     {
       "mime": "audio/*",
-      "template": "/path/to/stt2 --file {file} --lang {lang=ru}",
-      "timeout": 30000
+      "template": "/path/to/stt2 --file {file} --lang {lang=ru}"
     }
   ]
 }
 ```
 
-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.
+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. The command-template default timeout applies automatically. Legacy configs may still use `pipe` as a local alias.
 
 ## Template Placeholders
 

package/docs/command-templates.md

@@ -1,6 +1,14 @@
 # Command Template Standard
 
-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.
+Command templates are the portable integration format for deterministic local automation.
+
+**Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
+
+**Scope:** portable command execution format — shell-free exec, composition/pipes, default timeout, critical-step branching, output artifact selection, handler-level fallback. Single JSON standard; no platform lock-in.
+
+---
+
+Extensions may choose their own config files, selectors, placeholder sources, and examples, but should preserve this core contract.
 
 ## Shape
 
@@ -22,13 +30,14 @@ There is no portable `command` field. The command is derived from `template`: af
 
 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"` |
+| 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 override in milliseconds; default `30000` (30s)                 |
+| `output`   | Optional result selector; default `"stdout"`, or a "runtime value", e.g. `"ogg"`           |
+| `critical` | Optional boolean; default `false`. When `true`, failure aborts the entire root composition |
 
 Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
 
@@ -113,7 +122,7 @@ Composition rules:
 - 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
+- Default `30000` (30s) timeout applies automatically; configure `timeout` only for exceptional long-running commands
 - 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
 
@@ -136,6 +145,41 @@ Composition rules:
 
 Legacy local schemas may accept `pipe` as an alias, but the portable standard is `template: [...]`.
 
+## Fail-Open Default Policy
+
+By default, composition continues on failure: the failed step is logged and the next step executes. This is analogous to `make -k` — the user sees all failures at once and decides what to fix.
+
+## Critical Steps
+
+Set `critical: true` on any leaf to abort the entire root composition on failure. One `critical` leaf can halt the whole pipeline.
+
+```json
+{
+  "template": [
+    { "template": "cargo build" },
+    { "template": "cargo fmt --check" },
+    { "template": "cargo test", "critical": true }
+  ]
+}
+```
+
+`build` / `fmt` failures are logged, execution continues. `test` failure aborts the root composition immediately.
+
+A `critical` leaf in a nested composition still aborts the outermost root `template: [...]`. There is no per-branch scoping in the current standard.
+
+## Progressive Disclosure
+
+The standard uses a single `template` field that grows with the user's needs:
+
+```text
+string           → leaf command
+string[]         → sequential composition
+{ template }     → leaf with defaults
+{ template, critical, output } → full leaf
+```
+
+Start with a string. Add composition when needed. Add critical when safety matters. Same contract, growing capability, no dead weight.
+
 ## Tool Boundary
 
 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.

package/docs/locks.md

@@ -1,5 +1,9 @@
 # Extension Locks Standard
 
+**Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
+
+---
+
 `locks.json` is a shared registry for singleton pi extensions.
 
 Path:

package/docs/outbound-handlers.md

@@ -2,7 +2,7 @@
 
 `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 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 π 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).
 
@@ -15,7 +15,7 @@ An outbound handler is selected by `type`. Assistant markup maps to handler type
 | `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.
+Configured command-template handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. `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
 
@@ -30,8 +30,7 @@ Configured command-template handlers provide `template`. A string is one command
         "/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
+      "output": "ogg"
     }
   ]
 }
@@ -49,9 +48,13 @@ Full text answer stays here.
 <!-- telegram_voice lang=ru rate=+30%
 Text to synthesize as a Telegram voice message.
 -->
+
+<!-- telegram_voice lang=ru rate=+30% text="Short spoken companion summary." -->
+
+<!-- telegram_voice: Short spoken companion summary. -->
 ```
 
-The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` block to `type: "voice"`, generates one file per block, and sends each file as an independent Telegram-native voice message. The opening `<!-- telegram_voice` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown.
+The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` block to `type: "voice"`, generates one file per block, and sends each file as an independent Telegram-native voice message. The opening `<!-- telegram_voice` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown. Body-form comments leave the opening line unclosed until the body-ending `-->`; closed heads can use `text="..."` for explicit one-line spoken text.
 
 ## Built-In Voice Placeholders
 
@@ -59,7 +62,7 @@ Voice outbound handlers receive these runtime placeholders:
 
 | Placeholder | Value                                                    |
 | ----------- | -------------------------------------------------------- |
-| `{text}`    | Voice block body                                         |
+| `{text}`    | Voice text from body, `text="..."`, or colon shorthand |
 | `{lang}`    | Optional markup override such as `lang=ru`               |
 | `{rate}`    | Optional markup override such as `rate=+30%`             |
 | `{mp3}`     | Flat temp artifact path under `~/.pi/agent/tmp/telegram` |
@@ -73,28 +76,31 @@ For composed handlers, `output` selects the primary artifact after the compositi
 
 For one-step `template` handlers, stdout remains the default result channel: the command should print the generated OGG/Opus path.
 
+**Critical steps:** voice synthesis is a multi-step pipeline (TTS → ffmpeg → OGG). The ffmpeg conversion step is inherently critical — if it fails, the voice output is invalid. Mark it as `"critical": true` when a composed handler must abort after conversion failure instead of continuing to later non-critical steps. Keep the fallback chain (Mistral TTS → Groq TTS) as the safety net for persistent outages. See [Command Template Standard](./command-templates.md) for semantics.
+
 ## Buttons Markup
 
-Assistant replies can include independent button blocks. The block body is the prompt sent back to pi when the user taps the button; omit the body when the prompt should equal the label:
+Assistant replies can include independent button blocks. The prompt is sent back to π when the user taps the button; use the colon shorthand when the prompt should equal the label, `prompt="..."` for one-line prompts, or the body form for multiline prompts:
 
 ```md
 I can continue.
 
-<!-- telegram_button label="OK"
-Continue with the current plan.
--->
+<!-- telegram_button label=Continue prompt="Continue with the current plan." -->
 
 <!-- telegram_button label="Show risks"
 List the main risks first.
 -->
 
-<!-- telegram_button label="Done" -->
+<!-- telegram_button: Done -->
 ```
 
 Rules:
 
-- `telegram_button label="Label"` creates one independent button row whose prompt is the block body, or the label itself when the body is omitted.
+- `telegram_button: Label` creates one independent label-only button row whose prompt equals the label.
+- `telegram_button label="Label" prompt="Prompt"` creates one independent button row whose prompt is the `prompt` attribute.
+- `telegram_button label="Label"` with a body creates one independent button row whose prompt is the block body.
 - The opening `<!-- telegram_button` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown.
+- Keep the canonical body form as `<!-- telegram_button label="Label"` + body + `-->`; closed heads must use `prompt="..."` or the colon shorthand to create a button.
 - Use one block per button; this mirrors HTML's singular element model and avoids a nested button DSL inside comments.
 - Button actions are stored in memory with short `callback_data`; Telegram never sees the full prompt in the button payload.
 
@@ -105,8 +111,8 @@ Buttons are built in and do not need a command template because they are pure Te
 The extension injects Telegram-specific system prompt guidance so agents know the fast path:
 
 - Write the full technical answer as normal Markdown.
-- Add `telegram_voice` when a Telegram-native voice message is useful; the block body is the text to synthesize and may be a companion summary, but no specific summary format is required.
-- Add `telegram_button label="..."` for quick replies that should come back as normal Telegram prompts.
+- Add `telegram_voice` when a Telegram-native voice message is useful; use body text, `text="..."`, or colon shorthand for the text to synthesize. A companion summary is optional, no specific summary format is required.
+- Add `telegram_button: ...` when label equals prompt, `telegram_button label="..." prompt="..."` for one-line prompts, or `telegram_button label="..."` with a body for multiline prompts. If the reply contains only button/voice comment blocks, add a short visible marker (for example `Choose one:`) before them so Telegram always has a visible parent message for attachment.
 - Do not call or register TTS/text-to-OGG/Telegram transport tools for voice or buttons; the bridge owns the configured outbound-handler pipeline and delivery.
 
 This keeps the agent focused on semantics and lets the bridge handle low-latency Telegram adaptation.