@brain0pia/pi-notify 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# `@brain0pia/pi-notify`
+
+Pi package that sends a Telegram notification after each completed Pi agent response.
+
+## Install
+
+```bash
+pi install npm:@brain0pia/pi-notify
+```
+
+For local development you can also load the package directly:
+
+```bash
+pi -e /absolute/path/to/pi-notify
+```
+
+## Configure
+
+Create `~/.pi/notify.json`:
+
+```json
+{
+  "botToken": "123456:ABCDEF...",
+  "chatId": "123456789"
+}
+```
+
+## Behavior
+
+After every `agent_end` event the extension:
+
+1. Finds the latest assistant text from the completed run.
+2. Shows a 30-second overlay countdown.
+3. Sends immediately on `Enter`.
+4. Cancels on any other key.
+5. Sends automatically when the countdown reaches zero.
+
+The Telegram payload includes metadata (`project`, `cwd`, `timestamp`, `model`) plus the full assistant output. Short outputs are sent as a MarkdownV2 message with a plain-text fallback on parse errors. Long outputs are sent as a short header message plus a `.md` attachment containing the full response.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run check
+```

package/docs/plans/2026-03-13-pi-telegram-notify-design.md

@@ -0,0 +1,321 @@
+# Pi Telegram Notify — Design
+
+Date: 2026-03-13
+Status: Approved
+Package: `@brain0pia/pi-notify`
+Install: `pi install npm:@brain0pia/pi-notify`
+
+## Goal
+
+Сделать Pi extension/package, который после каждого завершения работы агента отправляет уведомление в Telegram с markdown output.
+
+## Approved Decisions
+
+- Формат поставки: **Pi package**
+- npm package name: **`@brain0pia/pi-notify`**
+- Установка: **`pi install npm:@brain0pia/pi-notify`**
+- Исходный репозиторий: **`~/projects/pi-notify`**
+- Триггер: **каждый `agent_end`**
+- Перед отправкой: **ожидание 30 секунд**
+- UX ожидания: **overlay/countdown widget**
+- Поведение клавиш:
+  - **Enter** → скрыть виджет и **отправить** сообщение
+  - **любая другая клавиша** → скрыть виджет и **отменить** отправку
+  - **timeout** → скрыть виджет и **отправить** сообщение
+- Конфиг: **`~/.pi/notify.json`**
+- Получатель: **один** Telegram chat (`botToken` + `chatId`)
+- Содержимое уведомления: **metadata + полный последний assistant message**
+- Формат сообщения: **MarkdownV2**, при ошибке — **fallback в plain text**
+- Для длинных ответов: **короткий header + `.md` файл**
+- Для полного вложения: **`.md`**, не `.txt`
+- Конкуренция: всегда активен только **последний pending job**
+- Commit и implementation plan: **не делать** по текущему запросу пользователя
+
+## Approaches Considered
+
+### 1. `agent_end` + delay без перехвата клавиш
+Простой и надёжный путь: после `agent_end` запускать таймер и отменять только по новому user input.
+
+**Плюсы:** минимальная сложность.
+**Минусы:** не соответствует требованию отмены по любой клавише.
+
+### 2. Countdown overlay widget с фокусом (**selected**)
+После `agent_end` показывается overlay-виджет с таймером. Он получает фокус и перехватывает клавиши.
+
+**Плюсы:** точно соответствует нужному UX, хорошо укладывается в extension API Pi.
+**Минусы:** сложнее TUI-часть и управление жизненным циклом overlay.
+
+### 3. Полная временная замена editor/input-компонента
+На 30 секунд заменять обычный editor специальным компонентом для полного контроля над клавишами.
+
+**Плюсы:** максимальный контроль ввода.
+**Минусы:** слишком инвазивно, выше риск ломать привычный UX и совместимость.
+
+## Recommended Architecture
+
+Пакет состоит из extension и нескольких внутренних модулей.
+
+### 1. Config loader
+Отвечает за чтение и валидацию `~/.pi/notify.json`.
+
+Responsibilities:
+- читать JSON-конфиг
+- валидировать `botToken` и `chatId`
+- возвращать нормализованный config
+- при ошибке отключать отправку без падения extension
+
+### 2. Agent event controller
+Подписывается на `agent_end`.
+
+Responsibilities:
+- находить последний assistant message текущего прогона
+- собирать metadata
+- создавать pending notification job
+- отменять предыдущий job, если приходит новый `agent_end`
+- координировать overlay, timer и отправку
+
+### 3. Countdown widget / input gate
+UI-слой для 30-секундного ожидания.
+
+Responsibilities:
+- отображать countdown overlay
+- обновлять таймер на экране
+- принимать key input
+- интерпретировать `Enter` как send
+- интерпретировать любую другую клавишу как cancel
+- скрывать себя при cancel/send/timeout
+
+### 4. Telegram delivery
+Интеграция с Telegram Bot API.
+
+Responsibilities:
+- собирать итоговый payload
+- отправлять short message через `sendMessage`
+- отправлять `.md` файл через `sendDocument`, если output слишком длинный
+- делать fallback с MarkdownV2 на plain text
+- безопасно обрабатывать API errors
+
+### 5. Formatting helpers
+Утилиты для подготовки текста.
+
+Responsibilities:
+- сборка metadata header
+- escape для Telegram MarkdownV2
+- определение, помещается ли ответ в одно сообщение
+- сборка markdown-файла для длинного output
+
+## Repository Structure
+
+Предлагаемая структура `~/projects/pi-notify`:
+
+```text
+~/projects/pi-notify/
+  package.json
+  README.md
+  src/
+    index.ts
+    config.ts
+    countdown.ts
+    telegram.ts
+    format.ts
+  docs/
+    plans/
+      2026-03-13-pi-telegram-notify-design.md
+```
+
+## Pi Package Structure
+
+`package.json` должен объявлять пакет как Pi package.
+
+Expected package metadata:
+- name: `@brain0pia/pi-notify`
+- keywords: include `pi-package`
+- `pi.extensions`: path to extension entrypoint
+- peerDependencies: Pi core packages with `"*"` range
+
+## Runtime Data Flow
+
+### Normal flow
+1. Пользователь отправляет prompt в Pi.
+2. Pi завершает ответ, срабатывает `agent_end`.
+3. Extension находит последний assistant message.
+4. Extension собирает metadata:
+   - cwd / project
+   - timestamp
+   - model (если доступен)
+5. Extension создаёт новый notification job.
+6. Если был предыдущий активный job, он отменяется.
+7. Показывается countdown overlay на 30 секунд.
+8. Дальше возможны три исхода:
+   - **Enter** → overlay закрывается, сообщение сразу отправляется
+   - **другая клавиша** → overlay закрывается, отправка отменяется
+   - **timeout** → overlay закрывается, сообщение отправляется автоматически
+
+### Outgoing Telegram content
+
+#### Short output
+Отправляется одним сообщением:
+- header с metadata
+- затем полный assistant output
+
+Flow:
+1. try `sendMessage` with MarkdownV2
+2. if parse error → retry as plain text
+
+#### Long output
+Если текст не помещается в лимиты Telegram:
+- сначала отправляется короткий header/message
+- затем отправляется `.md` document с полным output
+
+## Overlay UX
+
+Виджет должен:
+- явно показывать, что агент закончил работу
+- показывать countdown от 30 до 0
+- объяснять действия клавиш
+- скрываться в трёх сценариях: cancel, immediate send, timeout send
+
+Suggested text shape:
+- title: `Pi finished`
+- body: `Sending to Telegram in 30s`
+- hints:
+  - `Enter — send now`
+  - `Any other key — cancel`
+
+## State Model
+
+In-memory state достаточно.
+
+Proposed active state:
+- `activeJobId`
+- `activeTimer`
+- `activeOverlayHandle`
+- `activePayload`
+- `activeStatus`
+- flags: `cancelled`, `sent`
+
+Никакое persistent storage для отложенных уведомлений не требуется.
+
+## Concurrency Rules
+
+Нужно избегать двойной отправки и гонок.
+
+Rules:
+- у каждого job есть уникальный `jobId`
+- любой callback (keypress, timeout, send completion) сначала проверяет, что его `jobId` всё ещё активен
+- новый `agent_end` отменяет предыдущий pending job
+- старые callbacks после отмены ничего не делают
+
+## Error Handling
+
+### Config errors
+Если `~/.pi/notify.json`:
+- не существует
+- битый JSON
+- не содержит `botToken` или `chatId`
+
+Then:
+- extension не падает
+- отправка отключается
+- пользователю показывается локальное предупреждение через `ctx.ui.notify(...)`
+
+### Overlay errors
+Если overlay не удалось показать:
+- extension не должен ломать сессию Pi
+- fallback: таймер продолжает жить в фоне
+- по timeout выполняется обычная отправка
+- просто недоступна keyboard cancellation для этого конкретного job
+
+### Telegram API errors
+Cases:
+- network failure
+- 401 / 403 auth or chat access errors
+- 400 markdown parse error
+- 429 rate limit
+- 5xx remote server error
+
+Behavior:
+1. сначала пробовать MarkdownV2
+2. при markdown parse error → fallback to plain text
+3. при oversized body → header + `.md` file
+4. при финальной ошибке → локальное уведомление в Pi + no crash
+5. бесконечные retry не делать
+
+### Shutdown / reload
+При завершении Pi или reload extension:
+- pending timer отменяется
+- overlay/status очищаются
+- недоотправленные уведомления не восстанавливаются
+
+## Config Shape
+
+Планируемый минимальный формат `~/.pi/notify.json`:
+
+```json
+{
+  "botToken": "123456:ABCDEF...",
+  "chatId": "123456789"
+}
+```
+
+Дополнительные поля не требуются для первой версии.
+
+## Testing Strategy
+
+### 1. Config tests
+Проверить:
+- valid config
+- missing file
+- invalid JSON
+- missing required fields
+
+### 2. Countdown UX tests
+Проверить:
+- overlay появляется после `agent_end`
+- countdown обновляется
+- `Enter` скрывает виджет и отправляет
+- другая клавиша скрывает виджет и отменяет
+- timeout скрывает виджет и отправляет
+- новый `agent_end` отменяет старый countdown
+
+### 3. Formatting tests
+Проверить:
+- metadata header собирается корректно
+- MarkdownV2 escaping корректен
+- fallback в plain text работает
+- длинный output переводится в `.md` document flow
+
+### 4. Telegram integration tests
+Проверить:
+- success path for `sendMessage`
+- success path for `sendDocument`
+- 401/403/429/5xx handled safely
+- ошибки не ломают Pi session
+
+### 5. Packaging smoke tests
+Проверить:
+- package installs as `pi install npm:@brain0pia/pi-notify`
+- Pi discovers extension from package manifest
+- runtime dependencies resolve correctly
+
+## Success Criteria
+
+Задача считается успешной, если:
+- пакет устанавливается как `pi install npm:@brain0pia/pi-notify`
+- после каждого ответа Pi появляется countdown-виджет
+- `Enter` отправляет уведомление сразу
+- любая другая клавиша отменяет отправку
+- timeout автоматически отправляет уведомление
+- Telegram получает metadata + output
+- длинные ответы приходят как short message + `.md` file
+- ошибки конфига и Telegram не ломают работу Pi
+
+## Out of Scope
+
+В первой версии не включаем:
+- несколько Telegram recipients
+- несколько профилей/config presets
+- retries с backoff и очередями доставки
+- восстановление pending notifications после рестарта Pi
+- commit design doc
+- implementation plan

package/execplan/2026-03-13-pi-telegram-notify-implementation.md

@@ -0,0 +1,143 @@
+# Build and ship the `@brain0pia/pi-notify` Telegram notifier package
+
+This ExecPlan is a living document. The sections `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` must be kept up to date as work proceeds.
+
+This document must be maintained in accordance with `/home/bot/.pi/agent/skills/pi-skills-with-self-analysis/execplan/references/PLANS.md`.
+
+## Purpose / Big Picture
+
+After this change, Pi users can install `@brain0pia/pi-notify` as a Pi package, configure a Telegram bot in `~/.pi/notify.json`, and automatically receive the final assistant output after each completed agent run. The user-visible behavior is a 30-second countdown overlay: pressing Enter sends immediately, pressing any other key cancels, and letting the countdown expire sends automatically. The way to see it working is to load the package in Pi, trigger an assistant response, watch the overlay appear in interactive mode, and verify that the extension either sends the Telegram notification or cancels it according to the chosen key.
+
+## Progress
+
+- [x] (2026-03-13 18:01 UTC+8) Read the approved design in `docs/plans/2026-03-13-pi-telegram-notify-design.md`, read the ExecPlan methodology in `PLANS.md`, and reviewed the Pi package, extension, TUI, and SDK documentation plus relevant extension examples.
+- [x] (2026-03-13 18:04 UTC+8) Created the npm/package scaffold (`package.json`, `README.md`, `.gitignore`, `tsconfig.json`) plus source and test directories.
+- [x] (2026-03-13 18:05 UTC+8) Implemented the config loader, formatting helpers, Telegram transport, countdown overlay, controller, and extension entrypoint in `src/`.
+- [x] (2026-03-13 18:06 UTC+8) Added automated tests for config parsing, formatting, Telegram fallback/document delivery, and controller behavior in `test/`.
+- [x] (2026-03-13 18:07 UTC+8) Installed dependencies, fixed the initial version mismatch in `package.json`, and ran `npm run check`, `npm test`, and the local Pi smoke test successfully.
+- [x] (2026-03-13 18:08 UTC+8) Initialized git, committed the repository, created the public GitHub repository with `gh`, and updated package metadata to the actual remote URL.
+- [x] (2026-03-13 18:08 UTC+8) Updated this ExecPlan with final results, validation evidence, repository URL, and implementation notes.
+
+## Surprises & Discoveries
+
+- Observation: the target directory already existed and already contained the approved design document, but it was not yet a git repository.
+  Evidence: `/home/bot/projects/pi-notify` initially contained only `docs/` and `git status` returned `fatal: not a git repository`.
+- Observation: the npm versions suggested by nearby example packages were not available for `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui`; the currently published version is `0.57.1`.
+  Evidence: `npm install` failed with `No matching version found for @mariozechner/pi-coding-agent@^1.21.1`, and `npm view @mariozechner/pi-coding-agent version` returned `0.57.1`.
+- Observation: the active GitHub account available through `gh` is `brainopia`, not `brain0pia`, so the repository had to be created under `brainopia/pi-notify` even though the npm package scope remains `@brain0pia`.
+  Evidence: `gh repo create brain0pia/pi-notify --public ...` returned `HTTP 404`, while `gh repo create brainopia/pi-notify --public ...` succeeded and `gh repo view brainopia/pi-notify` shows a public repository.
+
+## Decision Log
+
+- Decision: keep the package as a TypeScript Pi package that ships the extension source directly instead of adding a build step.
+  Rationale: Pi loads extensions through `jiti`, the design already targets `src/*.ts`, and skipping a compile step keeps the package simpler for installation and maintenance.
+  Date/Author: 2026-03-13 / OpenAI Codex
+- Decision: implement the notification orchestration in a controller module with small helper modules for config, formatting, Telegram transport, and overlay UI.
+  Rationale: the behavior includes concurrency, timers, and fallback paths, so a controller boundary makes the code easier to test without depending on a live Pi runtime.
+  Date/Author: 2026-03-13 / OpenAI Codex
+- Decision: keep the npm package scope as `@brain0pia/pi-notify` from the approved design, but publish the GitHub repository under the authenticated account `brainopia/pi-notify`.
+  Rationale: the design fixes the package name, while GitHub repository ownership must match the available authenticated account in `gh`.
+  Date/Author: 2026-03-13 / OpenAI Codex
+- Decision: use conservative local tests with mocked `fetch` and injected timer/countdown dependencies instead of trying to hit the real Telegram API during repository validation.
+  Rationale: the repository should validate without secrets, and the mocked tests still prove Markdown fallback, long-output document delivery, and pending-job replacement behavior.
+  Date/Author: 2026-03-13 / OpenAI Codex
+
+## Outcomes & Retrospective
+
+Implementation complete. The repository now contains a working Pi package with a focused module layout, automated tests, and the approved Telegram-notification behavior. The package reads `~/.pi/notify.json`, extracts the final assistant text on `agent_end`, shows an interactive countdown overlay in UI mode, falls back to background timeout delivery when overlay UI is unavailable, and sends Telegram notifications with MarkdownV2 first and plain text second. Long outputs are routed through a short header message plus a `.md` attachment.
+
+The acceptance criteria that could be verified locally are met. `npm run check` passes, `npm test` passes all 18 tests, and `pi -e /home/bot/projects/pi-notify -p "Reply with OK only."` returns `OK`, proving that Pi can load the package from a local path without crashing. The repository is public at `https://github.com/brainopia/pi-notify`. The main remaining work outside this repository is operational rather than implementation-related: a real user still needs to provide a valid `~/.pi/notify.json` and a reachable Telegram bot/chat pair to observe live delivery against the Telegram API.
+
+## Context and Orientation
+
+The repository root is `/home/bot/projects/pi-notify`. The approved design source remains `docs/plans/2026-03-13-pi-telegram-notify-design.md`. The package metadata lives in `package.json`; it declares the Pi extension entrypoint through `pi.extensions` and keeps the package name as `@brain0pia/pi-notify`. The extension entrypoint is `src/index.ts`, which registers the runtime hooks and delegates work to `src/controller.ts`.
+
+The code is organized so a newcomer can reason about the feature one layer at a time. `src/config.ts` reads and validates `~/.pi/notify.json`. `src/format.ts` builds the metadata header, Telegram-safe MarkdownV2 strings, short-message detection, and `.md` attachment content. `src/telegram.ts` talks to the Telegram Bot API using `sendMessage` and `sendDocument`, including Markdown parse-error fallback and automatic long-output attachment flow. `src/countdown.ts` implements the overlay component and keyboard handling through `ctx.ui.custom(..., { overlay: true })`. `src/controller.ts` owns the in-memory state machine that extracts assistant text, prevents multiple pending jobs, schedules background sends when needed, and reports local warnings without crashing Pi. The tests under `test/` mock the edges of the system so the behavior can be validated without external credentials.
+
+## Plan of Work
+
+The implementation was completed in four layers. First, the repository was turned into a standard npm and git project with Pi package metadata, a README, TypeScript settings, and a committed lockfile. Second, the runtime modules were added so each piece of behavior has a narrow responsibility: config parsing, formatting, Telegram transport, countdown overlay, and orchestration. Third, the behavior was covered with isolated tests so the most failure-prone flows—missing config, Markdown parse fallback, oversized outputs, and pending-job replacement—can be revalidated on every change. Fourth, the repository was initialized as a public GitHub repository with `gh` and pushed to `main`.
+
+The implementation stays close to the approved design but resolves a few practical details explicitly. The repository owner had to be `brainopia` because that is the authenticated GitHub account. The package still uses the `@brain0pia` npm scope because that was an approved design requirement and is independent of the GitHub owner. The overlay uses Pi’s centered overlay mode with a bordered component so keyboard capture remains local to the countdown UI. Background delivery remains in-memory only, which matches the design’s “no persistence for pending jobs” rule.
+
+## Concrete Steps
+
+Work from `/home/bot/projects/pi-notify`.
+
+1. Initialize the repository and scaffold package files.
+2. Add the source files under `src/` and tests under `test/`.
+3. Install dependencies and run validation.
+4. Commit the result and publish the repository with `gh`.
+
+Commands executed during implementation:
+
+    cd /home/bot/projects/pi-notify
+    npm install
+    npm run check
+    npm test
+    pi -e /home/bot/projects/pi-notify -p "Reply with OK only."
+    git init -b main
+    git add .
+    git commit -m "Initial pi-notify package"
+    gh repo create brainopia/pi-notify --public --source=. --remote=origin --push
+
+Important observed outputs:
+
+    npm run check
+    > tsc --noEmit
+
+    npm test
+    ✔ 18 tests passed
+
+    pi -e /home/bot/projects/pi-notify -p "Reply with OK only."
+    OK
+
+    gh repo view brainopia/pi-notify --json name,visibility,url,owner
+    {"name":"pi-notify","owner":{"login":"brainopia"},"url":"https://github.com/brainopia/pi-notify","visibility":"PUBLIC"}
+
+## Validation and Acceptance
+
+Acceptance is met for the repository-backed implementation. The package loads in Pi from a local path, the TypeScript check passes, and the automated test suite passes. The implemented behavior matches the approved design in the source and tests: `src/controller.ts` enforces a single active pending job, `src/countdown.ts` maps Enter to immediate send and all other keys to cancel, `src/telegram.ts` retries with plain text on Telegram Markdown parse errors, and `src/format.ts` routes oversized outputs to a `.md` attachment flow.
+
+The exact validation commands and results are:
+
+- `cd /home/bot/projects/pi-notify && npm run check` → success, no TypeScript errors.
+- `cd /home/bot/projects/pi-notify && npm test` → success, 18 tests passed.
+- `cd /home/bot/projects/pi-notify && pi -e /home/bot/projects/pi-notify -p "Reply with OK only."` → success, output was `OK`.
+- `gh repo view brainopia/pi-notify --json name,visibility,url,owner` → success, repository is public at `https://github.com/brainopia/pi-notify`.
+
+A live Telegram end-to-end send was not executed in this repository session because that requires valid external credentials in `~/.pi/notify.json`. The code paths for that behavior are covered by mocked tests and are ready for manual verification once credentials are added.
+
+## Idempotence and Recovery
+
+The repository setup is safe to repeat. Re-running `npm install`, `npm run check`, `npm test`, or the local Pi smoke test is idempotent. If `gh repo create` is re-run after the repository already exists, the safe recovery path is to use the existing remote (`origin`) and push normally. The runtime implementation is also idempotent by design: only the latest pending notification stays active, cancelled jobs clear their timers, and `session_shutdown` cancels any in-memory pending work without trying to replay it later.
+
+If Telegram delivery fails at runtime, the extension reports a local warning through `ctx.ui.notify(...)` and does not crash Pi. If overlay creation fails, the controller falls back to background timeout delivery and still keeps only one pending job active.
+
+## Artifacts and Notes
+
+Important evidence captured during implementation:
+
+    - `npm run check` passed with no TypeScript errors.
+    - `npm test` passed with 18 tests.
+    - Local Pi smoke test: `pi -e /home/bot/projects/pi-notify -p "Reply with OK only."` returned `OK`.
+    - Public repository: `https://github.com/brainopia/pi-notify`.
+    - Initial implementation commit: `ee9bdcb` (`Initial pi-notify package`).
+
+The working tree should be clean after committing the final metadata update and ExecPlan revision.
+
+## Interfaces and Dependencies
+
+The package exports the default Pi extension factory from `src/index.ts`:
+
+    export default function registerPiNotify(pi: ExtensionAPI): void
+
+`src/config.ts` exposes `loadNotifyConfig()` and `validateNotifyConfig()` to normalize `botToken` and `chatId` from `~/.pi/notify.json`.
+
+`src/controller.ts` exports `PiNotifyController`, `extractAssistantText()`, and `createNotificationPayload()`. The controller accepts the `agent_end` message list plus `ExtensionContext`, extracts the latest assistant message, and ensures that only one pending notification job is active at a time.
+
+`src/telegram.ts` exports `sendTelegramNotification()` and uses the Telegram Bot API methods `sendMessage` and `sendDocument` over `fetch`. `src/countdown.ts` exports `showCountdownOverlay()` and uses Pi overlay UI plus `@mariozechner/pi-tui` keyboard helpers. `package.json` declares `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` as peer dependencies and development dependencies so the package works inside Pi and can also be type-checked locally.
+
+Plan created on 2026-03-13 because the user explicitly requested an ExecPlan-backed implementation based on the approved Telegram notify design.
+
+Revision note (2026-03-13): updated after implementation to record the finished source layout, dependency version correction, validation commands/results, GitHub ownership adjustment (`brainopia/pi-notify`), and the public repository URL.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@brain0pia/pi-notify",
+  "version": "0.1.0",
+  "description": "Pi package that sends Telegram notifications after each completed agent response.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "telegram",
+    "notifications"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brainopia/pi-notify.git"
+  },
+  "homepage": "https://github.com/brainopia/pi-notify#readme",
+  "bugs": {
+    "url": "https://github.com/brainopia/pi-notify/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "docs",
+    "execplan"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.57.1",
+    "@mariozechner/pi-tui": "^0.57.1",
+    "@types/node": "^24.5.2",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/**/*.test.ts"
+  }
+}

