@llblab/pi-telegram 0.3.0 → 0.4.0

package/README.md

@@ -18,7 +18,7 @@ This repository is an actively maintained fork of [`badlogic/pi-telegram`](https
 - **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.
 - **Mobile-Optimized Rendering**: Tables and lists are formatted for narrow screens, table padding accounts for emoji grapheme and wide Unicode display width, and Telegram-originated runs prompt the assistant to prefer narrow table columns for phone readability. Markdown is correctly parsed and split to fit Telegram's limits without breaking HTML structures or code blocks, block spacing stays faithful to the original Markdown with readable heading separation, supported absolute links stay clickable, and unsupported link forms degrade safely.
-- **File Handling & Attachments**: Send images and files to the agent, or ask it to generate and return artifacts. Inbound downloads and outbound attachments are size-limited by default, and outbound files are delivered automatically via the `telegram_attach` tool.
+- **File Handling & Attachments**: Send images and files to the agent, transcribe or transform inbound files with configured attachment handlers, or ask pi to generate and return artifacts. Inbound downloads and outbound attachments are size-limited by default, and outbound files are delivered automatically via the `telegram_attach` tool.
 - **Streaming Responses**: Closed Markdown blocks stream back as rich Telegram HTML while pi is generating, and the still-growing tail stays readable until the final fully rendered reply lands.
 
 ## Install
@@ -60,7 +60,7 @@ Paste your bot token when prompted. If a bot token is already saved in `~/.pi/ag
 /telegram-connect
 ```
 
-The bridge is session-local. Only one pi session should be connected to the bot at a time.
+The bridge is session-local: only one pi instance polls Telegram at a time. `/telegram-connect` records polling ownership in `~/.pi/agent/locks.json`; live ownership moves require confirmation, while `/new` and same-`cwd` process restarts resume automatically.
 
 ### 4. Pair your account from Telegram
 
@@ -92,8 +92,8 @@ Run these inside pi, not Telegram:
 
 - **`/telegram-setup`**: Configure or update the Telegram bot token.
 - **`/telegram-status`**: Check bridge status, connection, polling, execution, queue, and recent redacted runtime/API failure events.
-- **`/telegram-connect`**: Start polling Telegram updates in the current pi session.
-- **`/telegram-disconnect`**: Stop polling in the current pi session.
+- **`/telegram-connect`**: Start polling Telegram updates in the current pi session, acquire the singleton lock, or interactively move ownership here from another live instance.
+- **`/telegram-disconnect`**: Stop polling in the current pi session and release the singleton lock.
 
 ### Queue, Reactions, and Media
 
@@ -102,9 +102,31 @@ 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.
 - 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`, local file paths are included in the prompt, 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`.
+- 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.
+
+```json
+{
+  "attachmentHandlers": [
+    {
+      "mime": "audio/*",
+      "command": "/home/me/bin/transcribe {filename} ru"
+    },
+    {
+      "type": "voice",
+      "tool": "transcribe_groq",
+      "args": { "lang": "ru" }
+    }
+  ]
+}
+```
+
+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.
+
 ### 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`.

package/docs/README.md

@@ -4,6 +4,5 @@ Living index of project documentation in `/docs`.
 
 ## Documents
 
-| Document | Description |
-| --- | --- |
-| [architecture.md](./architecture.md) | Overview of the Telegram bridge runtime, queueing model, rendering pipeline, and interactive controls |
+- [architecture.md](./architecture.md) — Overview of the Telegram bridge runtime, queueing model, rendering pipeline, and interactive controls
+- [locks.md](./locks.md) — Shared `locks.json` standard for singleton extension ownership

package/docs/architecture.md

@@ -26,7 +26,7 @@ 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`, 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`.
+- 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`
@@ -35,17 +35,19 @@ Current runtime areas include:
 - 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, queued-prompt edit runtime binding, and Node-backed image-file reads for pi image inputs in `/lib/turns.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, paired update-runtime binding, flow, execution-planning, authorized reaction priority/removal handling, direct execute-from-update routing, update runtime adapters over queue/media/menu ports, and runtime helpers in `/lib/updates.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 broader event-side orchestration in `index.ts`; direct Node file-operation imports stay in the owning domains rather than the entrypoint
+- 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
@@ -61,6 +63,10 @@ Current runtime areas include:
 
 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.
 
+## 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.
+
 ## Message And Queue Flow
 
 ### Inbound Path
@@ -70,9 +76,11 @@ Because `ctx.ui.input()` only exposes placeholder text, the bridge uses `ctx.ui.
 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. A `PendingTelegramTurn` is created and queued locally
-7. Telegram `edited_message` updates are routed separately and update a matching queued turn when the original message has not been dispatched yet
-8. 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 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
 
 ### Queue Safety Model
 

package/docs/locks.md

@@ -0,0 +1,136 @@
+# Extension Locks Standard
+
+`locks.json` is a shared registry for singleton pi extensions.
+
+Path:
+
+```text
+~/.pi/agent/locks.json
+```
+
+## Shape
+
+```json
+{
+  "@llblab/pi-telegram": {
+    "pid": 2590864,
+    "cwd": "/home/user/project"
+  }
+}
+```
+
+Top-level keys are extension identities. Values are JSON objects owned by that extension.
+
+## Identity key
+
+Use the most stable available identity:
+
+1. `package.json/name` for npm-style pi packages
+2. Directory name when the extension entrypoint is `index.ts` but there is no package name
+3. File basename when the extension is a single file
+
+For npm-style package extensions, the canonical value is the `package.json` `name`. Implementations may keep that value as a small local constant when it is clearer than runtime package introspection. The fallback rules are only for unpackaged extensions.
+
+Examples:
+
+```text
+extensions/pi-telegram/package.json name=@llblab/pi-telegram -> @llblab/pi-telegram
+extensions/pi-telegram/index.ts without package.json         -> pi-telegram
+extensions/pi-telegram.ts                                    -> pi-telegram
+```
+
+## Required fields
+
+```json
+{
+  "pid": 2590864
+}
+```
+
+`pid` is the process that currently owns the singleton runtime. `cwd` should be stored when ownership is tied to a pi session directory.
+
+During a user-initiated start/connect event, an extension should:
+
+1. Read its lock entry
+2. If `pid` is stale, replace the entry
+3. If `pid` and `cwd` match the current pi instance, refresh or keep the entry
+4. If a live external owner exists, ask interactively whether to move singleton ownership here
+
+## Acquisition timing
+
+Lock writes must be caused by an explicit user-initiated runtime event, such as `/wakeup-start`, `/telegram-connect`, or a confirmed takeover prompt.
+
+Extension initialization and session-start hooks may read `locks.json`, update local status, install ownership watchers, and resume local work when the existing lock already points at the current `pid`/`cwd`. After a full process restart, a session-start hook may replace a stale lock from the same `cwd` to restore explicitly requested ownership. They must not create ownership from an inactive lock, take over a live external owner, or replace a stale lock from another directory by themselves. Such locks should stay visible as state until the user runs the start/connect command. Session replacement should suspend local runtime work and ownership watchers without releasing the lock, so the next session in the same `pid`/`cwd` can resume from explicit ownership.
+
+## Optional fields
+
+Extensions may add compact fields when useful:
+
+```json
+{
+  "pid": 2590864,
+  "cwd": "/repo/project",
+  "mode": "connected",
+  "updatedAt": "2026-04-28T00:00:00.000Z"
+}
+```
+
+Do not print optional fields in normal UI unless they help the user act.
+
+## Ownership rules
+
+- One top-level key per singleton extension
+- An extension may only mutate its own key
+- Other keys must be preserved exactly
+- If `cwd` is present, active-here ownership means both `pid` and `cwd` match the current pi instance
+- Human-readable diagnostics should say `active here`, `active elsewhere`, or `stale`
+- Debug data belongs in `locks.json`, not in normal status output
+
+## Runtime status
+
+Singleton extensions with footer/status presence should expose quiet but explicit local state. For example, pi-wakeup uses:
+
+- `wakeup off` when this pi instance does not own the singleton runtime
+- `wakeup on` when this pi instance owns the runtime but has no pending wake-up detail to show
+- `wakeup [16:32:39]` when the runtime owns scheduled work and can show the next countdown
+
+## Interactive takeover
+
+Start/connect commands should make singleton moves easy:
+
+1. If no live owner exists, take ownership without an extra prompt
+2. If a live external owner exists, ask whether to move singleton ownership to this pi instance
+3. On confirmation, write the current `{ "pid": ..., "cwd": ... }` to this extension's key in `locks.json`
+4. The previous owner must notice that `locks.json` no longer points at its own `pid`/`cwd` and stop local runtime work without deleting the new lock
+
+Takeover prompts should use the extension name as the dialog title, then the question, a blank line, and source/target lines:
+
+```text
+pi-telegram
+move singleton lock here?
+
+from: pid 2590864, cwd /old
+to: /new
+```
+
+Avoid repeating the extension name in the body. Color is encouraged: extension title/name accent, question warning, `from:`/`to:` muted.
+
+The previous owner may use `fs.watch`, mtime polling, or an existing status/timer tick. Long-lived watchers should compare against a snapshotted `pid`/`cwd` identity rather than a live pi context object, because session replacement such as `/new` makes captured contexts stale. The important contract is graceful local shutdown after ownership mismatch.
+
+## Reset
+
+Delete `~/.pi/agent/locks.json` to reset singleton runtime ownership for all participating extensions without deleting their configuration files such as `telegram.json`.
+
+## Atomicity
+
+Current baseline is read-modify-write JSON. This is enough for interactive pi singleton starts.
+
+If multiple instances may start concurrently, use an atomic helper later:
+
+- Lock file around `locks.json`, or
+- Temp file + rename with conflict checks, or
+- OS-level exclusive open for a short critical section
+
+## Migration
+
+Migrations from legacy lock files or legacy keys should be one-off cleanup work. Runtime ownership should read and write only `locks.json` under the canonical identity key.

package/index.ts

@@ -5,8 +5,9 @@
 
 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 Locks from "./lib/locks.ts";
 import * as Media from "./lib/media.ts";
 import * as Menu from "./lib/menu.ts";
 import * as Model from "./lib/model.ts";
@@ -17,10 +18,9 @@ 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";
 import * as Setup from "./lib/setup.ts";
 import * as Status from "./lib/status.ts";
-import * as Turns from "./lib/turns.ts";
-import * as Updates from "./lib/updates.ts";
 
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
 type RuntimeTelegramQueueItem = Queue.TelegramQueueItem<Pi.ExtensionContext>;
@@ -31,6 +31,7 @@ export default function (pi: Pi.ExtensionAPI) {
   const piRuntime = Pi.createExtensionApiRuntimePorts(pi);
   const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
   const configStore = Config.createTelegramConfigStore();
+  const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
   const activeTurnRuntime = Queue.createTelegramActiveTurnStore();
   const pendingModelSwitchStore =
     Model.createPendingModelSwitchStore<
@@ -63,6 +64,7 @@ export default function (pi: Pi.ExtensionAPI) {
       getQueuedItems: telegramQueueStore.getQueuedItems,
       formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
       getRecentRuntimeEvents: runtimeEvents.getEvents,
+      getRuntimeLockState: lockRuntime.getStatusLabel,
     });
   const currentModelRuntime = Model.createCurrentModelRuntime<
     Pi.ExtensionContext,
@@ -80,6 +82,13 @@ export default function (pi: Pi.ExtensionAPI) {
         bridgeRuntime.queue.incrementNextPriorityReactionOrder,
       updateStatus,
     });
