pi-braid-telegram 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kifirkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,222 @@
-# Temporary Holding Version
+# pi-braid-telegram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- status: current -->
+
+Bidirectional Telegram channel for pi-braid.
+
+```bash
+pi install npm:pi-braid-telegram
+```
+
+One command, no clone, no build: `pi install` registers the package with pi and installs it under pi's npm directory.
+
+- **Outbound**: `telegram_send` tool - the agent sends text messages to the
+  owner (or voice notes once a TTS source is configured). Messages are LONG by
+  default: plain text sends verbatim up to the cap (`braid.telegram.sendMaxChars`
+  in `~/.pi/agent/settings.json`, default 4096 = Telegram's per-message limit);
+  there is no tweet-length default. Over the cap, the crafting model distills
+  first and `rich: true` splits-to-fit instead. Returns the delivery
+  result (message_id or error). Outbound sends the raw trimmed
+  text verbatim - the `[tg-end]` marker is an INBOUND parse boundary only and
+  never appears on outbound messages.
+- **Turn-complete auto-notify (opt-in)**: with
+  `BRAID_TG_NOTIFY_ENABLED=1`, when a turn ends with a completed plain-text
+  answer (no trailing tool call), a second LLM call (key-ring-backed via
+  `ctx.modelRegistry`, never the bot token) distills the answer into an owner
+  update capped at `braid.telegram.notifyMaxChars` (default 1200) and sends it
+  through the same outbound seam. Rate-limited (default 4/min,
+  `BRAID_TG_NOTIFY_MAX_PER_MIN`); model override via `BRAID_TG_NOTIFY_MODEL`.
+  Default OFF - no unsolicited messages.
+- **Live-update tracked message (default-on)**: on every escalated
+  inbound owner message the bot immediately sends one "⚙️ Working…" message,
+  edits it in place (Telegram's edit affordance pins it at its position) as work
+  progresses, then on a completed turn edits it to "✅ Done" and sends a SEPARATE
+  beautifully formatted full report via rich Markdown + split-to-fit
+  (`sendMessageChunks`). Progress edits are rate-limited (default 4/min);
+  `finish()` is never dropped. Default ON - set
+  `BRAID_TG_LIVE_UPDATE_ENABLED=0` to disable.
+- **Rich / split-to-fit outbound**: `telegram_send` gained optional
+  `rich: true` and `parse_mode: "HTML"|"Markdown"`. `rich` bypasses the send
+  cap and the craft hook, delivering the text verbatim split on
+  paragraph→line→word boundaries with a `(i/N)` marker; bodies that ship as
+  HTML are split tag-aware (no cut inside a tag/entity; a chunk closes the tags
+  it opens, the next chunk reopens them). A Markdown balance guard
+  (`isBalancedMarkdown`) drops `parse_mode` to plain text (never an API error)
+  when Telegram would reject unbalanced emphasis/link delimiters, and the
+  MarkdownV2→HTML conversion is validated against Telegram's HTML parser
+  (`checkTelegramHtml`): a conversion that would cross delimiter pairs, emit an
+  unbalanced/broken author tag or cross the cap is refused, and the body ships
+  as authored. Default path (no `rich`) is plain text with the
+  settings-driven cap.
+- **Decision buttons (tap-to-answer)**: `telegram_send` gained optional
+  `options` - 1-2 rows of up to 4 `{ label, value }` buttons attached to the
+  message as an inline keyboard - and `decisionToken`, their correlation id
+  (generated when omitted, echoed in the tool result). A tap is acknowledged
+  with a toast and reaches the agent as a normal inbound message
+  `[decision] <token> → <label> (<value>)` (through the same coalescing
+  window and steer handoff as a text message). The owner can always answer
+  in words;
+  malformed rows refuse the send (nothing delivered); `pause`/`resume`/`status`
+  control taps keep their own handler.
+- **Inbound (agentic pull, default)**: `telegram_inbox` tool - the agent calls
+  it mid-turn to fetch pending messages from whitelisted chats via `getUpdates`
+  (offset confirm-on-read, persisted across restarts). Results come back as
+  braid-whisper envelopes (context, NOT synthetic user turns) with sender
+  provenance + a per-message `fromOwner` flag; only owner messages may be
+  escalated to a turn.
+- **Inbound (background poller, opt-in only)**: the legacy long-poll injector
+  is OFF by default. Explicitly enable via `BRAID_TG_POLL_ENABLED=1` at load,
+  `/telegram enable`, or the `telegram_poller` tool (`action:"enable"`). At
+  most ONE poller per process (singleton). Owner messages are delivered as
+  `[braid-whisper - telegram] ... [braid-whisper-end]` envelopes.
+
+Zero npm runtime dependencies: the client is built on Node 22's global fetch.
+No live credentials, no real network calls in the test suite (recorded-fixture
+fake fetch).
+
+## Install
+
+```bash
+pi install npm:pi-braid-telegram
+```
+
+Or register the workspace in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": ["file:~/pi-braid/packages/telegram"]
+}
+```
+
+## What this does not do
+
+- It does not poll or push by default. The background poller is OFF, turn-complete auto-notify is
+  opt-in, and the tracked in-progress message fires only on an escalated inbound owner message.
+- It does not accept strangers. Only whitelisted chats/users are read, and only owner messages may
+  be escalated to a turn.
+- It does not bundle a Telegram client library - the Bot API calls use Node 22's global fetch.
+
+## Activation preconditions
+
+- `BRAID_TG_BOT_TOKEN` set - this is what enables the channel.
+- A bot token from @BotFather; optionally `BRAID_TG_CHAT_ID` / `BRAID_TG_ALLOWED_USERS` for the
+  allow-list.
+
+## Settings cadence
+
+Settings live in `~/.pi/agent/settings.json`. `braid.telegram.pauseStateFile`
+is captured as the callback write target when the extension loads. `getPauseState()`
+resolves its read path per call, so restart after changing the setting to keep
+reads and writes aligned. `braid.telegram.tts` is loaded into the voice hook at
+extension load; restart after changing its source, rate, or voices.
+The send and notification caps (`braid.telegram.sendMaxChars` and
+`braid.telegram.notifyMaxChars`) are re-read per operation and change without
+a restart.
+
+## Environment variables
+
+| Var                                | Purpose                                                                | Required                                                        |
+| ---------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `BRAID_TG_BOT_TOKEN`               | Telegram bot token from @BotFather                                     | **enables the channel** (if-has-token guard)                    |
+| `BRAID_TG_CHAT_ID`                 | Owner chat/user id for outbound + allow-list                           | optional (bootstrap fallback)                                   |
+| `BRAID_TG_ALLOWED_USERS`           | Extra allow-list ids/@usernames (comma-separated)                      | optional                                                        |
+| `BRAID_TG_STATE_FILE`              | Offset/state file path                                                 | optional, default `~/.pi/agent/braid/telegram-state.json`       |
+| `BRAID_TG_POLL_INTERVAL_MS`        | Poll cadence (background poller)                                       | optional, default 1500                                          |
+| `BRAID_TG_POLL_ENABLED`            | Explicit opt-in: auto-start the background poller at load (`1`)        | optional; default OFF (`TELEGRAM_POLL_ENABLED` alias)           |
+| `BRAID_TG_POLL_DISABLED`           | Legacy opt-out flag (superseded by default-off; still honored)         | optional                                                        |
+| `BRAID_TG_COALESCE_WINDOW_MS`      | Coalescing window for inbound owner bursts (ms; `0` = next tick)       | optional, default 2000                                          |
+| `BRAID_TG_VERBOSE`                 | Route debug/info to the notify sink (still never console.\*)           | optional                                                        |
+| `BRAID_TG_NOTIFY_ENABLED`          | Opt-in: turn-complete auto-notify, default OFF                         | optional                                                        |
+| `BRAID_TG_NOTIFY_MODEL`            | Crafting model override (`provider/model-id`); default = session model | optional                                                        |
+| `BRAID_TG_NOTIFY_MAX_PER_MIN`      | Auto-notify rate cap (sliding window), default 4                       | optional                                                        |
+| `BRAID_TG_LIVE_UPDATE_ENABLED`     | Live-update tracked message, default ON (`0` disables)                 | optional                                                        |
+| `BRAID_TG_LIVE_UPDATE_MAX_PER_MIN` | Live-update progress-edit rate cap (sliding window), default 4         | optional                                                        |
+| `BRAID_TG_LIVE_UPDATE_STATE_FILE`  | Tracked-message state file path                                        | optional, default `~/.pi/agent/braid/telegram-live-update.json` |
+
+All `BRAID_TG_*` names have `TELEGRAM_*` owner-side aliases; `BRAID_TG_*` wins
+when both are set. No token → the extension factory returns immediately; no
+tools, no command, no poller, nothing crashes (debug log only).
+
+## Tools & command
+
+| Surface                 | Purpose                                                                                                                                                                                                                                                                                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `telegram_send`         | Outbound text/voice to the owner (raw trimmed text, no end marker); optional `rich: true` for verbatim split-to-fit delivery, `parse_mode: "HTML" or "Markdown"`, `options` for decision buttons (1-2 rows of up to 4 `{ label, value }` buttons; a tap returns `[decision] <token> → <label> (<value>)`), `decisionToken` correlation id |
+| `telegram_inbox`        | Agentic pull - fetch pending messages, confirm-on-read, `fromOwner` flag                                                                                                                                                                                                                                                                  |
+| `telegram_poller`       | Enable/disable the singleton background poller (agent tool)                                                                                                                                                                                                                                                                               |
+| `/telegram enable`      | Start the singleton background poller                                                                                                                                                                                                                                                                                                     |
+| `/telegram disable`     | Stop the singleton background poller                                                                                                                                                                                                                                                                                                      |
+| `/telegram send <text>` | Send a message from the shell (raw trimmed text, no marker)                                                                                                                                                                                                                                                                               |
+| `/telegram status`      | Show channel + poller state                                                                                                                                                                                                                                                                                                               |
+
+## Components
+
+| Path                            | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/index.ts`                  | Extension factory: if-has-token guard, registers `telegram_send`/`telegram_inbox`/`telegram_poller`, `/telegram` command, singleton poller (OFF by default), TUI-safe notify sink, turn-complete auto-notify (`turn_end` listener, opt-in), live-update tracked message (`start` on inbound / `finish` on `turn_end`, default-on), LLM-crafted + rich/split-to-fit outbound                                                                                                      |
+| `src/lib/telegram-client.ts`    | Low-level `api.telegram.org/bot<token>/<method>` client (sendMessage, editMessageText, sendVoiceNote, sendChatAction, getUpdates, getMe, testToken) with injectable fetch; `parse_mode` on text sends/edits                                                                                                                                                                                                                                                                      |
+| `src/lib/inbound-poller.ts`     | Long-poll loop: allow-list + bootstrap filtering, group/non-text rejection, confirm-on-read offset persistence, injection retry buffer                                                                                                                                                                                                                                                                                                                                           |
+| `src/lib/telegram-inbox.ts`     | `fetchInbox` agentic-pull core: fetch → filter → return with `fromOwner` → confirm offset; braid-whisper envelope formatting                                                                                                                                                                                                                                                                                                                                                     |
+| `src/lib/tool-logic.ts`         | `telegram_send` validation, settings-driven cap enforcement (craft hook replaces dumb truncate; `braid.telegram.sendMaxChars` default 4096), rich/split-to-fit + parse_mode + Markdown-balance guard, text/voice delivery orchestration                                                                                                                                                                                                                                          |
+| `src/lib/tts.ts`                | Outbound voice synthesis: `braid.telegram.tts` source/rate/voice reader (default edge-tts, rate +20%, RU/EN/HE voices by script), edge-tts → ffmpeg ogg/opus with retry, gated macOS `say` fallback, `source: "none"` → voice refusal; injectable spawn seam                                                                                                                                                                                                                     |
+| `src/lib/format.ts`             | `splitLongText` (paragraph→line→word boundaries, `(i/N)` markers), `splitHtmlText` (tag-aware chunks: tags close/reopen across cuts, entities stay whole; an over-cap tag refuses the body instead of being trimmed), `sendMessageChunks` (split-to-fit 4096, parseMode-propagation, replyMarkup on the last chunk), `isBalancedMarkdown` (pre-send guard), `convertMarkdownV2ToHtml` (refuses conversions Telegram would reject), `resolveDeliveryFormat` (mode decision point) |
+| `src/lib/html-check.ts`         | `checkTelegramHtml`: strict local mirror of Telegram's HTML parser (tag set, attribute quoting, end-tag attributes, unquoted-value delimiters, span/tg-emoji attribute rules, LIFO nesting), calibrated against the live API; gates every conversion and every HTML wire chunk                                                                                                                                                                                                   |
+| `src/lib/decision-buttons.ts`   | Decision-button protocol: `options` rows → `dec:<token>:<value>` inline keyboard (64-byte callback_data cap enforced), tap parse + label recovery, the answered row is dropped from the message while open rows stay (a multi-question keyboard survives a tap), `[decision] <token> → <label> (<value>)` delivery payload                                                                                                                                                       |
+| `src/lib/telegram-settings.ts`  | `braid.telegram` caps reader (`sendMaxChars` 4096, `notifyMaxChars` 1200) from `~/.pi/agent/settings.json`: per-call, safe defaults on missing/invalid input                                                                                                                                                                                                                                                                                                                     |
+| `src/lib/notify/craft.ts`       | Turn-complete notify: pure detection (`shouldNotifyTurnEnd`), final-text extraction, distilling prompt (cap injected from settings), guard-fallback at the same cap; `buildRichSummaryPrompts` (live-update rich-report prompt)                                                                                                                                                                                                                                                  |
+| `src/lib/notify/rate-limit.ts`  | Sliding-window rate limiter (max N per minute, deterministic timestamps)                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `src/lib/notify/model.ts`       | Key-ring-backed crafting model call (completeSimple via `ctx.modelRegistry`, never the bot token) + text-craft hooks for `telegram_send`/`/telegram send` and rich summaries                                                                                                                                                                                                                                                                                                     |
+| `src/lib/notify/live-update.ts` | Live-update tracker: `start` (send + persist tracked message, idempotent restart re-pin) / `update` (edit in place) / `finish` (edit → Done, then separate rich summary) / `isActive` / `getState` + state-file persistence                                                                                                                                                                                                                                                      |
+| `src/lib/notify/turn-notify.ts` | `turn_end` handler orchestration: detect → rate-limit → craft → deliver (injectable for tests)                                                                                                                                                                                                                                                                                                                                                                                   |
+| `test/*.test.mjs`               | Unit tests against recorded fixtures (fake fetch / stubbed client), no network; `test/corpus-runner.mjs` replays the committed adversarial corpus (wire validity, fidelity changes, cap contracts)                                                                                                                                                                                                                                                                               |
+
+## Tests
+
+```bash
+npm test                 # emits src -> dist (gitignored), runs all test files
+npm test -w pi-braid-telegram   # via the monorepo workspace
+npx tsc --noEmit         # typecheck (guardrail build)
+```
+
+Coverage: client method extraction & error mapping, param validation, cap
+enforcement (settings-driven default + explicit limit), allow-list filtering,
+bootstrap, offset confirm-on-read
+persistence across restarts and fetch calls, retry-on-injection-failure,
+group/non-text rejection, if-has-token guard, inbound/outbound envelope
+formats (inbound carries the `[tg-end]` end marker; outbound carries NONE),
+default-off poller, poll-enabled opt-in, singleton
+poller, `/telegram` command verbs, telegram settings caps (defaults,
+overrides, invalid-input degradation, per-call re-read), voice TTS
+(`braid.telegram.tts` defaults / `source: "none"` refusal / invalid-input
+fallback, script→voice, edge-tts retry, gated say fallback, handoff into the
+send path), turn-complete
+auto-notify (detection,
+rate limit, guard fallback, cap + token-budget injection, key-ring model
+resolver, no marker on outbound),
+live-update tracked message (start/update/finish idempotency, restart re-pin,
+rate limit, finish-not-rate-limited, default-on + `=0` opt-out, trailing-tool gating,
+state-file persistence), rich/split-to-fit (paragraph→line→word boundaries,
+never mid-word, `(i/N)` markers, 4096 cap sequence, honored parse_mode,
+Markdown-balance guard, craft bypass when `rich`),
+decision buttons (row/token validation, malformed-row refusal, 64-byte
+callback_data cap, generated-token echo, dec: parse/label/format, tap handler
+ack + delivery payload, multi-question keyboards keep the open rows after a
+tap, voice-path refusal, keyboard on the last rich chunk),
+callback routing through the real poller (dec: tap delivered as a whisper,
+pause tap persists state, unknown data answered without a crash),
+format corpus (`test/corpus.test.mjs` + `corpus-runner.mjs`: 76 hostile bodies ×
+3 requested modes, recorded live parse verdicts vs the local checker, the 21-cell
+resolution matrix, cap-crossing bodies; `test/live-html-probe.mjs` re-verifies
+the checker against the live API, opt-in and never run by `npm test`).
+
+## Live E2E (postponed)
+
+Configure the env vars above, add `packages/telegram` to the pi `packages`
+list (like `packages/providers`), then: `testToken` → `telegram_send` a text →
+`telegram_inbox` to pull replies (or explicitly `BRAID_TG_POLL_ENABLED=1` /
+`/telegram enable` for the background injector). `voice: true` synthesizes
+through `braid.telegram.tts` (default: latest edge-tts via uvx, rate +20%,
+voices picked by script) → ffmpeg ogg/opus → `sendVoice`; `source: "none"`
+disables synthesis, and `voice: true` then returns a clear "no TTS source is
+configured" error instead of silently sending text. macOS `say` is the
+explicit-config emergency fallback (`source: "say"` or `"edge-tts+say"`).

package/build-info.json

@@ -0,0 +1,9 @@
+{
+  "name": "pi-braid-telegram",
+  "version": "0.1.5",
+  "sha": "752d2e6e9b45037a8ebcc17f3d6f90c905b2c71c",
+  "shaShort": "752d2e6",
+  "branch": "detached",
+  "dirty": false,
+  "packedAt": "2026-10-19T11:29:41.109Z"
+}

package/docs/live-update.md

@@ -0,0 +1,190 @@
+<!-- status: current -->
+
+# Telegram LIVE-UPDATE tracked message + rich formatting: Design Decisions
+
+Status: **current (implemented)**. This list is the decision surface; the fixture
+tests in `packages/telegram/test/live-update.test.mjs`, `test/format.test.mjs`,
+and the live-update additions to `test/index.test.mjs` / `test/tool-logic.test.mjs`
+pin the implemented defaults. Any owner change below is a config/env change, not code.
+
+## Feature recap (the "editing workaround")
+
+The owner's request: _"make tg bot handler to provide live updates via workaround
+with ability to edit telegram message constantly. So when pi receives my message
+it would immediately send that tracked message and update it constantly, then when
+done edit finally that message to 'done' and then send final beautiful message with
+summary and report."_
+
+Telegram has **no streaming API** - the workaround is message _editing_: instead of
+sending a new progress message per update (which reorders and spams the chat), the
+bot sends ONE message immediately on inbound ("⚙️ Working… received your message"),
+then re-edits that same message in place (`editMessageText`) as work progresses -
+Telegram's edit affordance keeps the message pinned at its original position - and
+finally edits it to "✅ Done" plus sends a SEPARATE beautiful markdown summary.
+
+## Decision 1: opt-in vs always-on
+
+**Implemented: default ON; `BRAID_TG_LIVE_UPDATE_ENABLED=0` disables.**
+When disabled there is NO live-update behavior at all: no tracked message send, no
+`turn_end` finish listener, no state file, no rate limiter. The telegram extension
+already requires `BRAID_TG_BOT_TOKEN`; live-update is the only extra gate and it is
+on by default.
+
+## Decision 2: the tracked message lifecycle
+
+**Implemented: `start()` → `update()`\* → `finish()`.**
+
+- `start()` (called on every escalated inbound owner message): sends the immediate
+  "⚙️ Working… received your message" via `sendMessage`, records the returned
+  `message_id` + `chat_id` in-memory AND persists them to
+  `~/.pi/agent/braid/telegram-live-update.json` (mirrors `telegram-state.json`
+  conventions; `BRAID_HOME` overrides the root) so
+  a process reload can resume editing the same message.
+- `start()` is **idempotent**: when a tracked message already exists (incl. a
+  persisted one from a prior run), it is REUSED via an edit-re-pin - never a
+  duplicate send (the "no new-message spam" invariant).
+- `update(text)` - public tracker API - edits the tracked message in place,
+  idempotent (no-op with no tracked message), clipped to 4096 chars.
+
+_`update()` wiring note:_ the brief explicitly wires `start()` (on inbound) and
+`finish()` (on `turn_end`). Periodic mid-turn `update()` calls need a verified
+streaming hook that isn't on pi-core's documented extension event surface yet;
+`update()` is shipped, tested, and ready to be wired to such a hook later (see
+**Follow-ups**).
+
+## Decision 3: finish(): Done-edit + SEPARATE final summary
+
+**Implemented: two steps, ordered.**
+
+1. Edit the tracked message to "✅ Done — full report below." (`TRACKED_DONE_TEXT`).
+2. Send a SEPARATE final summary message (not an edit) via `sendMessageChunks`
+   (split-to-fit 4096). The summary is **crafted** via the existing key-ring-backed
+   craft path (`createRichCraftHook` - `completeSimple` through
+   `ctx.modelRegistry`, never the bot token) using a NEW rich prompt
+   (`buildRichSummaryPrompts`, rich-markdown variant) that FLAGS the model to use
+   Telegram Markdown structure. When no craft hook is available/fit, the raw final
+   answer text is delivered instead (still split-to-fit).
+
+The final summary always goes out even if no tracked message survived - the report
+is the deliverable.
+
+## Decision 4: finish() gating on turn_end
+
+**Implemented: reuse `shouldNotifyTurnEnd`** (the same predicate the turn-complete
+auto-notify already uses, `notify/craft.ts`): finish fires only when the turn ended
+with a completed plain-text answer (`stopReason !== "toolUse"`, non-empty text). A
+trailing-tool-call turn keeps the tracked message OPEN (work continues next turn).
+
+Note the two features are independent (live-update is default ON, notify is
+opt-in, both `turn_end` listeners): `BRAID_TG_NOTIFY_ENABLED` sends its own
+separate update capped at `braid.telegram.notifyMaxChars` (default 1200),
+`BRAID_TG_LIVE_UPDATE_ENABLED` (default ON)
+sends the tracked-message + full report. If the owner enables both, a turn_end
+delivers two messages (notify + full report) - an intentional,
+documented consequence of the two features staying independent.
+
+## Decision 5: rate limit
+
+**Implemented: sliding window, default 4/min** (`DEFAULT_LIVE_UPDATE_MAX_PER_MIN`),
+reusing `SlidingWindowLimiter` (`notify/rate-limit.ts`). Applied to `start()` and
+`update()` (progress edits). **`finish()` is NOT rate-limited** - it is terminal and
+always attempts its done-edit + summary; a saturated window must not strand the owner
+on a stuck "Working…" message. Override via `BRAID_TG_LIVE_UPDATE_MAX_PER_MIN`.
+
+## Decision 6: owner-gate
+
+The tracked message is only ever started from `deliverOwnerMessage` - the SINGLE
+inbound escalation seam in `src/index.ts` (shared by the background poller, the
+`telegram_poller` tool, and `/telegram enable`), which fires only for allow-listed
+owner messages. The inbox agentic-pull tool (`telegram_inbox`) does NOT itself send
+messages - it returns structured results for the agent to escalate via core's
+`sendUserMessage`, which this package cannot intercept - so wiring there would need a
+core-side hook (out of scope; see Follow-ups).
+
+## Decision 7: rich / split-to-fit telegram_send
+
+**Implemented (no breaking change to the default path):**
+
+- `telegram_send` gained optional `rich: boolean` and `parse_mode: "HTML"|"Markdown"`.
+- `rich: true` **bypasses** the settings-driven send cap
+  (`braid.telegram.sendMaxChars`, default 4096) and the craft hook entirely:
+  the text is delivered verbatim via `sendMessageChunks`, split on paragraph→line→word
+  boundaries (never mid-word), every chunk carrying a `(i/N)` continuity marker.
+  Bodies that ship with `parse_mode` HTML are split **tag-aware**
+  (`splitHtmlText`): a cut never lands inside a tag or entity, the tags open at
+  the cut are closed at the end of the chunk and reopened at the start of the
+  next one, so every chunk parses on its own (the same splitter serves the
+  plain-path split when a converted body exceeds Telegram's 4096 cap). A tag
+  longer than the cap cannot be represented without cutting it: such a body is
+  refused with an explicit over-cap error and nothing is sent.
+- Default path (`rich` unset): plain text up to the cap (+ craft hook above it), and
+  `parse_mode` is honored on the single send. The conversion is capped at the
+  effective limit: when the HTML rendering of a MarkdownV2 body would cross the
+  cap (`braid.telegram.sendMaxChars` or an explicit `limit`), the conversion is
+  refused and the authored text ships as-is, so the wire never exceeds the cap.
+- **Markdown safety net** (`isBalancedMarkdown` in `format.ts`): Telegram's
+  `Markdown` parse*mode rejects unbalanced emphasis/link delimiters. When the payload
+  has unbalanced `**`/`*`/backtick/`[` `]`, `parse_mode`is dropped and the text is
+delivered plain (with a`warn` in the outcome) instead of surfacing an API error.
+  HTML has no paired-delimiter rule and passes through. The MarkdownV2→HTML
+  conversion is validated against Telegram's HTML parser (`checkTelegramHtml`)
+  before it ships: a conversion whose output would cross delimiter pairs or
+  emit unbalanced/broken author tags is refused (the authored text ships on
+  the unconverted path), so the converter cannot turn a deliverable body into
+  an API error.
+
+## Env flags (BRAID*TG*\_ canonical; TELEGRAM\_\_ owner-side aliases)
+
+| Var                                | Purpose                                                 | Default                                       |
+| ---------------------------------- | ------------------------------------------------------- | --------------------------------------------- |
+| `BRAID_TG_LIVE_UPDATE_ENABLED`     | Live-update tracked message (default ON; `=0` disables) | ON                                            |
+| `BRAID_TG_LIVE_UPDATE_MAX_PER_MIN` | Progress-edit rate cap (sliding window)                 | 4                                             |
+| `BRAID_TG_LIVE_UPDATE_STATE_FILE`  | Tracked-message state file path                         | `~/.pi/agent/braid/telegram-live-update.json` |
+
+## API surface (new/changed)
+
+- `telegram-client.ts`: `editMessageText(token, chatId, messageId, text, opts?)`,
+  `sendChatAction(token, chatId, action?)`, `parseMode` option (`parse_mode` in the
+  body) on `sendMessage` + `editMessageText`; `TelegramClient` interface + factory
+  updated.
+- `format.ts`: `splitLongText(text, maxLen?, reserved?)`,
+  `splitHtmlText(text, maxLen?, reserved?)`, `isBalancedMarkdown(text)`,
+  `convertMarkdownV2ToHtml(text, {renderedCap?})`, `resolveDeliveryFormat(requested, text, detectMarkdown?, renderedCap?)`,
+  `sendMessageChunks(client, {token, chatId, text, parseMode?})`.
+- `html-check.ts`: `checkTelegramHtml(text)`, a local mirror of Telegram's HTML
+  parser rules (tag set, attribute quoting, span/tg-emoji attribute requirements,
+  strict nesting), calibrated against the live API by `test/live-html-probe.mjs`.
+- `notify/live-update.ts`: `createLiveUpdateTracker` (start/update/finish/isActive/
+  getState) + `loadLiveState`/`saveLiveState`/`clearLiveState` + `defaultLiveUpdateStateFile`.
+- `notify/craft.ts`: `buildRichSummaryPrompts` (rich-markdown variant).
+- `notify/model.ts`: `createRichCraftHook` (rich-prompt text-craft hook).
+- `tool-logic.ts`: `TelegramSendToolParams.rich` / `.parse_mode`; `chunks` in outcome.
+- `src/index.ts`: live-update section (tracker + `turn_end` finish listener),
+  shared `deliverOwnerMessage` seam, new ENV consts + aliases, updated telegram_send
+  tool params + guidelines.
+
+## Tests
+
+Fixture-based, zero network: live-update tracker (start/update/finish/restart/rate-
+limit/failure paths), format (split boundaries, markdown guard, chunk markers, cap),
+client (editMessageText body + `true` result, parse_mode, sendChatAction), tool-logic
+(rich split/honored parse_mode/unbalanced fallback), index (env aliases, disabled-no-
+behavior, enabled pins Working… + finishes, trailing tool call keeps open).
+Run: `cd packages/telegram && node test/run-tests.mjs` (all files green) and
+`npx tsc --noEmit` (clean).
+
+## Forbidden-files check
+
+- No changes to packages/core or packages/providers (incl. provider catalogs).
+- No package-lock.json diff, no npm install, no git checkout/reset/stash.
+- Scope is entirely inside packages/telegram.
+
+## Follow-ups
+
+- Wire periodic `update()` to a verified streaming hook when one is available, so the
+  tracked message updates mid-turn rather than only at start/finish.
+- Delivered: an HTML-tag-aware splitter (`splitHtmlText`) keeps rich messages
+  with markup spanning chunk boundaries parseable per chunk; a converted body
+  that would cross the cap is refused instead of split.
+- If agent-driven `telegram_inbox` escalation should also trigger `start()`, that
+  needs a core-side hook (sendUserMessage is called from core, not this package).

package/docs/pause-control.md

@@ -0,0 +1,151 @@
+<!-- status: current -->
+
+# Telegram inline-keyboard pause/resume control: Design Decisions
+
+Status: **current (implemented)**. Fixture tests: `packages/telegram/test/pause-control.test.mjs`
+(handler, keyboard, persistence), callback-routing + **pause-gate** additions to
+`test/inbound-poller.test.mjs`, and `reply_markup`/`answerCallbackQuery` client additions in
+`test/telegram-client.test.mjs`. Pause-gate consumer behavior (inbound held + «⏸ пауза» ack while
+paused) is implemented in `lib/inbound-poller.ts` (Decision 6).
+
+## Feature recap
+
+The owner asked: _"Seems need a button for pause or whatever control this through tg"_ - a
+button to control the agent from Telegram. This adds an inline keyboard (⏸ Pause / ▶ Resume /
+📊 Status) and `callback_query` handling in the inbound poller: **pause** sets the persisted flag
+to true, **resume** to false, **status** replies with the current state. Every tap is answered via
+`answerCallbackQuery` (toast with the state) and the keyboard is updated in place via
+`editMessageText` - paused shows ▶ Resume, running shows ⏸ Pause.
+
+## Decision 1: the pause flag is a CONSUMER signal, not a gate
+
+The module only persists the flag and keeps the keyboard in sync. It **never** blocks the poller,
+drops inbound, or changes the core loop. The orchestrator reads the flag via the exported
+`getPauseState()` and decides how to honor it. This package stays delivery-neutral.
+
+## Decision 6: the consumer gate lives in the poller
+
+The orchestrator-side consumer behavior is the **pause gate on non-callback inbound**: in
+`inbound-poller.ts`, every owner/bootstrap message (text/photo/voice) checks the persisted pause
+flag via an injected `getPauseState` reader BEFORE `onOwnerMessage` is called. While paused:
+
+- the message is **not injected** - `onOwnerMessage` / `pi.sendUserMessage` are never called (no
+  turn is triggered); the owner is told once with `«⏸ пауза»` + a ▶️ Resume hint;
+- the ack is sent **once per paused period** (reply-storm guard), keyed on the period's `updatedAt`:
+  `pauseAckUpdatedAt` holds the `updatedAt` of the last acked period, so messages inside the same
+  period are held silently and any resume/re-pause transition changes `updatedAt` and re-arms the
+  ack for the next period. Not persisted - a poller restart re-acks once (fresh session);
+- the held message is still confirmed (offset advances, confirm-on-read) - the owner was acked,
+  and after ▶️ Resume the next message flows normally;
+- retry-buffer messages are gated too (a queued owner message stays queued while paused);
+- **callback_query taps are NEVER gated** - pause/resume/status buttons are the owner's control
+  path and are routed to `handlePauseCallbackQuery` even while paused.
+
+DI mirrors the callback handler: `InboundPollerOptions.getPauseState` (default: never-paused, so
+unwired pollers are deterministic in tests) is injected by `index.ts` with the real
+`getPauseState()` at every `startSingletonPoller` site, so the gate is ON in production whenever
+the flag is paused. `sendMessage` (with the poller's `fetchFn`) emits the ack. Config-free: no new
+settings/env keys; the gate activates purely on `getPauseState().paused`.
+
+## Decision 2: config via settings, not process.env
+
+No new `BRAID_TG_*` env keys. The state file defaults to
+`<braidDir>/telegram/pause-state.json` (`~/.pi/agent/braid/telegram/pause-state.json`, relocated
+by `BRAID_HOME`) and can be overridden via `braid.telegram.pauseStateFile` in
+`~/.pi/agent/settings.json` (mirrors `packages/core/src/lib/config/braid-settings.ts`).
+`resolvePauseStateFile()` is the write target; `resolvePauseStateReadFile()` / `getPauseState()`
+prefer the braid-root file and fall back to the pre-move `~/.pi/agent/telegram-pause-state.json`
+until the first post-move write.
+
+## Decision 3: atomic persistence
+
+`savePauseState` writes `JSON + "\n"` to `<stateFile>.tmp` then `rename()`s over the target
+(write-temp-rename), so a crash mid-write can never leave a truncated state file. `loadPauseState`
+reads safely and treats a missing/corrupt file as "not paused". Shape: `{ paused: boolean, updatedAt: number }`.
+
+## Decision 4: callback routing lives in the poller
+
+`getUpdates` already returns `callback_query` updates. The poller routes allow-listed taps to a new
+`onCallbackQuery` option (wired in `index.ts` to the pause handler); foreign taps are dropped and
+counted (`callbackRejected`), never handed to `onOwnerMessage` - a button tap must not trigger a turn.
+Handler failures are requeued and retried next cycle (the retry buffer is now kind-aware:
+`"message" | "callback"`). No handler → taps are dropped (offset still advances, confirm-on-read).
+
+## Decision 5: keyboard refresh, idempotent
+
+`handlePauseCallbackQuery` re-reads the persisted state after a transition so idempotent re-taps
+(pause while already paused) don't rewrite `updatedAt`, but are still answered and refresh the
+keyboard. API failures (answer/edit) are reported in the outcome, never thrown; the flag is
+persisted first, so a failed answer never loses the command.
+
+## Decision 7: control-keyboard placement lives at the POLLER-START seam
+
+The owner must actually SEE the ⏸ Pause / ▶ Resume / 📊 Status control - not just have the code exist.
+`sendControlKeyboard` was exported but NOBODY called it (code-only). The natural lifecycle seam is
+`startSingletonPoller` in `src/index.ts` - the orchestrator-side wiring that constructs and starts the
+inbound poller (the entity that owns the poller). On EVERY poller start (env `BRAID_TG_POLL_ENABLED=1`
+auto-start at boot, `/telegram enable`, `telegram_poller enable`) it fires a new `placeControlKeyboard`
+helper: reads the persisted pause flag via the SAME `getPauseState` reader the poller gate uses, then
+`sendControlKeyboard` places the control in the owner chat (`resolveChatId()` - `BRAID_TG_CHAT_ID`, else
+the first allow-listed sender, else captured from the first owner message).
+
+Delivery-neutrality is kept: nothing self-sends on import - the FACTORY (the consumer that owns the
+poller) places, via a new `onStart` hook on `startSingletonPoller`. When the owner chat is not yet known
+at start (no chat-id env and no allow-list - pure first-message bootstrap), placement is DEFERRED
+(`placeControlKeyboard` returns `deferred: true`, nothing sent) and fired once when the first owner
+message captures `ownerChatId` (`deliverOwnerMessage` → `flushDeferredControlPlacement`, one-shot).
+Post-resume correctness is already cheap and unchanged: `handlePauseCallbackQuery` edits the SAME
+keyboard in place (`editMessageText`) on every tap, so pause/resume refresh the existing message - no
+per-transition re-send/spam.
+
+## Decision 8: placement is a once-per-poller-start, best-effort, DI-able helper
+
+`placeControlKeyboard(chatId, deps)` in `lib/pause-control.ts` reads the flag (DI-able `getPauseState`;
+default never-paused) and delegates to `sendControlKeyboard`. Failures are reported, never thrown; a
+failed placement is NOT retried (one-shot, logged - avoids side-effect storms). A no-op re-enable (the
+singleton is already running) does NOT re-place. Test coverage: `placeControlKeyboard` unit tests
+(correct chatId + paused→▶ Resume / running→⏸ Pause, defer on unknown chat, failure reporting) in
+`test/pause-control.test.mjs`, plus end-to-end wiring tests in `test/index.test.mjs` (boot auto-start
+places into the owner chat; `/telegram enable` places; no-chat bootstrap defers to the first owner
+message, one-shot). The boot placement shifts the exact `sendMessage` counts of the live-update factory
+tests (they now see the control keyboard as `sent[0]`) - those tests were updated accordingly.
+
+## API surface (new)
+
+- `telegram-client.ts`: `answerCallbackQuery(token, cqId, { text?, showAlert? })`,
+  `replyMarkup` option (`reply_markup` in the body) on `sendMessage`/`editMessageText`,
+  `TelegramReplyMarkup`/`TelegramSendOptions` types, `TelegramCallbackQuery` on `TelegramUpdate`,
+  factory merges per-call options with bound ones.
+- `lib/pause-control.ts`: `getPauseState(stateFile?)`, `defaultPauseStateFile()`,
+  `resolvePauseStateFile()`, `loadPauseState`/`savePauseState`, `buildControlKeyboard(paused)`,
+  `sendControlKeyboard(client, token, chatId, paused)`, `placeControlKeyboard(chatId, deps)`,
+  `handlePauseCallbackQuery(deps, cq)`.
+- `lib/inbound-poller.ts`: `onCallbackQuery` option; `getPauseState` / `pauseAckText` options
+  (pause gate); `PAUSED_INBOUND_ACK_TEXT`; `PollOnceResult.callbacks` / `.callbackRejected` /
+  `.paused` (held by the gate).
+- `src/index.ts`: wires `onCallbackQuery` into every poller start site (tool command, `/telegram
+enable`, env auto-start); wires the real `getPauseState()` as the poller's pause-gate reader;
+  re-exports the pause-control public surface for the orchestrator.
+
+## Tests
+
+Zero network: keyboard builder (running/paused buttons), persistence incl. atomic no-`.tmp`-left-behind,
+`getPauseState`, `sendControlKeyboard`, handler pause/resume/status/unknown/idempotent/restart/API-failure,
+poller routing (owner vs foreign, no-handler drop, retry), pause gate (held + «⏸ пауза» ack + no
+injection, once-per-paused-period in-batch and cross-cycle, resume callback ungated + post-resume
+delivery, normal flow while running, re-arm on a new paused period, non-fatal ack failure),
+`placeControlKeyboard` (running/paused/deferred/failure), poller-start placement wiring (boot auto-start,
+`/telegram enable`, no-chat bootstrap defer one-shot), client `answerCallbackQuery` + `reply_markup`
+bodies + factory merge.
+Run: `cd packages/telegram && node test/run-tests.mjs` (14 files green) and `npx tsc --noEmit` (clean).
+
+## Forbidden-files check
+
+- No changes to packages/providers (incl. provider catalogs), no package-lock diff, no npm install,
+  no git checkout/reset/stash, no push.
+- Scope is entirely inside packages/telegram.
+
+## Follow-ups
+
+- Telemetry: the gate currently holds (does not queue) paused inbound by design - the owner is acked
+  and re-sends after resume. Queue-until-resume would be a behavior change; not planned.