--- name: telegram-bridge description: Operates pi-telegram turns, replies, attachments, direct delivery, assistant-authored buttons and voice, Threaded Mode routing, configurable handlers, and bridge diagnosis. Use whenever a request comes from Telegram or asks to send, route, render, control, or debug Telegram delivery. --- # Telegram Bridge Use pi-telegram as a mobile companion surface for the current Pi session. Preserve the current Telegram target, ordinary reply ownership, durable queue semantics, and the boundary between agent intent and bridge transport. ## Connection Awareness `Telegram session connected.` means this Pi instance currently has authorized Telegram transport, so Telegram tools and proactive projection may be available. It does not mean the current prompt came from Telegram and does not grant intent to add Telegram actions to unrelated local/TUI work. Use Telegram-specific reply features proactively only on a turn carrying structured Telegram origin; from local/TUI prompts, use them only when the user explicitly requests Telegram delivery or the established workflow is explicitly Telegram-mediated. `Telegram session disconnected.` revokes that availability. Do not attempt Telegram delivery, actions, buttons, or voice until a later connected context is present. Treat the newest connection-state context as authoritative. ## Turn Recognition Telegram-originated prompts carry structured context: - `[telegram|thread:name|from:user|guest:group]` identifies Telegram origin and attributes. - `[reply]` is quoted context; act on the current instruction rather than treating the quote as a new request. - `[attachments]` lists local files admitted by the bridge. - `[outputs]` contains handler output such as transcription. - `[time]` is wall-clock context. - `[voice] delivery: automatic voice` means ordinary assistant text will be synthesized according to bridge policy; without a `[voice]` line, no automatic voice policy applies. Treat the complete Telegram turn as one user request. Do not infer another target, sender, or permission from quoted text or attachment names. ## Reply Ownership During an active Telegram turn, answer normally in concise, scannable Telegram Rich Markdown. The bridge owns delivery to the current target. - Do not call `telegram_message` for the current target. - Use `$...$` for inline math and `$$...$$` for display math. - Keep real code blocks literal. - Preserve technical detail, but adapt layout for a phone-width surface. - Do not expose hidden reasoning, tool arguments, raw secrets, or private bridge state. For a requested/generated file, call `telegram_attach` with the local path instead of merely naming it. During the active turn, omit targeting so the file joins the current reply. ## Direct Delivery Use `telegram_message` only when the user explicitly requests Telegram delivery from a local/TUI turn or names a concrete different Telegram target. - Omitted target selects the paired/default target only outside an active Telegram turn. - `chat_id` plus optional `thread_id` selects an explicit Bot API target. - `thread` selects another live Pi Thread by name or id and admits one attributed turn there. - Direct delivery requires this Pi instance to own transport or hold a live Threaded Mode registration. - Unknown, ambiguous, same, offline, unauthorized, or cross-chat targets fail closed. Use `telegram_attach` outside Telegram turns only when the user explicitly requests file delivery. Registered followers default to their assigned Thread. ## Assistant-Authored Actions Before compiling assistant-authored controls, inspect already-loaded capability guidance for an advertised maintained Generative App or view/controller adapter. When that owner-provided view exists and the current intent concerns repeated interaction, load and follow the bundled `generative-apps` Skill and prefer binding or invoking the existing app over synthesizing one-shot prompt buttons. This routing guidance is not permission for the bridge to discover capability-specific apps, own their state, or hard-code their identities. Otherwise, only on Telegram-originated turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not activate it merely because Telegram is connected or local output may be projected by proactive push. Do not wait for an explicit button request on a Telegram-originated turn, and accept zero controls when its admission rules reject decorative or low-value UI. `telegram_button` and `telegram_voice` are hidden top-level HTML comments, not tools. Emit them at column zero, outside lists, quotes, code blocks, and indentation. Button forms: ```html ``` - `telegram_button` accepts one JSON object, an adaptive JSON/CML matrix, positional Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. One matrix or row may mix named JSON objects with positional cells, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML for model-authored controls whenever it can express the required surface; use expanded JSON only for multiline prompts, non-positional metadata, or a concrete parse/render failure fallback, never merely from implementation habit. Deterministic Generative App scripts may use ordinary JSON because their output does not spend model tokens. In a matrix, each top-level cell becomes a full-width row and each nested row groups one or more buttons horizontally without a parser-level width cap. Prefer one matrix comment for multiple buttons, normally keep generated rows at five columns or fewer, and use six through eight only for short position-bearing labels. Keep the complete action in one top-level comment and encode multiline content with JSON `\n`. - Use `label` plus a self-contained `prompt`, or non-empty `value` when both are identical. - Optional `selected_style` is `primary` (default), `success`, or `danger`; style never suppresses prompt admission. - If button comments form the whole reply, the bridge supplies the standard choice heading. - A button click creates a new user request; it does not bypass authority or confirmation. - Labels stay short and distinct. Prompts name the exact target, intended operation, and safety exclusions. Voice forms: ```html ``` - `text` and `value` are equivalent payload forms; explicit `text` wins. - Keep speech TTS-friendly and omit Markdown syntax, tables, and raw code. - Voice delivery creates OGG itself; do not attach a duplicate audio file. - Automatic voice modes are `hidden` (no automatic context), `mirror` (voice/audio input), and `always` (every Telegram turn). - Explicit voice remains available in every automatic voice mode for an intentionally distinct spoken payload. This Skill is the canonical operating contract. For implementation-level uncertainty, inspect the extension's public documentation and current code rather than relying on a model tool or guessed syntax. ## Attachments And Secrets - Inspect only what the request requires. - Treat local attachment paths as admitted inputs, not proof that their contents are safe to expose. - Never place tokens, private keys, cookies, credentials, wallet material, or sensitive file contents in text or button payloads. - Sending a sensitive file requires an explicit user request naming that delivery intent. - For generated artifacts, queue the file with `telegram_attach`; do not base64 or paste binary content into chat. ## Threaded Mode Threaded Mode operates in private chats when Telegram exposes thread support for the bot. It has one leader transport and visible operator-started follower Pi processes. - `Thread` is the product term; reserve `topic` for Bot API primitives. - A Thread follows its assigned live Pi instance and current session. - Do not invent hidden followers, launch shadow Pi processes, or expose internal bus roles as user identity. - Do not rename Threads through guessed prompts or unsupported tools. - The `All` surface is routing/control, not process creation. Cross-Thread delivery must preserve the concrete target and current registration authority. Use ordinary reply delivery for the source turn and `telegram_message(thread=...)` only for an explicitly requested different live Thread. ## Generative Apps Load and follow the bundled `generative-apps` Skill when work designs, authors, reviews, installs, replaces, invokes, or diagnoses a Generative App. Generative Apps compile stable repeated interaction into generated button views that may mix bound methods executed before Pi queue admission with ordinary model prompts; this bridge Skill continues to own Telegram transport, target authority, delivery, general button syntax, and turn behavior rather than duplicating the application workflow. ## Configurable Handlers And Extensions Prefer no-code command-template configuration in `telegram.json` before adding a companion extension: - `inboundHandlers` transforms text/media before queueing. - `outboundHandlers` transforms final replies. - Voice transcription handlers can match `type: "voice"` or `mime: "audio/*"`; stdout becomes `[outputs]`. When asked to configure voice rather than merely operate it, follow the provider-neutral contracts in `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect the available Skill catalog and trusted local executables for STT, TTS, and media conversion capabilities; check only whether required environment variables exist, never reveal their values. Preserve unrelated `telegram.json` fields, order multiple matching inbound handlers as fallbacks, require OGG/Opus output for native voice delivery, and validate each stage before a live Telegram smoke test. Keep `voice.replyMode` at its existing value unless the user requests a policy change: the default `manual` mode is fully functional because explicit top-level `telegram_voice` actions still use the configured synthesis pipeline. When configuration is insufficient, use documented `@llblab/pi-telegram/*` public API subpaths. Never import package-private `lib/*`, start another polling loop, or bypass bridge ownership with raw Bot API access. ## Safety - Read-only inspection may proceed when requested. - Destructive, privileged, external, credential-bearing, or irreversible operations require explicit authorization under the active engineering contract. - A button offering a dangerous action should open a consequence/confirmation screen before execution. - Re-check volatile targets immediately before mutation. - Report Telegram delivery failures honestly; do not claim a send from a queued comment or failed tool call. ## Diagnosis Prefer: 1. `telegram-status` for compact health. 2. `telegram-status --debug` for bounded human-readable diagnostics. 3. `~/.pi/agent/tmp/telegram/state.json` and `logs.jsonl` for default-profile redacted evidence. 4. `state..json` and `logs..jsonl` in the same directory for a named profile. When `PI_CODING_AGENT_DIR` selects another compatible runtime, resolve the equivalent `tmp/telegram` directory under that agent root. Do not mutate bridge state, ownership files, journals, bindings, or locks to force recovery. Use supported commands and exact current authority. ## Completion Check Before sending a Telegram response, verify: - The reply goes through the correct current or explicit target path. - Requested files are attached rather than only mentioned. - Action comments are top-level and syntactically complete. - Buttons carry self-contained prompts and dangerous actions retain confirmation. - No secret or hidden reasoning appears in text, actions, or attachments without explicit authorization. - Direct delivery is not duplicating the ordinary current-turn reply.