package/src/config.ts

@@ -0,0 +1,67 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import type { ConfigLoadResult } from "./types.js";
+
+export const NOTIFY_CONFIG_PATH = path.join(homedir(), ".pi", "notify.json");
+
+export function validateNotifyConfig(value: unknown, configPath = NOTIFY_CONFIG_PATH): ConfigLoadResult {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, reason: `pi-notify: expected an object in ${configPath}.` };
+  }
+
+  const record = value as Record<string, unknown>;
+  const botToken = typeof record.botToken === "string" ? record.botToken.trim() : "";
+  const chatIdValue = record.chatId;
+  const chatId =
+    typeof chatIdValue === "string"
+      ? chatIdValue.trim()
+      : typeof chatIdValue === "number" && Number.isFinite(chatIdValue)
+        ? String(chatIdValue)
+        : "";
+
+  if (!botToken) {
+    return { ok: false, reason: `pi-notify: missing \"botToken\" in ${configPath}.` };
+  }
+
+  if (!botToken.includes(":")) {
+    return { ok: false, reason: `pi-notify: botToken in ${configPath} does not look like a Telegram bot token.` };
+  }
+
+  if (!chatId) {
+    return { ok: false, reason: `pi-notify: missing \"chatId\" in ${configPath}.` };
+  }
+
+  return {
+    ok: true,
+    config: {
+      botToken,
+      chatId,
+    },
+  };
+}
+
+export async function loadNotifyConfig(configPath = NOTIFY_CONFIG_PATH): Promise<ConfigLoadResult> {
+  let raw: string;
+
+  try {
+    raw = await readFile(configPath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { ok: false, reason: `pi-notify: config file not found at ${configPath}.` };
+    }
+
+    throw error;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, reason: `pi-notify: invalid JSON in ${configPath}: ${message}` };
+  }
+
+  return validateNotifyConfig(parsed, configPath);
+}