+  const attachmentHandlerRuntime =
+    Handlers.createTelegramAttachmentHandlerRuntime<Pi.ExtensionContext>({
+      getHandlers: configStore.getAttachmentHandlers,
+      execCommand: piRuntime.exec,
+      getCwd: Pi.getExtensionContextCwd,
+      recordRuntimeEvent: runtimeEvents.record,
+    });
 
   // --- Telegram API ---
 
@@ -202,127 +211,76 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: configStore.persist,
-    handleUpdate: Updates.createTelegramPairedUpdateRuntime<
+    handleUpdate: Routing.createTelegramInboundRouteRuntime<
+      Api.TelegramUpdate,
+      Api.TelegramMessage,
+      Api.TelegramCallbackQuery,
       Pi.ExtensionContext,
-      Api.TelegramUpdate
+      ActivePiModel
     >({
-      getAllowedUserId: configStore.getAllowedUserId,
-      setAllowedUserId: configStore.setAllowedUserId,
-      persistConfig: configStore.persist,
+      configStore,
+      bridgeRuntime,
+      activeTurnRuntime,
+      mediaGroupRuntime,
+      telegramQueueStore,
+      queueMutationRuntime,
+      modelMenuRuntime,
+      currentModelRuntime,
+      modelSwitchController,
+      menuActions,
+      attachmentHandlerRuntime,
       updateStatus,
-      removePendingMediaGroupMessages: mediaGroupRuntime.removeMessages,
-      removeQueuedTelegramTurnsByMessageIds:
-        queueMutationRuntime.removeByMessageIds,
-      clearQueuedTelegramTurnPriorityByMessageId:
-        queueMutationRuntime.clearPriorityByMessageId,
-      prioritizeQueuedTelegramTurnByMessageId:
-        queueMutationRuntime.prioritizeByMessageId,
+      dispatchNextQueuedTelegramTurn,
       answerCallbackQuery,
-      handleAuthorizedTelegramCallbackQuery:
-        Menu.createTelegramMenuCallbackHandlerForContext<
-          Api.TelegramCallbackQuery,
-          Pi.ExtensionContext,
-          ActivePiModel
-        >({
-          getStoredModelMenuState: modelMenuRuntime.getState,
-          getActiveModel: currentModelRuntime.get,
-          getThinkingLevel: piRuntime.getThinkingLevel,
-          setThinkingLevel: piRuntime.setThinkingLevel,
-          updateStatus,
-          updateModelMenuMessage: menuActions.updateModelMenuMessage,
-          updateThinkingMenuMessage: menuActions.updateThinkingMenuMessage,
-          updateStatusMessage: menuActions.updateStatusMessage,
-          answerCallbackQuery,
-          isIdle: Pi.isExtensionContextIdle,
-          hasActiveTelegramTurn: activeTurnRuntime.has,
-          hasAbortHandler: bridgeRuntime.abort.hasHandler,
-          getActiveToolExecutions:
-            bridgeRuntime.lifecycle.getActiveToolExecutions,
-          setModel: piRuntime.setModel,
-          setCurrentModel: currentModelRuntime.setCurrentModel,
-          stagePendingModelSwitch: modelSwitchController.stagePendingSwitch,
-          restartInterruptedTelegramTurn:
-            modelSwitchController.restartInterruptedTurn,
-        }),
       sendTextReply,
-      handleAuthorizedTelegramMessage:
-        Media.createTelegramMediaGroupDispatchRuntime<
-          Api.TelegramMessage,
-          Pi.ExtensionContext
-        >({
-          mediaGroups: mediaGroupRuntime,
-          dispatchMessages: Commands.createTelegramCommandOrPromptRuntime<
-            Api.TelegramMessage,
-            Pi.ExtensionContext
-          >({
-            extractRawText: Media.extractFirstTelegramMessageText,
-            handleCommand: Commands.createTelegramCommandHandlerTargetRuntime<
-              Api.TelegramMessage,
-              Pi.ExtensionContext
-            >({
-              hasAbortHandler: bridgeRuntime.abort.hasHandler,
-              clearPendingModelSwitch: modelSwitchController.clearPendingSwitch,
-              hasQueuedTelegramItems: telegramQueueStore.hasQueuedItems,
-              setPreserveQueuedTurnsAsHistory:
-                bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory,
-              abortCurrentTurn: bridgeRuntime.abort.abortTurn,
-              isIdle: Pi.isExtensionContextIdle,
-              hasPendingMessages: Pi.hasExtensionContextPendingMessages,
-              hasActiveTelegramTurn: activeTurnRuntime.has,
-              hasDispatchPending: bridgeRuntime.lifecycle.hasDispatchPending,
-              isCompactionInProgress:
-                bridgeRuntime.lifecycle.isCompactionInProgress,
-              setCompactionInProgress:
-                bridgeRuntime.lifecycle.setCompactionInProgress,
-              updateStatus,
-              dispatchNextQueuedTelegramTurn,
-              compact: Pi.compactExtensionContext,
-              allocateItemOrder: bridgeRuntime.queue.allocateItemOrder,
-              allocateControlOrder: bridgeRuntime.queue.allocateControlOrder,
-              appendControlItem: queueMutationRuntime.append,
-              showStatus: menuActions.sendStatusMessage,
-              openModelMenu: menuActions.openModelMenu,
-              getAllowedUserId: configStore.getAllowedUserId,
-              setAllowedUserId: configStore.setAllowedUserId,
-              setMyCommands,
-              persistConfig: configStore.persist,
-              sendTextReply,
-              recordRuntimeEvent: runtimeEvents.record,
-            }),
-            enqueueTurn: Queue.createTelegramPromptEnqueueController<
-              Api.TelegramMessage,
-              Pi.ExtensionContext
-            >({
-              ...telegramQueueStore,
-              getPreserveQueuedTurnsAsHistory:
-                bridgeRuntime.lifecycle.shouldPreserveQueuedTurnsAsHistory,
-              setPreserveQueuedTurnsAsHistory:
-                bridgeRuntime.lifecycle.setPreserveQueuedTurnsAsHistory,
-              createTurn:
-                Turns.createTelegramPromptTurnRuntimeBuilder<Api.TelegramMessage>(
-                  {
-                    allocateQueueOrder: bridgeRuntime.queue.allocateItemOrder,
-                    downloadFile: downloadTelegramBridgeFile,
-                  },
-                ),
-              updateStatus,
-              dispatchNextQueuedTelegramTurn,
-            }).enqueue,
-          }).dispatchMessages,
-        }).handleMessage,
-      handleAuthorizedTelegramEditedMessage:
-        Turns.createTelegramQueuedPromptEditRuntime<
-          Api.TelegramMessage,
-          Pi.ExtensionContext
-        >({
-          ...telegramQueueStore,
-          updateStatus,
-        }).updateFromEditedMessage,
+      setMyCommands,
+      downloadFile: downloadTelegramBridgeFile,
+      getThinkingLevel: piRuntime.getThinkingLevel,
+      setThinkingLevel: piRuntime.setThinkingLevel,
+      setModel: piRuntime.setModel,
+      isIdle: Pi.isExtensionContextIdle,
+      hasPendingMessages: Pi.hasExtensionContextPendingMessages,
+      compact: Pi.compactExtensionContext,
+      recordRuntimeEvent: runtimeEvents.record,
     }).handleUpdate,
     stopTypingLoop: bridgeRuntime.typing.stop,
     updateStatus,
     recordRuntimeEvent: runtimeEvents.record,
   });
