@llblab/pi-telegram 0.4.0 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@ This repository is an actively maintained fork of [`badlogic/pi-telegram`](https
 
 ## Key Features
 
-- **Priority Command Queue**: Control commands such as `/status` and `/model` use a high-priority control queue, so they do not get stuck behind normal queued prompts when pi is busy.
+- **Immediate Telegram Controls**: `/status` and `/model` respond immediately from Telegram, while model-switch continuation turns still use the control lane when a restart needs to resume safely.
 - **Interactive UI**: Manage your session directly from Telegram. Inline buttons allow you to switch models and adjust reasoning (thinking) levels on the fly.
 - **In-flight Model Switching**: Change the active model mid-generation. The agent gracefully pauses, applies the new model, and restarts its response without losing context.
 - **Smart Message Queue**: Messages sent while the agent is busy are queued and previewed in the pi status bar, and queued turns can be reprioritized or removed with Telegram reactions.
@@ -84,7 +84,7 @@ Use these inside the Telegram DM with your bot:
 - **`/compact`**: Start session compaction (only works when the session is idle).
 - **`/stop`**: Abort the active run.
 
-Telegram command admission is explicit: `/compact`, `/stop`, `/help`, and `/start` execute immediately; `/status` and `/model` enter the high-priority control lane so they can run before normal queued prompts when pi becomes safe to dispatch.
+Telegram command admission is explicit: `/compact`, `/stop`, `/help`, `/start`, `/status`, and `/model` execute immediately. Synthetic model-switch continuation turns still enter the high-priority control lane so they can resume before normal queued prompts when pi becomes safe to dispatch.
 
 ### Pi Commands
 
@@ -100,32 +100,41 @@ Run these inside pi, not Telegram:
 - If you send more Telegram messages while pi is busy, they enter the default prompt queue and are processed in order.
 - `👍` moves a waiting prompt into the priority prompt queue, behind control actions but ahead of default prompts. Removing `👍` sends it back to its normal queue position, and adding `👍` again gives it a fresh priority position.
 - `👎` 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.
-- For media groups, a reaction on any message in the group applies to the whole queued turn.
+- 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.
 - 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.
 
 ### Inbound Attachment Handlers
 
-`telegram.json` can define `attachmentHandlers` for common preprocessing such as voice transcription. The first matching handler runs after download and before the Telegram turn enters the pi queue.
+`telegram.json` can define ordered `attachmentHandlers` for common preprocessing such as voice transcription. Matching handlers run after download and before the Telegram turn enters the pi queue. If a matching handler fails, the next matching handler is tried as a fallback.
 
 ```json
 {
   "attachmentHandlers": [
     {
-      "mime": "audio/*",
-      "command": "/home/me/bin/transcribe {filename} ru"
+      "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"
+      }
     },
     {
-      "type": "voice",
-      "tool": "transcribe_groq",
-      "args": { "lang": "ru" }
+      "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"
+      }
     }
   ]
 }
 ```
 
-Matching supports `mime`, `type`, or `match`; wildcards like `audio/*` are accepted. Command placeholders are substituted as argv, not shell text: `{filename}` and `{path}` are the downloaded file path, `{basename}` is the display filename, `{mime}` is the MIME type, and `{type}` is the Telegram attachment type. Tool handlers invoke a locally available tool by name, for example `transcribe_groq`; how that tool is provided is outside pi-telegram. Local attachments stay in the prompt under `[attachments] <directory>` with relative file entries; successful handler stdout is added under `[outputs]`; failed or empty handlers simply produce no output block.
+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).
 
 ### Requesting Files
 
@@ -139,10 +148,10 @@ Rich previews are sent through editable messages because Telegram drafts are tex
 
 ## Status bar
 
-The pi status bar shows queued Telegram turns as compact previews, for example:
+The pi status bar shows the current bridge state plus queued Telegram turns as compact previews. Busy labels distinguish states such as `active`, `dispatching`, `queued`, `tool running`, `model`, and `compacting`.
 
 ```text
-+3: [⬆ write a shell script…, summarize this image…, 📎 2 attachments]
+telegram queued +3: [⬆ write a shell script…, summarize this image…, 📎 2 attachments]
 ```
 
 ## Notes

package/docs/README.md