package/src/controller.ts

@@ -0,0 +1,251 @@
+import path from "node:path";
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { loadNotifyConfig } from "./config.js";
+import { showCountdownOverlay, type CountdownOverlayOptions } from "./countdown.js";
+import { sendTelegramNotification } from "./telegram.js";
+import type { ConfigLoadResult, CountdownDecision, NotificationPayload, NotifyConfig } from "./types.js";
+
+interface TextContentLike {
+  type?: string;
+  text?: string;
+}
+
+export interface AgentMessageLike {
+  role?: string;
+  content?: unknown;
+}
+
+export interface PiNotifyControllerDependencies {
+  delayMs?: number;
+  loadConfig?: () => Promise<ConfigLoadResult>;
+  showCountdown?: (ctx: ExtensionContext, options: CountdownOverlayOptions) => Promise<CountdownDecision>;
+  sendNotification?: (config: NotifyConfig, payload: NotificationPayload) => Promise<unknown>;
+  setTimeoutFn?: typeof setTimeout;
+  clearTimeoutFn?: typeof clearTimeout;
+  now?: () => Date;
+}
+
+interface ActiveJob {
+  id: number;
+  cancel?: () => void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+function isTextContent(value: unknown): value is TextContentLike {
+  return typeof value === "object" && value !== null && (value as { type?: string }).type === "text";
+}
+
+export function extractAssistantText(messages: readonly AgentMessageLike[]): string | null {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) {
+      continue;
+    }
+
+    const text = message.content
+      .filter(isTextContent)
+      .map((block) => block.text ?? "")
+      .join("\n")
+      .trim();
+
+    if (text.length > 0) {
+      return text;
+    }
+  }
+
+  return null;
+}
+
+export function createNotificationPayload(
+  messages: readonly AgentMessageLike[],
+  ctx: Pick<ExtensionContext, "cwd" | "model">,
+  now: Date,
+): NotificationPayload | null {
+  const assistantText = extractAssistantText(messages);
+  if (!assistantText) {
+    return null;
+  }
+
+  const cwd = ctx.cwd;
+  const basename = path.basename(cwd);
+  const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+
+  return {
+    metadata: {
+      project: basename.length > 0 ? basename : cwd,
+      cwd,
+      timestamp: now.toISOString(),
+      model,
+    },
+    assistantText,
+  };
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export class PiNotifyController {
+  private readonly delayMs: number;
+  private readonly loadConfig: () => Promise<ConfigLoadResult>;
+  private readonly showCountdown: (ctx: ExtensionContext, options: CountdownOverlayOptions) => Promise<CountdownDecision>;
+  private readonly sendNotification: (config: NotifyConfig, payload: NotificationPayload) => Promise<unknown>;
+  private readonly setTimeoutFn: typeof setTimeout;
+  private readonly clearTimeoutFn: typeof clearTimeout;
+  private readonly now: () => Date;
+
+  private activeJob: ActiveJob | null = null;
+  private nextJobId = 0;
+  private lastConfigWarning: string | null = null;
+
+  constructor(dependencies: PiNotifyControllerDependencies = {}) {
+    this.delayMs = dependencies.delayMs ?? 30_000;
+    this.loadConfig = dependencies.loadConfig ?? loadNotifyConfig;
+    this.showCountdown = dependencies.showCountdown ?? showCountdownOverlay;
+    this.sendNotification = dependencies.sendNotification ?? sendTelegramNotification;
+    this.setTimeoutFn = dependencies.setTimeoutFn ?? setTimeout;
+    this.clearTimeoutFn = dependencies.clearTimeoutFn ?? clearTimeout;
+    this.now = dependencies.now ?? (() => new Date());
+  }
+
+  async handleAgentEnd(messages: readonly AgentMessageLike[], ctx: ExtensionContext): Promise<void> {
+    const payload = createNotificationPayload(messages, ctx, this.now());
+    if (!payload) {
+      return;
+    }
+
+    const configResult = await this.loadConfig();
+    if (!configResult.ok) {
+      this.warnMissingConfig(ctx, configResult.reason);
+      return;
+    }
+
+    this.lastConfigWarning = null;
+    const job = this.startNewJob();
+
+    if (!ctx.hasUI) {
+      this.scheduleBackgroundSend(job, ctx, configResult.config, payload);
+      return;
+    }
+
+    try {
+      const decision = await this.showCountdown(ctx, {
+        delayMs: this.delayMs,
+        registerCancel: (cancel) => {
+          job.cancel = cancel;
+        },
+      });
+
+      if (!this.isActive(job.id)) {
+        return;
+      }
+
+      this.finishJob(job.id);
+      if (decision === "send" || decision === "timeout") {
+        await this.deliver(configResult.config, payload, ctx);
+      }
+    } catch (error) {
+      if (!this.isActive(job.id)) {
+        return;
+      }
+
+      this.notify(ctx, `pi-notify: overlay unavailable, sending automatically in ${Math.ceil(this.delayMs / 1000)}s.`, "warning");
+      this.scheduleBackgroundSend(job, ctx, configResult.config, payload);
+      const description = describeError(error);
+      if (description) {
+        this.notify(ctx, `pi-notify: overlay error: ${description}`, "warning");
+      }
+    }
+  }
+
+  shutdown(): void {
+    this.cancelActiveJob();
+  }
+
+  private startNewJob(): ActiveJob {
+    this.cancelActiveJob();
+    const job: ActiveJob = {
+      id: ++this.nextJobId,
+    };
+    this.activeJob = job;
+    return job;
+  }
+
+  private cancelActiveJob(): void {
+    const job = this.activeJob;
+    this.activeJob = null;
+
+    if (!job) {
+      return;
+    }
+
+    if (job.timer) {
+      this.clearTimeoutFn(job.timer);
+    }
+
+    job.cancel?.();
+  }
+
+  private scheduleBackgroundSend(
+    job: ActiveJob,
+    ctx: ExtensionContext,
+    config: NotifyConfig,
+    payload: NotificationPayload,
+  ): void {
+    job.cancel = () => {
+      if (job.timer) {
+        this.clearTimeoutFn(job.timer);
+      }
+    };
+
+    job.timer = this.setTimeoutFn(async () => {
+      if (!this.isActive(job.id)) {
+        return;
+      }
+
+      this.finishJob(job.id);
+      await this.deliver(config, payload, ctx);
+    }, this.delayMs);
+  }
+
+  private finishJob(jobId: number): void {
+    if (this.activeJob?.id !== jobId) {
+      return;
+    }
+
+    const timer = this.activeJob.timer;
+    this.activeJob = null;
+    if (timer) {
+      this.clearTimeoutFn(timer);
+    }
+  }
+
+  private isActive(jobId: number): boolean {
+    return this.activeJob?.id === jobId;
+  }
+
+  private async deliver(config: NotifyConfig, payload: NotificationPayload, ctx: ExtensionContext): Promise<void> {
+    try {
+      await this.sendNotification(config, payload);
+    } catch (error) {
+      this.notify(ctx, `pi-notify: Telegram delivery failed: ${describeError(error)}`, "warning");
+    }
+  }
+
+  private warnMissingConfig(ctx: ExtensionContext, reason: string): void {
+    if (this.lastConfigWarning === reason) {
+      return;
+    }
+
+    this.lastConfigWarning = reason;
+    this.notify(ctx, reason, "warning");
+  }
+
+  private notify(ctx: ExtensionContext, message: string, type: "info" | "warning" | "error"): void {
+    if (ctx.hasUI) {
+      ctx.ui.notify(message, type);
+    }
+  }
+}

package/src/countdown.ts

@@ -0,0 +1,120 @@
+import type { ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import type { Component, TUI } from "@mariozechner/pi-tui";
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+import type { CountdownDecision } from "./types.js";
+
+export interface CountdownOverlayOptions {
+  delayMs: number;
+  registerCancel?: (cancel: () => void) => void;
+}
+
+function clampRemainingSeconds(targetTime: number): number {
+  return Math.max(0, Math.ceil((targetTime - Date.now()) / 1000));
+}
+
+class CountdownOverlayComponent implements Component {
+  private readonly targetTime: number;
+  private readonly interval: NodeJS.Timeout;
+  private closed = false;
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: Theme,
+    delayMs: number,
+    private readonly finish: (decision: CountdownDecision) => void,
+  ) {
+    this.targetTime = Date.now() + delayMs;
+    this.interval = setInterval(() => {
+      if (this.closed) {
+        return;
+      }
+
+      if (clampRemainingSeconds(this.targetTime) <= 0) {
+        this.finish("timeout");
+        return;
+      }
+
+      this.tui.requestRender();
+    }, 250);
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.enter)) {
+      this.finish("send");
+      return;
+    }
+
+    this.finish("cancel");
+  }
+
+  render(width: number): string[] {
+    const outerWidth = Math.max(28, width);
+    const innerWidth = Math.max(26, outerWidth - 2);
+    const remaining = clampRemainingSeconds(this.targetTime);
+    const title = this.theme.fg("accent", this.theme.bold("Pi finished"));
+    const body = this.theme.fg("text", `Sending to Telegram in ${remaining}s`);
+    const hintSend = this.theme.fg("success", "Enter — send now");
+    const hintCancel = this.theme.fg("warning", "Any other key — cancel");
+
+    const pad = (value: string): string => {
+      const visible = visibleWidth(value);
+      return value + " ".repeat(Math.max(0, innerWidth - visible));
+    };
+
+    const row = (value = ""): string => {
+      const trimmed = truncateToWidth(value, innerWidth, "");
+      return this.theme.fg("borderAccent", "│") + pad(trimmed) + this.theme.fg("borderAccent", "│");
+    };
+
+    return [
+      this.theme.fg("borderAccent", `╭${"─".repeat(innerWidth)}╮`),
+      row(` ${title}`),
+      row(""),
+      row(` ${body}`),
+      row(""),
+      row(` ${hintSend}`),
+      row(` ${hintCancel}`),
+      this.theme.fg("borderAccent", `╰${"─".repeat(innerWidth)}╯`),
+    ];
+  }
+
+  invalidate(): void {}
+
+  dispose(): void {
+    this.closed = true;
+    clearInterval(this.interval);
+  }
+}
+
+export async function showCountdownOverlay(
+  ctx: ExtensionContext,
+  options: CountdownOverlayOptions,
+): Promise<CountdownDecision> {
+  return ctx.ui.custom<CountdownDecision>(
+    (tui, theme, _keybindings, done) => {
+      let completed = false;
+      const finish = (decision: CountdownDecision) => {
+        if (completed) {
+          return;
+        }
+
+        completed = true;
+        done(decision);
+      };
+
+      options.registerCancel?.(() => finish("replaced"));
+
+      return new CountdownOverlayComponent(tui, theme, options.delayMs, finish);
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: 40,
+        maxHeight: 10,
+        margin: 1,
+      },
+    },
+  );
+}

