diff --git a/README.md b/README.md index 18e3793..925673b 100644 --- a/README.md +++ b/README.md @@ -1,339 +1,205 @@ +
+ # oh-my-pi-telegram -![pi-telegram screenshot](screenshot.png) +**A Telegram companion hub for live [Oh My Pi](https://github.com/can1357/oh-my-pi) (`omp`) sessions — +queue prompts, stream replies, send files and voice, and supervise your agent from your phone.** -**Telegram companion hub for live [Oh My Pi](https://github.com/can1357/oh-my-pi) (omp) sessions.** +![Version](https://img.shields.io/badge/version-0.22.0--evandro.1-informational) +![Node](https://img.shields.io/badge/node-%3E%3D22.19.0-informational) +![License](https://img.shields.io/badge/license-MIT-informational) -> **This is the Evandro Fonseca Junior fork** of [`@llblab/pi-telegram@0.22.0`](https://github.com/llblab/pi-telegram/tree/v0.22.0) (SHA `afe09c5`), repackaged and validated as a drop-in extension for [`can1357/oh-my-pi`](https://github.com/can1357/oh-my-pi) — the AI coding agent for the terminal. -> -> Upstream lineage: `badlogic/pi-telegram` → `llblab/pi-telegram` (0.22.0) → **`evandrodevbr/oh-my-pi-telegram`** (this fork). +[Install](#installation) · [Features](#what-it-does) · [How it works](#how-it-works) · [Limitations](#limitations) · [Development](#development) · [CI/CD](#cicd) -## Oh My Pi (omp) Compatibility +pi-telegram running in Telegram -This fork is built and tested against: +
-| Component | Version | Status | -| --- | --- | --- | -| `can1357/oh-my-pi` (CLI: `omp`) | `>=16.5.2` (`@oh-my-pi/pi-coding-agent`) | ✅ verified | -| `@earendil-works/pi-{ai,agent-core,coding-agent}` | `>=0.80.6` | ✅ verified (peerDeps preserved from upstream) | -| `node` | `>=22.19.0` | ✅ verified on Node 24.15.0 | -| Telegram Bot API | current | ✅ unchanged from upstream | +> [!NOTE] +> **Project status:** fork of [`@llblab/pi-telegram@0.22.0`](https://github.com/llblab/pi-telegram/tree/v0.22.0) +> (SHA `afe09c5`), repackaged as `@evandrodevbr/oh-my-pi-telegram` and declared as an +> `omp` extension. Per [`CHANGELOG.md`](CHANGELOG.md), the fork passes the upstream +> gates (typecheck, 1229/1230 tests with one platform-only skip, `npm audit` with 0 +> vulnerabilities, clean `npm pack --dry-run`). The latest commit adds a design spec +> for an OMP 17 status-bar segment ([`docs/superpowers/specs/`](docs/superpowers/specs/2026-07-15-telegram-omp-status-design.md)); +> that spec needs a new OMP core API and is **not implemented in this repository yet**. -### Install into omp +> [!IMPORTANT] +> **This is a runtime adapter, not a remote terminal.** Telegram prompts are normal +> model turns in the instance's *currently active* session and inherit its +> post-compaction context, so token cost is not proportional only to the new mobile +> message. Telegram can compact the current session, but cannot create, resume, fork, +> browse or switch sessions, and arbitrary slash commands are never forwarded to the TUI. + +## Installation + +Requires `omp` ≥ 16.5.2 (`@oh-my-pi/pi-coding-agent`) and Node.js ≥ 22.19.0. ```bash -# From npm (after this fork is published): -omp install npm:@evandrodevbr/oh-my-pi-telegram +# From git (this repository) +omp plugin install https://git.evandro.dev.br/evandro/oh-my-pi-telegram.git -# From git (always works): -omp install git:github.com/evandrodevbr/oh-my-pi-telegram +# From npm (once the package is published) +omp plugin install npm:@evandrodevbr/oh-my-pi-telegram -# From a local checkout (development): -omp install --link /path/to/oh-my-pi-telegram +# From a local checkout (development) +omp plugin link /path/to/oh-my-pi-telegram ``` -Then inside `omp`: +Restart (or reload) `omp` so the extension loads, then: -```bash -/telegram-setup # paste bot token -/telegram-connect # activate polling for this omp instance -``` +1. Create a bot with [@BotFather](https://t.me/BotFather) (`/newbot`) and copy the token. +2. In `omp`, run `/telegram-setup` and paste the token. +3. Run `/telegram-connect` to activate polling for this instance. +4. In the bot DM, send `/start`. -In your Telegram bot DM: +> [!WARNING] +> **The first Telegram user to message the bot becomes the allowed owner**; everyone +> else is ignored. Pair right after `/telegram-connect`, and never put the bot token in +> chat, source, committed config or logs. Setup can prefill the token from +> `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN` or `TELEGRAM_KEY`; the saved +> config lives in `~/.pi/agent/telegram.json`. -```text -/start -``` +## Why this fork and not upstream -The first user becomes the allowed owner. +`llblab/pi-telegram@0.22.0` targets the Pi extension platform (`@earendil-works/pi-*`). +`omp` consumes the same platform republished as `@oh-my-pi/pi-coding-agent`. This fork: -### Why this fork exists +1. Renames the package to `@evandrodevbr/oh-my-pi-telegram` so it is unambiguous in the `omp` extension registry. +2. Keeps the upstream `peerDependencies` on `@earendil-works/pi-{ai,agent-core,coding-agent}` `>=0.80.6`, the runtime surface `omp` consumes — no code changes or shims. +3. Declares the extension through an `omp` block in `package.json` (`extensions`, display name and `compatibleWith: >=16.5.2`); the old `pi` block was replaced by it. +4. Re-runs every upstream gate (`typecheck` → `test` → `audit` → `pack:check`) on the `v0.22.0` source. -`llblab/pi-telegram@0.22.0` targets the **Pi extension platform** (`@earendil-works/pi-*`). `omp` ships the same platform but republishes it under `@oh-my-pi/pi-coding-agent` with the additional harness tooling (LSP, DAP, hashline, subagents, advisor, TTSR, …). This fork: +Lineage: `badlogic/pi-telegram` → `llblab/pi-telegram` (0.22.0) → **this fork**. -1. **Renames the npm package** to `@evandrodevbr/oh-my-pi-telegram` so it is unambiguous in the `omp` extension registry. -2. **Keeps the upstream `peerDependencies`** on `@earendil-works/*` (these are the canonical runtime packages that both Pi and omp consume). -3. **Adds an `omp` field** in `package.json` with explicit compatibility metadata for downstream extension discovery. -4. **Re-runs every upstream gate** (`typecheck` → `test` → `audit` → `pack:check`) on the exact `v0.22.0` source — 1229 tests pass, 0 vulnerabilities, pack clean. -5. **Adds this README section** so the fork is discoverable as the Telegram bridge for omp. +## What it does -## What `pi-telegram` (and this fork) does +| Surface | What you can do | +|---|---| +| **Prompt intake** | Send text, replies, edits, images, files, albums and voice notes into the session | +| **Queue control** | Messages sent while the agent is busy become queued turns; inspect, delete, promote, continue, abort, stop or force the next one | +| **Operator menu** | `/start` opens status, prompt templates, model, thinking level, settings, queue and extension sections | +| **Prompt templates** | Run Pi prompt templates as Telegram-safe commands such as `/fix_tests` | +| **Model and thinking** | Switch model or reasoning level through safe continuation flows; confirm `/compact` | +| **Rich replies** | Native Rich Markdown (default) or legacy Markdown-to-HTML for final answers; optional live draft previews; native `…typing` status while the agent works | +| **Files** | Inbound files land in `/tmp/telegram` (50 MiB default limit); `telegram_attach` returns artifacts as real files | +| **Voice** | Inbound voice through command-template, programmatic or STT handlers; outbound via `telegram_voice` and TTS providers | +| **Buttons** | Hidden `telegram_button` comments become inline buttons whose callbacks re-enter the session | +| **Threaded Mode** | One leader plus visible follower `omp` instances, each with its own Telegram thread, through one bot | +| **Named profiles** | Run independent bots from one agent directory with isolated polling, diagnostics and bus transport | +| **Extension platform** | Companion extensions add commands, menu sections, status rows, update/callback handlers, inbound/outbound handlers and voice providers | +| **Diagnostics** | `/telegram-status` shows connection, mode, queue, transport and recent redacted events | -`pi-telegram` turns a private Telegram DM into a mobile operator surface for Pi/omp. It accepts prompts, queues work, streams readable previews, delivers final replies and files, exposes safe controls, and lets companion extensions add Telegram-native capabilities without owning a second bot loop. +
+Commands -It is a **runtime adapter**, not a remote terminal. Start or supervise work in the `omp` TUI, then continue from Telegram while away from the keyboard. Each Telegram destination follows a running `omp` instance and sends prompts into that instance's currently active session; it is not permanently bound to one session file or session identity. The bridge preserves Pi session semantics instead of pretending Telegram is a PTY, shell, process launcher, or session browser. That boundary is the product: Telegram gets safe runtime handles, not raw terminal power. - -This fork is derived from [`llblab/pi-telegram@0.22.0`](https://github.com/llblab/pi-telegram/tree/v0.22.0) (SHA `afe09c5`), which itself is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). - -## Install (npm/git, same as upstream) - -From npm: - -```bash -pi install npm:@evandrodevbr/oh-my-pi-telegram -``` - -From git: - -```bash -pi install git:github.com/evandrodevbr/oh-my-pi-telegram -``` - -The 0.21 extension platform requires Pi `0.80.6` or newer. Its Activity API uses the public `agent_settled` lifecycle event to keep retries/continuations under one activity identity and release that identity only after the run fully settles. - -## Quick Start - -### 1. Create a Telegram bot - -1. Open [@BotFather](https://t.me/BotFather). -2. Run `/newbot`. -3. Pick a name and username. -4. Copy the bot token. - -### 2. Configure Pi/omp - -Run this inside Pi/omp: - -```bash -/telegram-setup -``` - -Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved token, setup offers it as the default. If no saved token exists, setup can prefill from `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, or `TELEGRAM_KEY`. Named profiles are optional; the ordinary `/telegram-setup` and `/telegram-connect` flow keeps using the default profile. Use `/telegram-setup ` only when you want an additional bot profile. Cancelling or failing named-profile token validation leaves the currently active profile and polling runtime unchanged; setup reports the profile as saved and connected only after polling startup succeeds. - -### 3. Connect this Pi/omp instance and its active session - -```bash -/telegram-connect -``` - -The connected instance owns Telegram polling. Use `/telegram-connect ` to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the unnamed default profile keeps legacy paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. - -### 4. Pair your Telegram account - -Open the bot DM and send: - -```text -/start -``` - -The first Telegram user to message the bot becomes the allowed owner. Other users are ignored. - -## What It Feels Like - -- Start a task in the terminal, walk away, and keep supervising it from your phone. -- Send another prompt while Pi is busy; it becomes a queued Telegram turn instead of interrupting the active run. -- Open `/start` to inspect status, model, thinking, settings, prompt templates, and queue controls. -- Send voice, images, files, replies, edits, or media groups; the bridge turns them into Pi context. -- Ask for an artifact; `telegram_attach` returns it through the active reply or direct Telegram delivery. -- In Threaded Mode, run multiple visible Pi instances through one bot, each with its own Telegram thread. -- Configure named profiles to run independent Telegram bots from the same Pi agent directory without sharing transport or routing state. - -## Product Model - -| Lens | What `pi-telegram` owns | -| --- | --- | -| Operator companion | A phone-width control surface for the active session of a running Pi instance | -| Runtime adapter | Telegram targets mapped to Pi instances, then into each instance's current session lifecycle, queueing, previews, final replies, and artifacts | -| Telegram UI harness | Menus, settings, callbacks, Rich Markdown, drafts, active status, buttons, voice, and files | -| Multi-instance organism | One leader plus explicit visible followers routed through Telegram private-chat threads | -| Extension platform | Commands, sections, status rows, update handlers, inbound/outbound handlers, and voice providers | -| Safety boundary | No hidden Pi processes, no fake terminal, no PTY tricks, no arbitrary TUI slash-command forwarding | - -## Feature Showcase - -`pi-telegram` is intentionally broad: it is a Telegram-shaped runtime surface, not only a message relay. This catalogue keeps the practical feature surface visible while detailed contracts stay in `/docs`. - -| Surface | What you can do | Why it matters | -| --- | --- | --- | -| Prompt intake | Send text, replies, edits, images, files, albums, voice notes, and handler output into Pi. | Telegram becomes a real mobile input surface with file/context references, not just a text tunnel. | -| Queue control | Inspect waiting turns, delete stale work, promote important prompts, continue, abort, stop, or force the next queued item. | Long Pi tasks keep running while new mobile prompts stay visible and controllable instead of interrupting or disappearing. | -| Operator menu | Use `/start` for status, prompt templates, model, thinking, settings, queue, extension sections, and diagnostics. | The bot is an operator panel, not a command cheat sheet. | -| Prompt templates | Run Pi prompt templates as Telegram-safe commands such as `/fix_tests`. | Reusable local workflows become phone-accessible without exposing arbitrary terminal commands. | -| Model and thinking | Switch model or reasoning level from Telegram through safe continuation flows. | Mobile control can adjust execution strategy without tearing down the current session. | -| Compaction | Confirm `/compact`, show native active status during compaction, and preserve Telegram-owned turn semantics. | Context maintenance is visible and safe from the phone. | -| Draft previews | Show Telegram's native `…typing` indicator whenever the connected instance is doing agent work, or enable Rich Draft previews for streamed answer text. | Local prompts, Telegram turns, and autonomous continuations remain visibly active while draft visibility stays independent from final rendering. | -| Assistant rendering | Choose Native Rich Markdown or legacy Markdown-to-HTML for final assistant replies. | Renderer compatibility is explicit instead of being conflated with draft previews. | -| Bridge UI rendering | Render tool rows, reasoning/technical steps, menus, queue controls, status, settings, diagnostics, and sections through explicit Telegram HTML/plain UI. | Harness-owned surfaces remain operationally predictable and visually distinct from model-authored answers. | -| Inbound files | Download inbound files to the Pi agent temp directory with size limits. | Screenshots, PDFs, datasets, and artifacts enter Pi as inspectable local files. | -| Outbound artifacts | Return generated files through `telegram_attach` during active turns or explicit direct delivery. | Agents send real artifacts as files, not pasted blobs. | -| Voice input | Route audio through configured command-template handlers, programmatic handlers, or STT providers. | Voice notes become usable prompt context. | -| Voice output | Use `telegram_voice`, reply modes, configured voice handlers, and TTS providers. | Replies can become Telegram voice messages when the workflow calls for it. | -| Buttons | Turn top-level `telegram_button` comments into inline buttons. | Assistant-authored choices become native Telegram interactions. | -| Callback routing | Route known callbacks to the owner extension and unknown callbacks back into Pi. | Companion extensions can build UI without polling Telegram themselves. | -| Threaded Mode | Run one leader plus visible follower Pi instances through named private-chat threads. | One bot can host a local multi-instance Pi organism without hidden process spawning. | -| Reroute and restore | Preserve unknown threads and offer explicit target choices. | Telegram client state can be repaired without silently deleting or hijacking prompts. | -| Extension sections | Add menu sections, commands, status rows, settings, callbacks, and delivery helpers from companion extensions. | `pi-telegram` becomes a platform surface for other Pi extensions. | -| Runtime diagnostics | Use `/telegram-status` and recent runtime events for connection, role, queue, transport, and failure evidence. | Debugging lives in the operator surface instead of hidden logs only. | -| Safety and ownership | Pair one owner, lock transport, scope targets, and reject fake terminal behavior. | Remote access remains explicit, bounded, and understandable. | - -## Core Loop - -```text -Telegram message - -> Telegram turn - -> queue or active dispatch - -> Pi agent lifecycle - -> streaming preview / native active status - -> final Rich Markdown reply - -> optional files, voice, buttons, or callback actions -``` - -The bridge keeps Telegram responsive without stealing Pi's runtime model. Queueing, model changes, compaction, aborts, final delivery, and direct artifact sends all stay scoped to the Pi instance that accepted the work. - -## Telegram Controls - -Use these in the bot DM. +In the bot DM: | Command | Purpose | -| --- | --- | -| `/start` | Pair when needed and open the main operator menu | +|---|---| +| `/start` | Pair when needed and open the operator menu | | `/compact` | Confirm and run session compaction when safe | | `/next` | Dispatch the next queued turn, aborting first if needed | | `/continue` | Enqueue a priority continuation prompt | -| `/abort` | Abort the active run while preserving the queue | +| `/abort` | Abort the active run, keeping the queue | | `/stop` | Abort the active run and clear waiting Telegram turns | -Hidden compatibility shortcuts: `/help`, `/status`, `/model`, `/thinking`, `/queue`, and `/settings` jump into the same menu system. +`/help`, `/status`, `/model`, `/thinking`, `/queue` and `/settings` are hidden shortcuts into the same menus. -## Pi Commands - -Run these inside Pi. +Inside `omp`: | Command | Purpose | -| --- | --- | -| `/telegram-setup` | Save or update the default bot token | -| `/telegram-setup ` | Save or update a named-profile bot token | -| `/telegram-connect` | Activate the default profile and acquire its transport ownership | -| `/telegram-connect ` | Activate a named profile and acquire its transport ownership | +|---|---| +| `/telegram-setup [profile]` | Save or update the default (or a named-profile) bot token | +| `/telegram-connect [profile]` | Activate a profile and acquire its transport ownership | | `/telegram-disconnect` | Stop polling and release ownership | -| `/telegram-status` | Inspect connection, mode, queue, transport, and recent diagnostics | +| `/telegram-status` | Inspect connection, mode, queue, transport and diagnostics | -Named profile identifiers contain only lowercase ASCII letters and digits (maximum 32 characters); `default`, `main`, and `active` remain reserved. +Profile names use lowercase ASCII letters and digits (max 32 characters); `default`, `main` and `active` are reserved. -## Main Surfaces +
-### Operator Menu - -`/start` opens the Telegram-native control panel: status, prompt-template commands, model selection, thinking level, settings, queue controls, and extension sections. It is the primary Telegram UI; reaction shortcuts are secondary queue affordances. - -### Queue Runtime - -Messages sent while Pi is busy become queued turns. Priority lanes support control actions and model-switch continuations. Queue controls let you inspect, delete, promote, and dispatch work from Telegram without touching the terminal. - -### Native Rich Markdown - -Rich Markdown is the default model-answer membrane. Complete assistant and guest model replies use Telegram's native Rich Message APIs, while tool-call rows, reasoning/thinking blocks, menus, status rows, queue controls, settings, diagnostics, and other harness-owned surfaces use explicit Telegram HTML/plain rendering. This keeps meaningful model-authored answers visually distinct from bridge-owned operational UI. Two Settings controls keep the layers separate: `Draft previews` toggles live `sendRichMessageDraft` frames, while `Assistant rendering` chooses final-answer delivery (`rich` Native Rich Markdown or `html` legacy Markdown-to-HTML). - -### Files And Artifacts - -Inbound files land under `/tmp/telegram` and default to a 50 MiB limit. `telegram_attach` is the canonical outbound file path. During Telegram-originated turns it attaches to the active reply; during explicit local/TUI delivery it can send to the paired/default chat or routed Threaded Mode target. - -### Voice And Media - -Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. - -### Buttons And Callbacks - -Assistant replies can include top-level hidden `telegram_button` comments. The bridge strips the comments from visible text, renders inline buttons, and routes callbacks back into Pi as queued prompts or extension-owned callback actions. - -### Threaded Mode And Multi-Instance Bus - -Classic private DM mode is the base product mode. When Telegram private-chat Threaded Mode is available, the bridge enables a local leader/follower bus automatically: - -- One live leader owns `getUpdates`. -- Followers are visible Pi processes started by the operator. -- Each connected instance gets a Telegram thread target. -- Follower session replacement automatically reconnects the new session context to the same thread instead of requiring another manual connect. -- Unknown threads are preserved and offered explicit reroute/restore choices. -- Telegram never launches hidden Pi processes. - -| Mode | Best for | Runtime shape | -| --- | --- | --- | -| Classic DM | One running Pi instance and its active session controlled from one private bot chat | One polling owner, one queue/runtime surface | -| Threaded Mode | Several visible Pi instances sharing one bot | One leader owns transport; each named private-chat thread follows its assigned instance and current session | - -## Environment Configuration - -Most controls live in Pi commands or the Telegram menu. Environment variables remain for bootstrap and transport boundaries: +
+Environment variables | Area | Variables | -| --- | --- | +|---|---| | Bot token bootstrap | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, `TELEGRAM_KEY` | | HTTP proxy | `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, plus `NODE_USE_ENV_PROXY=1` or Node `--use-env-proxy` | -| Telegram network family | `PI_TELEGRAM_NETWORK_FAMILY=auto`, `ipv4`, `ipv6`, or `ipv4-fallback` | +| Network family | `PI_TELEGRAM_NETWORK_FAMILY` = `auto`, `ipv4`, `ipv6` or `ipv4-fallback` | | Agent data root | `PI_CODING_AGENT_DIR` | | Inbound file limit | `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES`, `TELEGRAM_MAX_FILE_SIZE_BYTES` | | Outbound attachment limit | `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES`, `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES` | -Defaults are chosen for ordinary private-bot use: saved config in `~/.pi/agent`, inbound temp files in `~/.pi/agent/tmp/telegram`, `assistant: { rendering: "rich", draftPreviews: false }` for assistant answer output, and native Telegram active status for long-running turns. +Defaults: config in `~/.pi/agent`, inbound temp files in `~/.pi/agent/tmp/telegram`, and `assistant: { rendering: "rich", draftPreviews: false }`. -## Extension Platform +
-Companion extensions can integrate with Telegram without owning polling or transport: +## How it works -- Register Telegram slash commands. -- Add menu sections and settings surfaces. -- Add compact status rows. -- Deliver target-aware operational views and chat actions from companion code. -- Observe normalized assistant, reasoning, tool, compaction, and settlement activity without blocking Pi. -- Handle update/callback namespaces. -- Provide inbound preprocessing handlers. -- Provide outbound voice synthesis. -- Use direct delivery helpers for explicit local/TUI sends. +```mermaid +flowchart LR + TG["Telegram
private DM · Threaded Mode"] -->|"getUpdates"| POLL + subgraph OMP["omp instance (extension)"] + POLL["polling + updates
pairing · routing"] --> Q["turns + queue
control · priority · default"] + Q -->|"sendUserMessage"| AG["agent session
(currently active)"] + AG -->|"lifecycle events"| OUT["previews · rich replies
files · voice · buttons"] + end + OUT -->|"Bot API"| TG + POLL <-->|"local bus
Unix socket / named pipe"| F["follower omp instances
(Threaded Mode)"] +``` -Stable public entrypoints are documented in [Public API](./docs/public-api.md), [Telegram Delivery API](./docs/delivery.md), [Telegram Activity API](./docs/activity.md), [Extension Sections](./docs/sections.md), [Inbound Handlers](./docs/inbound.md), [Outbound Handlers](./docs/outbound.md), [Updates](./docs/updates.md), and [Voice Integration](./docs/voice.md). +The core loop is: Telegram message → Telegram turn → queue or active dispatch → +agent lifecycle → streaming preview / native active status → final Rich Markdown +reply → optional files, voice, buttons or callback actions. Exactly one instance +owns `getUpdates` per bot; in Threaded Mode followers are visible processes the +operator started and ran `/telegram-connect` in — Telegram never launches hidden +`omp` processes. -## Safety Boundaries +
+Layout and public entrypoints -`pi-telegram` intentionally does not: +| Path | Role | +|---|---| +| `index.ts` | Composition root: wires live ports, session state, transport adapters and lifecycle hooks | +| `lib/*.ts` | Flat domain modules (queue, polling, locks, bus, menus, rendering, delivery…) forming an acyclic import graph | +| `api/*.ts` | Public companion-extension entrypoints: `inbound`, `outbound`, `delivery`, `activity`, `updates`, `commands`, `sections`, `status`, `voice`, `keyboard` | +| `docs/` | Architecture and contract documentation | +| `tests/*.test.ts` | Domain regressions run with `node --test` | -- Spawn hidden Pi follower processes. -- Pretend Telegram is a terminal or PTY. -- Forward arbitrary Telegram slash commands into the Pi TUI. -- Inject raw TTY input or terminal-control sequences. -- Replace Pi session lifecycle without an official Pi API. -- Let non-owner Telegram users control the bridge. +State: `~/.pi/agent/telegram.json` (config), `~/.pi/agent/locks.json` (polling ownership) and profile-scoped redacted `logs*.jsonl` under `tmp/telegram` (never model context). -Telegram is a companion surface around a live Pi runtime, not a second runtime. It can compact the current session, but it cannot create, resume, fork, browse, or switch sessions until Pi exposes safe public extension APIs for those operations. +Documentation: [Architecture](docs/architecture.md) · [Public API](docs/public-api.md) · [Delivery](docs/delivery.md) · [Activity](docs/activity.md) · [Inbound](docs/inbound.md) · [Outbound](docs/outbound.md) · [Voice](docs/voice.md) · [Sections](docs/sections.md) · [Updates](docs/updates.md) · [Multi-Instance Bus](docs/multi-instance-bus.md) · [Locks](docs/locks.md) · [UI Style](docs/ui-style.md) · [Callback Namespaces](docs/callback-namespaces.md) · [Command Templates](docs/command-templates.md) — index in [`docs/README.md`](docs/README.md). -A Telegram prompt is a normal model turn in the active Pi session and therefore inherits that session's active post-compaction context; the bridge does not make token cost proportional only to the new mobile message. Current releases keep per-turn guidance small and transient, with detailed bridge instructions available on demand through `telegram_help` instead of persisted in every user turn. Pi session JSONL contains model history; profile-scoped pi-telegram `logs*.jsonl` contains redacted operational events and is never model context. +
-## Documentation Map +## Limitations -- [Architecture](./docs/architecture.md) — runtime, domains, queue, transport, and Threaded Mode overview. -- [Public API](./docs/public-api.md) — package entrypoints and stable companion-extension contracts. -- [Telegram Delivery API](./docs/delivery.md) — target-aware operational views, logical message handles, and lifecycle-safe transport. -- [Telegram Activity API](./docs/activity.md) — normalized lifecycle events, source identity, non-blocking delivery contexts, and consumer policy examples. -- [Inbound Handlers](./docs/inbound.md) — Telegram-to-Pi preprocessing pipelines. -- [Outbound Handlers](./docs/outbound.md) — final text/voice/file transformation and delivery. -- [Voice Integration](./docs/voice.md) — STT/TTS provider model and reply policies. -- [Extension Sections](./docs/sections.md) — Telegram-native companion UI surfaces. -- [Updates](./docs/updates.md) — update handler registry and callback interop. -- [Multi-Instance Bus](./docs/multi-instance-bus.md) — leader/follower routing in Threaded Mode. -- [Locks](./docs/locks.md) — singleton ownership and shared lock conventions. -- [UI Style](./docs/ui-style.md) — menu, emoji, labels, dialogs, and inline keyboard standards. -- [Callback Namespaces](./docs/callback-namespaces.md) — callback ownership and routing. -- [Command Templates](./docs/command-templates.md) — handler command-template conventions. - -The docs index lives at [docs/README.md](./docs/README.md). +- Telegram is a companion surface around a live runtime, not a second runtime: no hidden `omp` processes, no PTY or fake terminal, no raw TTY input, no session replacement without an official extension API, and non-owner users cannot control the bridge. +- In Threaded Mode, threadless messages sent from the `All` tab are not routed as prompts once bound threads exist; use a bound thread tab. +- Package metadata declares the extension only under `omp.extensions` (the `pi` block was removed in `572967c`); install this fork through `omp`, and use upstream `@llblab/pi-telegram` for plain Pi. +- Open work is tracked in [`BACKLOG.md`](BACKLOG.md) (promoted-follower reload evidence, native Windows Threaded Mode follow-ups, evidence-backed Telegram client and Rich Markdown quirks). ## Development ```bash -npm run typecheck -npm test -npm run audit -npm run pack:check +npm ci +npm run typecheck # tsc --noEmit +npm test # node --experimental-strip-types --test tests/*.test.ts +npm run audit # npm audit +npm run pack:check # npm pack --dry-run +npm run validate # all of the above ``` -Full validation: +Engineering conventions: [`AGENTS.md`](AGENTS.md). Completed delivery history: [`CHANGELOG.md`](CHANGELOG.md). -```bash -npm run validate -``` +## CI/CD -Project context: +- [`.github/workflows/validate.yml`](.github/workflows/validate.yml) — on every push and pull request: Node 24, `npm ci`, `npm run validate`. +- [`.github/workflows/release.yml`](.github/workflows/release.yml) — on tags `v*.*.*`: checks that the tag matches `package.json`'s version, extracts that version's section from `CHANGELOG.md` into the release notes, and creates the release with `gh release create` (a GitHub CLI call). The extraction expects a `## ` heading; the fork's entry currently sits under `## Unreleased` as a `###` heading, so a tag would fail that check until the section is promoted. -- [AGENTS.md](./AGENTS.md) — engineering and runtime conventions. -- [BACKLOG.md](./BACKLOG.md) — release-relevant open work. -- [CHANGELOG.md](./CHANGELOG.md) — completed delivery history. +## Credits and notices + +- MIT licensed ([`LICENSE`](LICENSE)): copyright Evandro Fonseca Junior (evandrodevbr) and llblab. +- Built on [`llblab/pi-telegram`](https://github.com/llblab/pi-telegram), itself a fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram); runs inside [Oh My Pi](https://github.com/can1357/oh-my-pi) and talks to the Telegram Bot API. +- Unofficial project, not affiliated with Telegram or the Oh My Pi maintainers.