@@ -5,4 +5,6 @@ Living index of project documentation in `/docs`.
 ## Documents
 
 - [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
 - [locks.md](./locks.md) — Shared `locks.json` standard for singleton extension ownership

package/docs/architecture.md

@@ -21,37 +21,33 @@ Interface consistency rule: when two modules mean the same runtime entity, they
 
 Naming rule: because the repository already scopes this codebase to Telegram, extracted module and test filenames use bare domain names such as `api.ts`, `queue.ts`, `updates.ts`, and `queue.test.ts` rather than repeating `telegram-*` in every filename.
 
-Current runtime areas include:
-
-- Telegram Bot API concrete transport shapes live with Telegram API helpers in `/lib/api.ts`, while persisted bot/session pairing state lives in `/lib/config.ts`; domain-owned runtime state types stay with their owners, such as queued/active turn state in `/lib/queue.ts` and preview state in `/lib/preview.ts`, while domain helpers prefer local structural `*Like` contracts instead of importing concrete wire DTOs
-- Direct pi SDK imports are centralized in `/lib/pi.ts`, which exposes concrete pi SDK type exports, bound extension API runtime ports, and narrow bridge-facing helpers such as settings-manager creation plus context model/idle/pending-message/compaction adapters; `index.ts` uses this adapter namespace instead of importing `@mariozechner/pi-coding-agent` directly
-- Session-local runtime primitives such as queue/control/priority ordering counters, lifecycle/dispatch flags, setup guard state, abort-handler storage/binding, typing-loop timer lifecycle, typing-loop starter binding, prompt-dispatch lifecycle/runtime adapters, and agent-end reset sequencing in `/lib/runtime.ts`; the runtime domain's essence is mutable cross-domain session coordination rather than business behavior. It exposes a grouped bridge runtime facade with named queue/lifecycle/setup/abort/typing ports that bind those primitives to one session state while remaining a cohesive state/runtime boundary, and `index.ts` still wires live Telegram API calls and status updates into those helpers. Preview-specific state, draft-support detection, and draft-id allocation live in `/lib/preview.ts`.
-- Constants live in their owning domains instead of a shared constants module: API paths/inbound limits and inbound file-size env parsing in `/lib/api.ts`, outbound attachment limits and outbound attachment-size env parsing in `/lib/attachments.ts`, media-group debounce in `/lib/media.ts`, attachment-handler timeout and local tool lookup defaults in `/lib/handlers.ts`, menu cache/state bounds in `/lib/menu.ts`, preview throttle/draft bounds in `/lib/preview.ts`, typing cadence in `/lib/runtime.ts`, diagnostic ring limits in `/lib/status.ts`, Telegram prompt prefix in `/lib/turns.ts`, and system-prompt guidance in `/lib/registration.ts`.
-- Queueing, narrow Telegram prompt content contracts, queue-store contracts/state helpers, active-turn state helpers, dispatch-readiness adapters, queue append/mutation runtime/controller adapters, control enqueue controllers, queue dispatch readiness/controller/runtime adapters, prompt enqueue/history planning/runtime/controllers, queue-runtime, session state appliers plus lifecycle/runtime sequencing, session start/shutdown sequencing plus hook binding, agent-start/agent-end lifecycle handling plus hook/runtime binding, and tool lifecycle handling plus tool-execution hook/runtime binding in `/lib/queue.ts`
-- Model identity/thinking-level contracts, scoped model-pattern parsing/resolution/sorting, current-model store/update/runtime helpers, in-flight model-switch state helpers, restart eligibility, delayed abort decisions, Telegram-prefix defaulted continuation prompt construction, continuation queue adapters, and model-switch controller/runtime binding over queue-owned turns in `/lib/model.ts`
-- Preview transport-selection, assistant-message preview lifecycle hook binding/handling, preview-finalization, preview controller state/reset helpers, preview Bot API message/rendered-chunk transport adapters, preview-controller/assistant-preview runtime binding, reply-metadata defaulting through the replies-domain helper, and preview-runtime helpers in `/lib/preview.ts`
-- Reply-transport, rendered-message delivery runtime/binding, structural assistant-message extraction, reply-parameter construction over API-owned transport shapes, and plain/Markdown final-reply helpers in `/lib/replies.ts`
-- Preview appearance and snapshot derivation stay in `/lib/rendering.ts`, while `/lib/preview.ts` owns transport and lifecycle decisions, so richer preview strategies can evolve without entangling Markdown formatting with Telegram delivery state
-- Polling request, start/stop controller state orchestration, polling activity readers, stop-condition, structural config contract, long-poll loop helpers, and poll-loop/controller runtime wiring over Telegram transport ports in `/lib/polling.ts`
-- Telegram persisted config shape, config-path defaults, config file read/write helpers, mutable config-store accessors, single-user authorization, and first-user pairing side effects/runtime adapters in `/lib/config.ts`
-- Telegram API helpers, concrete Bot API transport shapes including reply parameters and send/edit message bodies, typed/default Bot API runtime helpers, bot identity fetch transport, chat-action sender adapters/runtime-bound typing action, lazy bot-token client wrappers, API runtime error-recording wrappers, temp paths, inbound file-size limits, and runtime-bound temp-directory preparation/default cleanup in `/lib/api.ts`
-- Telegram turn-building helpers, runtime turn-builder wiring over media download ports and media-owned downloaded-file metadata contracts, inbound attachment handler processing, queued-prompt edit runtime binding, and Node-backed image-file reads for pi image inputs in `/lib/turns.ts`
-- Telegram media/text extraction, file-info normalization, downloaded-message-file metadata contracts, inbound file download assembly, media-group debounce helpers, media-group controller state, and media-group-aware authorized-message dispatch adapter wiring in `/lib/media.ts`
-- Telegram inbound attachment handler matching, command placeholder substitution, local tool invocation, handler-output collection, and quiet failure handling in `/lib/handlers.ts`
-- Telegram slash-command parsing, command-message target helpers/adapters, command control-enqueue adapters/runtime binding, command-action routing, command-handler/target-runtime and command-or-prompt dispatch binding, command runtime port orchestration, shared command-runtime reply/status/control adapter closures, stop/compact/status/model/help command side-effect branching, bound Bot API command registration, and Bot API command metadata helpers in `/lib/commands.ts`
-- Telegram updates extraction, authorization classification, execution-planning, authorized reaction priority/removal handling, direct execute-from-update routing, and runtime helpers in `/lib/updates.ts`
-- Inbound route composition across paired update execution, callback menus, command-or-prompt dispatch, media grouping, prompt enqueueing, queued edits, and attachment-handler turn building in `/lib/routing.ts`
-- Telegram attachment queueing, narrow structural attachment turn targets, queued-attachment sender runtime binding, delivery helpers, Node-backed file stat checks, outbound photo-vs-document classification, and outbound attachment limits/env parsing in `/lib/attachments.ts`
-- Telegram tool, command, before-agent prompt, and lifecycle-hook registration helpers in `/lib/registration.ts`
-- Setup/token prompt, environment fallback, guarded setup runtime adapter wiring, structural setup config contract, token validation, config persistence orchestration, and setup notification helpers in `/lib/setup.ts`
-- Markdown block scanning/rendering, inline-token/style rendering, text-piece rendering, stable-preview block scanning, final rendered-block chunk balancing, preview-snapshot derivation, HTML escaping, raw HTML tag-preserving chunking, and Telegram message rendering helpers in `/lib/rendering.ts`
-- Status-bar rendering/runtime adapters, bridge status state adapters, status-message rendering and status-HTML binding, structural queue-lane status view contracts, structured redacted runtime-event recording, recent-event recorder state, recent-event line formatting, and grouped pi-side diagnostics helpers in `/lib/status.ts`
-- Menu settings/model-registry access through structural ports, menu-state construction, menu runtime state/cache controller, menu-state storage pruning/refresh helpers, command open-flow branching, action runtime/state-builder adapters, menu callback handler adapters, stored callback entry/runtime routing, model-menu input-cache/state-building resolution, pure menu-page derivation, pure menu render-payload builders, menu-message runtime, callback parsing, callback mutation helpers, full model-callback planning and execution, interface-polished callback effect ports, status-thinking callback handling, and UI helpers in `/lib/menu.ts`
-- Telegram API-bound transport adapters and top-level runtime registration stay in `index.ts`; broader inbound event-side orchestration lives in `/lib/routing.ts`; direct Node file-operation imports stay in the owning domains rather than the entrypoint
-- Remaining `index.ts` wiring is intentionally cross-domain adapter code that closes over live extension state, pi callbacks, Telegram API ports, and status updates; keep repeated wiring DRY through small local adapter helpers or owning-domain contracts when that reduces duplication without obscuring live state, and extract more only when a boundary can move cohesive behavior into an owning domain instead of relocating one-off closures
-- Additional domains can be extracted into `/lib/*.ts` as the bridge grows, while keeping `index.ts` as the single entrypoint
-- `index.ts` uses namespace imports for local bridge domains so orchestration reads as domain-scoped calls such as `Queue.*`, `Turns.*`, and `Rendering.*` instead of long flat import lists
-- Mirrored domain regression coverage lives in `/tests/*.test.ts` using the same bare domain naming scheme, and architecture-invariant coverage in `/tests/invariants.test.ts` checks that the local `index.ts` plus `/lib/*.ts` import graph stays acyclic, shared bucket domains such as `lib/constants.ts` or `lib/types.ts` are not reintroduced, empty interface-extension shells stay collapsed into clearer type aliases, direct pi SDK imports stay centralized, `index.ts` source code stays free of direct Node runtime imports, local helper declarations, local arrow adapters, direct `process.env`, and direct `pi.*` receiver access, `/lib/runtime.ts` stays free of local domain imports, structural leaf domains stay free of local nominal imports, the menu domain stays on structural ports without re-exporting model, API transport stays decoupled from persisted config defaults, structural update/media domains stay decoupled from concrete API transport shapes, and attachment delivery stays decoupled from queue/inbound media/API helpers
+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 |
+
+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`
+- 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`
+- `index.ts` uses namespace imports for local bridge domains so orchestration reads as `Queue.*`, `Turns.*`, and `Rendering.*`
+- Architecture-invariant tests guard the acyclic import graph, pi SDK centralization, entrypoint purity, runtime-domain isolation, structural leaf-domain isolation, menu/model boundaries, API/config separation, media/update/API separation, and attachment boundary isolation
+- Mirrored domain regression coverage lives in `/tests/*.test.ts`; test helpers stay local to the mirrored suite by default, and shared fixture folders are justified only by reuse across multiple domain suites
 
 ## Configuration UX
 
@@ -76,11 +72,12 @@ Telegram bot configuration stays in `~/.pi/agent/telegram.json`; singleton runti
 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 handlers receive safe argv substitution for `{filename}`/`{path}`/`{basename}`/`{mime}`/`{type}`, and tool handlers invoke locally available tools by name
-7. 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 or empty handlers simply omit handler output while keeping the attachment entry
-8. A `PendingTelegramTurn` is created and queued locally
-9. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
-10. The queue dispatcher sends the turn into pi only when dispatch is safe
+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
 
 ### Queue Safety Model
 
@@ -96,11 +93,11 @@ Admission contract:
 | Admission             | Examples                                             | Queue shape                                                          | Dispatch rank |
 | --------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | ------------- |
 | Immediate execution   | `/compact`, `/stop`, `/help`, `/start`               | Does not enter the Telegram queue                                    | N/A           |
-| Control queue         | `/status`, `/model`, model-switch continuation turns | `queueLane: control`; accepts control items and continuation prompts | 0             |
+| 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             |
 
-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 queue preview, priority prompts are marked with `⬆` while control items keep their own control-specific summary 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 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 `⚡`.
 
 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.
 
@@ -112,7 +109,7 @@ Dispatch is gated by:
 - `ctx.isIdle()` being true
 - `ctx.hasPendingMessages()` being false
 
-This prevents queue races around rapid follow-ups, `/compact`, and mixed local plus Telegram activity. The dispatch controller also serializes asynchronous control items, so a queued `/status` or `/model` 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. 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.
 
 ### Abort Behavior
 
@@ -161,13 +158,13 @@ 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, queued as a high-priority control item when needed
+- `/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, queued as a high-priority control item when needed and supporting in-flight restart of the active Telegram-owned run on a newly selected model
+- `/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
 - `/stop` for aborting the active Telegram-owned run
 - `/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 `👎`, with `👎` acting as the canonical queue-removal path because ordinary Telegram DM message deletions are not exposed through the Bot API polling path this bridge uses
+- 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
 
 ## In-Flight Model Switching
 

package/docs/attachment-handlers.md

@@ -0,0 +1,60 @@
+# Attachment Handlers
+
+`pi-telegram` can run ordered inbound attachment handlers after downloading files and before the Telegram turn enters the pi queue.
+
+This document is the local adaptation of the portable [Command Template Standard](./command-templates.md).
+
+## Config Shape
+
+`telegram.json` may define `attachmentHandlers`:
+
+```json
+{
+  "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"
+      }
+    },
+    {
+      "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"
+      }
+    }
+  ]
+}
+```
+
+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.
+
+## Template Placeholders
+
+Attachment handlers support these built-in placeholders:
+
+| Placeholder | Value                                                            |
+| ----------- | ---------------------------------------------------------------- |
+| `{file}`    | Full local path to the downloaded file                           |
+| `{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"`.
+
+If a template has no `{file}` placeholder, the downloaded file path is appended as the last command arg.
+
+## Ordered Fallbacks
+
+A handler list is ordered. For each attachment, matching handlers run in list order and stop after the first successful handler.
+
+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.

package/docs/command-templates.md

@@ -0,0 +1,75 @@
+# Command Template Standard
+
+Command templates are the stable integration format for deterministic local automation.
+
+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.
+
+## Definition
+
+A command template is a single command-line string with named placeholders:
+
+```text
+~/bin/transcribe {file} {lang}
+```
+
+## Execution Contract
+
+The runtime must:
+
+1. Split the template into shell-like words, honoring 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
+
+Implementations may expand `~` in the command position and may resolve relative command paths against the caller cwd.
+
+## Quoting Model
+
+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:
+
+```text
+template="echo {text}"
+text="hello world"
+args=["hello world"]
+```
+
+A placeholder can also be embedded inside one word:
+
+```text
+template="tool --file={file}"
+file="/tmp/a b.ogg"
+args=["--file=/tmp/a b.ogg"]
+```
+
+Use quotes only for literal template words that should contain spaces before placeholder substitution:
+
+```text
+template="echo 'literal words' {text}"
+```
+
+## Storage Vocabulary
+
+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.
+
+Common field names:
+
+| 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                                         |
+
+Config file locations, selectors, labels, descriptions, and surrounding registry shapes belong to each extension's local adaptation.
+
+## Tool Boundary
+
+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.
+
+Until such an API exists, extensions should prefer command templates for deterministic local automation.
+
+## Compatibility
+
+Consumers should share this template contract, not private registry fields or implementation details from any specific extension.

package/index.ts

@@ -5,8 +5,10 @@
 
 import * as Api from "./lib/api.ts";
 import * as Attachments from "./lib/attachments.ts";
+import * as Commands from "./lib/commands.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";
 import * as Menu from "./lib/menu.ts";
@@ -14,8 +16,8 @@ import * as Model from "./lib/model.ts";
 import * as Pi from "./lib/pi.ts";
 import * as Polling from "./lib/polling.ts";
 import * as Preview from "./lib/preview.ts";
+import * as Prompts from "./lib/prompts.ts";
 import * as Queue from "./lib/queue.ts";
-import * as Registration from "./lib/registration.ts";
 import * as Replies from "./lib/replies.ts";
 import * as Runtime from "./lib/runtime.ts";
 import * as Routing from "./lib/routing.ts";
@@ -255,7 +257,7 @@ export default function (pi: Pi.ExtensionAPI) {
     updateStatus,
     recordRuntimeEvent: runtimeEvents.record,
   });