+  const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
+    lock: lockRuntime,
+    hasBotToken: configStore.hasBotToken,
+    startPolling: pollingRuntime.start,
+    stopPolling: pollingRuntime.stop,
+    updateStatus,
+    recordRuntimeEvent: runtimeEvents.record,
+  });
+  const sessionLifecycleRuntime = Registration.appendTelegramLifecycleHooks(
+    Queue.createTelegramSessionLifecycleRuntime<
+      Pi.ExtensionContext,
+      RuntimeTelegramQueueItem,
+      ActivePiModel
+    >({
+      getCurrentModel: Pi.getExtensionContextModel,
+      loadConfig: configStore.load,
+      setQueuedItems: telegramQueueStore.setQueuedItems,
+      setCurrentModel: currentModelRuntime.set,
+      setPendingModelSwitch: pendingModelSwitchStore.set,
+      syncCounters: bridgeRuntime.queue.syncCounters,
+      syncFlags: bridgeRuntime.lifecycle.syncFlags,
+      prepareTempDir,
+      updateStatus,
+      clearPendingMediaGroups: mediaGroupRuntime.clear,
+      clearModelMenuState: modelMenuRuntime.clear,
+      getActiveTurnChatId: activeTurnRuntime.getChatId,
+      clearPreview: previewRuntime.clear,
+      clearActiveTurn: activeTurnRuntime.clear,
+      clearAbort: bridgeRuntime.abort.clearHandler,
+      stopPolling: lockedPollingRuntime.suspend,
+      recordRuntimeEvent: runtimeEvents.record,
+    }),
+    { onSessionStart: lockedPollingRuntime.onSessionStart },
+  );
 
   // --- Extension Registration ---
 