package/src/format.ts

@@ -0,0 +1,93 @@
+import type { NotificationMetadata, NotificationPayload } from "./types.js";
+
+export const TELEGRAM_MESSAGE_LIMIT = 4096;
+const EMPTY_ASSISTANT_MESSAGE = "(assistant message was empty)";
+
+const MARKDOWN_V2_SPECIALS = /[\\_*\[\]()~`>#+\-=|{}.!]/g;
+
+function normalizeAssistantText(text: string): string {
+  const normalized = text.trim();
+  return normalized.length > 0 ? normalized : EMPTY_ASSISTANT_MESSAGE;
+}
+
+function metadataLines(metadata: NotificationMetadata): string[] {
+  return [
+    `Project: ${metadata.project}`,
+    `CWD: ${metadata.cwd}`,
+    `Time: ${metadata.timestamp}`,
+    ...(metadata.model ? [`Model: ${metadata.model}`] : []),
+  ];
+}
+
+export function escapeMarkdownV2(text: string): string {
+  return text.replace(MARKDOWN_V2_SPECIALS, (char) => `\\${char}`);
+}
+
+export function buildPlainTextMessage(payload: NotificationPayload): string {
+  return [
+    "Pi finished",
+    ...metadataLines(payload.metadata),
+    "",
+    normalizeAssistantText(payload.assistantText),
+  ].join("\n");
+}
+
+export function buildMarkdownMessage(payload: NotificationPayload): string {
+  const assistantText = escapeMarkdownV2(normalizeAssistantText(payload.assistantText));
+  const metadata = [
+    "*Pi finished*",
+    ...metadataLines(payload.metadata).map((line) => escapeMarkdownV2(line)),
+    "",
+    assistantText,
+  ];
+
+  return metadata.join("\n");
+}
+
+export function buildLongOutputPlainTextNotice(payload: NotificationPayload): string {
+  return [
+    "Pi finished",
+    ...metadataLines(payload.metadata),
+    "",
+    "Full output attached as pi-notify-output.md",
+  ].join("\n");
+}
+
+export function buildLongOutputMarkdownNotice(payload: NotificationPayload): string {
+  return [
+    "*Pi finished*",
+    ...metadataLines(payload.metadata).map((line) => escapeMarkdownV2(line)),
+    "",
+    escapeMarkdownV2("Full output attached as pi-notify-output.md"),
+  ].join("\n");
+}
+
+export function buildAttachmentFilename(metadata: NotificationMetadata): string {
+  const sanitized = metadata.timestamp.replace(/[:]/g, "-");
+  return `pi-notify-${sanitized}.md`;
+}
+
+export function buildAttachmentMarkdown(payload: NotificationPayload): string {
+  const modelLine = payload.metadata.model ? `- Model: ${payload.metadata.model}` : undefined;
+
+  return [
+    "# Pi finished",
+    "",
+    `- Project: ${payload.metadata.project}`,
+    `- CWD: ${payload.metadata.cwd}`,
+    `- Time: ${payload.metadata.timestamp}`,
+    ...(modelLine ? [modelLine] : []),
+    "",
+    "## Assistant output",
+    "",
+    normalizeAssistantText(payload.assistantText),
+    "",
+  ].join("\n");
+}
+
+export function shouldSendAsDocument(payload: NotificationPayload): boolean {
+  return (
+    buildPlainTextMessage(payload).length > TELEGRAM_MESSAGE_LIMIT ||
+    buildMarkdownMessage(payload).length > TELEGRAM_MESSAGE_LIMIT
+  );
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { PiNotifyController } from "./controller.js";
+
+export default function registerPiNotify(pi: ExtensionAPI): void {
+  const controller = new PiNotifyController();
+
+  pi.on("agent_end", async (event, ctx) => {
+    await controller.handleAgentEnd(event.messages, ctx);
+  });
+
+  pi.on("session_shutdown", async () => {
+    controller.shutdown();
+  });
+}

package/src/telegram.ts

@@ -0,0 +1,139 @@
+import {
+  buildAttachmentFilename,
+  buildAttachmentMarkdown,
+  buildLongOutputMarkdownNotice,
+  buildLongOutputPlainTextNotice,
+  buildMarkdownMessage,
+  buildPlainTextMessage,
+  shouldSendAsDocument,
+} from "./format.js";
+import type { NotificationPayload, NotifyConfig } from "./types.js";
+
+export interface TelegramSendResult {
+  mode: "message" | "document";
+}
+
+export class TelegramApiError extends Error {
+  constructor(
+    public readonly method: string,
+    public readonly status: number,
+    public readonly description: string,
+    public readonly errorCode?: number,
+  ) {
+    super(`Telegram ${method} failed (${status}): ${description}`);
+    this.name = "TelegramApiError";
+  }
+}
+
+function telegramUrl(config: NotifyConfig, method: string): string {
+  return `https://api.telegram.org/bot${config.botToken}/${method}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isMarkdownParseError(error: TelegramApiError): boolean {
+  return /parse entities|can't parse entities/i.test(error.description);
+}
+
+function isMessageTooLong(error: TelegramApiError): boolean {
+  return /message is too long/i.test(error.description);
+}
+
+async function parseTelegramResponse(response: Response, method: string): Promise<unknown> {
+  const text = await response.text();
+  const payload = text.length > 0 ? JSON.parse(text) : {};
+
+  if (!response.ok || (isRecord(payload) && payload.ok === false)) {
+    const description = isRecord(payload) && typeof payload.description === "string" ? payload.description : response.statusText;
+    const errorCode = isRecord(payload) && typeof payload.error_code === "number" ? payload.error_code : undefined;
+    throw new TelegramApiError(method, response.status, description || `HTTP ${response.status}`, errorCode);
+  }
+
+  return payload;
+}
+
+async function postJson(fetchImpl: typeof fetch, config: NotifyConfig, method: string, body: Record<string, unknown>): Promise<void> {
+  const response = await fetchImpl(telegramUrl(config, method), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  await parseTelegramResponse(response, method);
+}
+
+async function sendMessage(fetchImpl: typeof fetch, config: NotifyConfig, text: string, parseMode?: "MarkdownV2"): Promise<void> {
+  const body: Record<string, unknown> = {
+    chat_id: config.chatId,
+    text,
+  };
+
+  if (parseMode) {
+    body.parse_mode = parseMode;
+  }
+
+  await postJson(fetchImpl, config, "sendMessage", body);
+}
+
+async function sendDocument(fetchImpl: typeof fetch, config: NotifyConfig, filename: string, content: string): Promise<void> {
+  const form = new FormData();
+  form.set("chat_id", config.chatId);
+  form.set("document", new Blob([content], { type: "text/markdown" }), filename);
+
+  const response = await fetchImpl(telegramUrl(config, "sendDocument"), {
+    method: "POST",
+    body: form,
+  });
+
+  await parseTelegramResponse(response, "sendDocument");
+}
+
+async function sendTextWithFallback(fetchImpl: typeof fetch, config: NotifyConfig, markdownText: string, plainText: string): Promise<void> {
+  try {
+    await sendMessage(fetchImpl, config, markdownText, "MarkdownV2");
+  } catch (error) {
+    if (error instanceof TelegramApiError && isMarkdownParseError(error)) {
+      await sendMessage(fetchImpl, config, plainText);
+      return;
+    }
+
+    throw error;
+  }
+}
+
+async function sendDocumentFlow(fetchImpl: typeof fetch, config: NotifyConfig, payload: NotificationPayload): Promise<void> {
+  await sendTextWithFallback(
+    fetchImpl,
+    config,
+    buildLongOutputMarkdownNotice(payload),
+    buildLongOutputPlainTextNotice(payload),
+  );
+  await sendDocument(fetchImpl, config, buildAttachmentFilename(payload.metadata), buildAttachmentMarkdown(payload));
+}
+
+export async function sendTelegramNotification(
+  config: NotifyConfig,
+  payload: NotificationPayload,
+  fetchImpl: typeof fetch = fetch,
+): Promise<TelegramSendResult> {
+  if (shouldSendAsDocument(payload)) {
+    await sendDocumentFlow(fetchImpl, config, payload);
+    return { mode: "document" };
+  }
+
+  try {
+    await sendTextWithFallback(fetchImpl, config, buildMarkdownMessage(payload), buildPlainTextMessage(payload));
+    return { mode: "message" };
+  } catch (error) {
+    if (error instanceof TelegramApiError && isMessageTooLong(error)) {
+      await sendDocumentFlow(fetchImpl, config, payload);
+      return { mode: "document" };
+    }
+
+    throw error;
+  }
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+export interface NotifyConfig {
+  botToken: string;
+  chatId: string;
+}
+
+export interface NotificationMetadata {
+  project: string;
+  cwd: string;
+  timestamp: string;
+  model?: string;
+}
+
+export interface NotificationPayload {
+  metadata: NotificationMetadata;
+  assistantText: string;
+}
+
+export type CountdownDecision = "send" | "cancel" | "timeout" | "replaced";
+
+export type ConfigLoadResult =
+  | { ok: true; config: NotifyConfig }
+  | { ok: false; reason: string };