-  const sessionLifecycleRuntime = Registration.appendTelegramLifecycleHooks(
+  const sessionLifecycleRuntime = Lifecycle.appendTelegramLifecycleHooks(
     Queue.createTelegramSessionLifecycleRuntime<
       Pi.ExtensionContext,
       RuntimeTelegramQueueItem,
@@ -282,14 +284,14 @@ export default function (pi: Pi.ExtensionAPI) {
     { onSessionStart: lockedPollingRuntime.onSessionStart },
   );
 
-  // --- Extension Registration ---
+  // --- Extension API Bindings ---
 
-  Registration.registerTelegramAttachmentTool(pi, {
+  Attachments.registerTelegramAttachmentTool(pi, {
     getActiveTurn: activeTurnRuntime.get,
     recordRuntimeEvent: runtimeEvents.record,
   });
 
-  Registration.registerTelegramCommands(pi, {
+  Commands.registerTelegramBridgeCommands(pi, {
     promptForConfig: Setup.createTelegramSetupPromptRuntime({
       getConfig: configStore.get,
       setConfig: configStore.set,
@@ -310,9 +312,9 @@ export default function (pi: Pi.ExtensionAPI) {
 
   // --- Lifecycle Hooks ---
 
-  Registration.registerTelegramLifecycleHooks(pi, {
+  Lifecycle.registerTelegramLifecycleHooks(pi, {
     ...sessionLifecycleRuntime,
-    onBeforeAgentStart: Registration.createTelegramBeforeAgentStartHook(),
+    onBeforeAgentStart: Prompts.createTelegramBeforeAgentStartHook(),
     onModelSelect: currentModelRuntime.onModelSelect,
     ...Queue.createTelegramAgentLifecycleHooks<
       Queue.PendingTelegramTurn,

package/lib/attachments.ts

@@ -1,13 +1,18 @@
 /**
  * Telegram attachment domain helpers
- * Owns attachment queueing and attachment delivery so Telegram file output stays in one domain module
+ * Owns telegram_attach registration, attachment queueing, and attachment delivery so Telegram file output stays in one domain module
  */
 
 import { stat } from "node:fs/promises";
 import { basename } from "node:path";
 
+import { Type } from "@sinclair/typebox";
+
+import type { ExtensionAPI } from "./pi.ts";
 import { buildTelegramMultipartReplyParameters } from "./replies.ts";
 
+const MAX_ATTACHMENTS_PER_TURN = 10;
+
 export const TELEGRAM_OUTBOUND_ATTACHMENT_DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
 
 export function getTelegramAttachmentByteLimitFromEnv(
@@ -35,6 +40,21 @@ export interface TelegramAttachmentToolResult {
   details: { paths: string[] };
 }
 
+export interface TelegramAttachmentRuntimeEventRecorderPort {
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
+export interface TelegramAttachmentToolRegistrationDeps extends TelegramAttachmentRuntimeEventRecorderPort {
+  maxAttachmentsPerTurn?: number;
+  maxAttachmentSizeBytes?: number;
+  getActiveTurn: () => TelegramAttachmentQueueTargetView | undefined;
+  statPath?: (path: string) => Promise<{ isFile(): boolean; size?: number }>;
+}
+
 export interface TelegramQueuedAttachmentView {
   path: string;
   fileName: string;
@@ -69,6 +89,54 @@ function formatTelegramAttachmentSizeLimitError(
   return path ? `${message}: ${path}` : message;
 }
 
+function formatTelegramAttachmentToolResultText(count: number): string {
+  // Pi's compact tool rows need an empty first line to visually separate header and result
+  return ["", `Queued ${count} Telegram attachment(s).`].join("\n");
+}
+
+export function registerTelegramAttachmentTool(
+  pi: ExtensionAPI,
+  deps: TelegramAttachmentToolRegistrationDeps,
+): void {
+  const maxAttachmentsPerTurn =
+    deps.maxAttachmentsPerTurn ?? MAX_ATTACHMENTS_PER_TURN;
+  const maxAttachmentSizeBytes =
+    deps.maxAttachmentSizeBytes ?? TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES;
+  pi.registerTool({
+    name: "telegram_attach",
+    label: "Telegram Attach",
+    description:
+      "Queue one or more local files to be sent with the next Telegram reply.",
+    promptSnippet: "Queue local files to be sent with the next Telegram reply.",
+    promptGuidelines: [
+      "When handling a [telegram] message and the user asked for a file or generated artifact, call telegram_attach with the local path instead of only mentioning the path in text.",
+    ],
+    parameters: Type.Object({
+      paths: Type.Array(
+        Type.String({ description: "Local file path to attach" }),
+        { minItems: 1, maxItems: maxAttachmentsPerTurn },
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      try {
+        return await queueTelegramAttachments({
+          activeTurn: deps.getActiveTurn(),
+          paths: params.paths,
+          maxAttachmentsPerTurn,
+          maxAttachmentSizeBytes,
+          statPath: deps.statPath,
+        });
+      } catch (error) {
+        deps.recordRuntimeEvent?.("attachment", error, {
+          phase: "queue",
+          count: params.paths.length,
+        });
+        throw error;
+      }
+    },
+  });
+}
+
 export interface TelegramQueuedAttachmentDeliveryDeps {
   sendMultipart: (
     method: string,
@@ -141,7 +209,7 @@ export async function queueTelegramAttachments(options: {
     content: [
       {
         type: "text",
-        text: `Queued ${added.length} Telegram attachment(s).`,
+        text: formatTelegramAttachmentToolResultText(added.length),
       },
     ],
     details: { paths: added },