@@ -338,44 +296,22 @@ export default function (pi: Pi.ExtensionAPI) {
       setupGuard: bridgeRuntime.setup,
       getMe: Api.fetchTelegramBotIdentity,
       persistConfig: configStore.persist,
-      startPolling: pollingRuntime.start,
+      startPolling: lockedPollingRuntime.start,
       updateStatus,
       recordRuntimeEvent: runtimeEvents.record,
     }),
     getStatusLines,
     reloadConfig: configStore.load,
     hasBotToken: configStore.hasBotToken,
-    startPolling: pollingRuntime.start,
-    stopPolling: pollingRuntime.stop,
+    startPolling: lockedPollingRuntime.start,
+    stopPolling: lockedPollingRuntime.stop,
     updateStatus,
   });
 
   // --- Lifecycle Hooks ---
 
   Registration.registerTelegramLifecycleHooks(pi, {
-    ...Queue.createTelegramSessionLifecycleRuntime<
-      Pi.ExtensionContext,
-      RuntimeTelegramQueueItem,
-      ActivePiModel
-    >({
-      getCurrentModel: Pi.getExtensionContextModel,
-      loadConfig: configStore.load,
-      setQueuedItems: telegramQueueStore.setQueuedItems,
-      setCurrentModel: currentModelRuntime.set,
-      setPendingModelSwitch: pendingModelSwitchStore.set,
-      syncCounters: bridgeRuntime.queue.syncCounters,
-      syncFlags: bridgeRuntime.lifecycle.syncFlags,
-      prepareTempDir,
-      updateStatus,
-      clearPendingMediaGroups: mediaGroupRuntime.clear,
-      clearModelMenuState: modelMenuRuntime.clear,
-      getActiveTurnChatId: activeTurnRuntime.getChatId,
-      clearPreview: previewRuntime.clear,
-      clearActiveTurn: activeTurnRuntime.clear,
-      clearAbort: bridgeRuntime.abort.clearHandler,
-      stopPolling: pollingRuntime.stop,
-      recordRuntimeEvent: runtimeEvents.record,
-    }),
+    ...sessionLifecycleRuntime,
     onBeforeAgentStart: Registration.createTelegramBeforeAgentStartHook(),
     onModelSelect: currentModelRuntime.onModelSelect,
     ...Queue.createTelegramAgentLifecycleHooks<

package/lib/config.ts

@@ -5,10 +5,19 @@
 
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
-const AGENT_DIR = join(homedir(), ".pi", "agent");
-const CONFIG_PATH = join(AGENT_DIR, "telegram.json");
+import type { TelegramAttachmentHandlerConfig } from "./handlers.ts";
+
+function getAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR
+    ? resolve(process.env.PI_CODING_AGENT_DIR)
+    : join(homedir(), ".pi", "agent");
+}
+
+function getConfigPath(): string {
+  return join(getAgentDir(), "telegram.json");
+}
 
 export interface TelegramConfig {
   botToken?: string;
@@ -16,6 +25,7 @@ export interface TelegramConfig {
   botId?: number;
   allowedUserId?: number;
   lastUpdateId?: number;
+  attachmentHandlers?: TelegramAttachmentHandlerConfig[];
 }
 
 export interface TelegramConfigStore {
@@ -25,6 +35,7 @@ export interface TelegramConfigStore {
   getBotToken: () => string | undefined;
   hasBotToken: () => boolean;
   getAllowedUserId: () => number | undefined;
+  getAttachmentHandlers: () => TelegramAttachmentHandlerConfig[] | undefined;
   setAllowedUserId: (userId: number) => void;
   load: () => Promise<void>;
   persist: (config?: TelegramConfig) => Promise<void>;
@@ -64,8 +75,8 @@ export function createTelegramConfigStore(
   options: TelegramConfigStoreOptions = {},
 ): TelegramConfigStore {
   let config: TelegramConfig = options.initialConfig ?? {};
-  const agentDir = options.agentDir ?? AGENT_DIR;
-  const configPath = options.configPath ?? CONFIG_PATH;
+  const agentDir = options.agentDir ?? getAgentDir();
+  const configPath = options.configPath ?? getConfigPath();
   return {
     get: () => config,
     set: (nextConfig) => {
@@ -77,6 +88,7 @@ export function createTelegramConfigStore(
     getBotToken: () => config.botToken,
     hasBotToken: () => !!config.botToken,
     getAllowedUserId: () => config.allowedUserId,
+    getAttachmentHandlers: () => config.attachmentHandlers,
     setAllowedUserId: (userId) => {
       config.allowedUserId = userId;
     },