@llblab/pi-telegram 0.20.6 → 0.21.0

package/AGENTS.md

@@ -83,7 +83,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - Instance thread names are provisioner-authored identity metadata, not model-authored output. Fresh Threaded Mode threads select one of five curated compact 4-6 letter Latin names for the assigned slot letter using provisioning timestamp entropy, then create the Telegram thread with that thread name immediately. The title is the thread name itself, not `{slot} {threadName}` or `{slot} — {threadName}`. Do not register or reintroduce an agent-facing thread rename tool; removing the extra rename prompt/tool turn is an intentional simplicity constraint. Thread names must mirror into terminal status, live diagnostics, and `[telegram|thread:name]` through one target-aware current-instance identity resolver. Registered follower/leader metadata takes precedence over a stale shared record for the same target, with the record used only as fallback; do not hide a valid baked/custom thread name behind old slot-prefix validation. A follower that later becomes leader keeps its existing name; leadership changes are transport role changes, not identity resets.
 - Telegram private-chat Threaded Mode treats `All` as an aggregate/control surface, not a durable `General` thread and not a process launcher. Leader activation creates/reuses a leader thread in the private bot DM (chat = allowedUserId) proactively. If all threads are closed and the owner writes from `All`, a first new unbound thread should be reclaimed by the leader when the leader lacks an active bound thread. Later unknown threads require explicit routing or restore; creating another Pi instance is a manual terminal action followed by `/telegram-connect`.
 - Unbound thread detection: when a message arrives from the owner in an unknown `message_thread_id` while Threaded Mode is active, the default runtime first reclaims it for the leader if the leader has no active bound thread and routes the prompt locally. Later unknown threads are preserved by default and receive an in-thread reroute chooser that can send the captured prompt to a live thread or restore a stale leader/follower binding through explicit restore actions; destructive cleanup happens only after explicit user confirmation and through `thread-reconciler`. If the operator wants another Pi instance, they start Pi in a terminal and run `/telegram-connect`; Telegram-originated hidden auto-spawn and `/thread`-style process launch flows are intentionally absent. If Threaded Mode is unavailable, the message is processed normally through classic routing.
-- Telegram extension work should not hold Pi's core agent lifecycle hostage once Pi has produced the semantic result. For Telegram-originated turns, final Telegram delivery, attachment upload, and transport cleanup are extension-owned side effects; schedule them off the critical `agent_end` path when ordering can still be preserved, record failures as runtime events, and keep dispatch of the next Telegram turn behind the delivery task when needed to avoid interleaving previews/finals.
+- Telegram extension work should not hold Pi's core agent lifecycle hostage once Pi has produced the semantic result. For Telegram-originated turns, final Telegram delivery, attachment upload, and transport cleanup are extension-owned side effects; schedule them off the critical `agent_end` path when ordering can still be preserved, record failures as runtime events, and keep dispatch of the next Telegram turn behind the delivery task when needed to avoid interleaving previews/finals. Public activity handlers run through isolated asynchronous per-handler queues; lifecycle hooks enqueue normalized events and never await consumer work.
 - Telegram runtime state should be treated as event-driven reconciliation of extension assumptions against observable Telegram signals, not as a full Telegram bot read-model and not as a reason to query Telegram on every action. Keep a local assumption model for bot identity/capabilities, pairing assumptions, thread support, known thread lifecycle, bound instance targets, reservations, and transport health. Invalidate and reconcile the relevant slice on meaningful events: startup/reload, lifecycle service messages, stale-send/API errors, setup/pairing changes, follower register/prune, explicit status/debug requests, and bounded low-frequency leader health ticks. `lib/sync.ts` owns sync slices, observation intake, invalidation triggers, status/debug freshness, and reconciliation scheduling; it must not promise complete bot-state mirroring because Bot API lacks a complete topic listing surface. `lib/thread-reconciler.ts` owns pure Threaded Mode lifecycle planning and should become the only policy authority for destructive thread cleanup decisions. `threads` owns current Telegram UI thread/tab binding primitives and thread-name helpers mapped to Bot API topic transport, `status` renders projections, and `index.ts` only wires ports. `tmp/telegram/logs.jsonl` is a session-local redacted runtime evidence stream for race debugging and resets on extension start / runtime scope changes; it is diagnostics only, not routing/provisioning authority. `state.json` should be an observable/debug snapshot aligned with `/telegram-status` (extension runtime, bot capabilities including `bot.lastSlot`, runtime role, live roster projection, reservations, diagnostics), not routing/provisioning authority. Because every process on one Telegram profile shares this file, only the active transport lock owner may persist it; followers read current state and gain write authority only after promotion. Status-only writes must refresh disk-backed bindings before serialization so a stale loaded snapshot cannot erase newer leader state. Live bus/runtime state is authoritative; file reservations and fresh capability observations may be startup hints/collision guards only; stale snapshots must re-probe before suppressing bus/topic behavior. Do not persist stale/offline/failed thread target history as source of truth.
 - Thread bindings are bidirectional. From the Pi-instance side, an instance knows and preserves its target, slot, thread name, lifecycle state, and direct-delivery defaults. From the Telegram-client/bot side, the bridge observes thread creation/close/reopen/stale-send signals and reconciles them into instance binding state. Lifecycle transitions that affect operator understanding should be Telegram-visible when a live transport remains: every successful follower registration/re-registration gets a compact connected notice in the assigned thread, while heartbeat pruning stays silent because it is only liveness suspicion. These notices should use the instance thread name when known and fall back to the slot letter only while the thread is still unnamed. New unknown threads (owner writing in `All`) are preserved until the user explicitly chooses a reroute/restore/new-instance action that makes cleanup eligible; any destructive cleanup must go through `thread-reconciler`. Unknown `forum_topic_created` service events are observations, not destructive cleanup proof.
 - The multi-instance bus uses private bot DMs with Telegram private-chat Threaded Mode enabled for the bot. No supergroup, group, or forum configuration is needed; the thread chat is always the private chat with the paired owner. Threaded capability checks must use bot/private-chat evidence such as `getMe.has_topics_enabled`, incoming `message_thread_id`, and topic operation success/failure; do not use group chat metadata as the control-plane truth for Telegram private-chat Threaded Mode.
@@ -159,9 +159,9 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 
 - Scheduling and lifecycle: `queue`, `runtime`, `lifecycle`, `locks`
 - Telegram transport, polling, bus, sync, and inbound flow: `api`, `polling`, `bus`, `bus-api`, `bus-leader`, `bus-follower`, `ownership`, `target`, `sync`, `thread-reconciler`, `threads`, `updates`, `routing`, `media`, `turns`, `inbound`, `config`, `setup`
-- Response surfaces: `preview`, `replies`, `rendering`, `keyboard`, `outbound-markup`, `outbound-attachments`, `outbound`, `voice`, `status`
+- Response surfaces: `preview`, `replies`, `rendering`, `keyboard`, `delivery`, `activity`, `outbound-markup`, `outbound-attachments`, `outbound`, `voice`, `status`
 - Controls and application menu UI: `commands`, `menu`, `menu-model`, `menu-thinking`, `menu-status`, `menu-queue`, `model`, `prompts`
-- Extension platform: `sections` owns section registry, token mapping, callback dispatch, context building, and its globalThis bridge; `voice` owns the voice-provider registry and its globalThis bridge
+- Extension platform: `sections` owns section registry, token mapping, callback dispatch, context building, and its globalThis bridge; `delivery` owns target-aware extension views, logical handles, target policy, ordering, lifecycle fencing, and its globalThis runtime membrane; `activity` owns normalized lifecycle registration, activity/source identity, non-blocking dispatch, delivery contexts, and its globalThis runtime membrane; `voice` owns the voice-provider registry and its globalThis bridge
 - Pi SDK boundary: `pi` owns direct pi imports and bound extension API ports; `bindings` owns pi-facing command/tool/lifecycle registration wiring extracted from the entrypoint
 
 ## 6.5 Entrypoint And Import Boundaries
@@ -203,9 +203,11 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 - Inline UI labels and dialogs follow [`docs/ui-style.md`](./docs/ui-style.md): action buttons use emoji plus capitalized action text, state & navigation buttons show state and lead to a submenu, first-level submenus start with `⬆️ Main menu` while deeper submenus start with `⬆️ Back`, boolean toggles use Capitalized horizontal `On`/`Off` with green active `On`, yellow active `Off`, and black inactive dots, tabs use capitalized labels with purple default-state and yellow elevated-state active dots and black inactive dots, vertical option lists mark only the current value green, and confirmation dialogs use a single bold text-only question with emoji on buttons only.
 - Inbound text/media may be transformed through configured `inboundHandlers` before queueing; legacy `attachmentHandlers` are deprecated compatibility aliases appended after `inboundHandlers`; active-turn outbound files must flow through `telegram_attach`, while explicit local/TUI Telegram sends use `telegram_attach` for files or `telegram_message` for text/buttons
 - Long Telegram text split recovery belongs to `text-groups`: keep it conservative, short-debounced, same chat/user/message-id contiguous, and gated by near-limit human text so normal rapid follow-ups and slash commands stay separate
-- Public API boundaries live in [`docs/public-api.md`](./docs/public-api.md): companion extensions must use public API domain subpaths such as `@llblab/pi-telegram/sections`, `/voice`, `/inbound`, `/outbound`, and `/updates`; `0.12.0` intentionally removes the published `@llblab/pi-telegram/lib/*.ts` compatibility wildcard
-- Public handler API matrix: low-level buses use `registerTelegramUpdateHandler(handler)`, `registerTelegramInboundHandler(kind, handler)`, and `registerTelegramOutboundHandler(kind, handler)` without ids; high-level surfaces use stable identity (`registerTelegramSection({ id, ... })`, `registerTelegramVoiceTranscriptionProvider(provider, { id })`, and `registerTelegramVoiceSynthesisProvider(provider, { id })`). Inbound handlers and command-backed outbound handlers use command templates as the standard config contract; built-in outbound buttons use inline keyboards plus callback routing because no polling command execution is needed
+- Public API boundaries live in [`docs/public-api.md`](./docs/public-api.md): companion extensions must use public API domain subpaths such as `@llblab/pi-telegram/sections`, `/delivery`, `/voice`, `/inbound`, `/outbound`, and `/updates`; `0.12.0` intentionally removes the published `@llblab/pi-telegram/lib/*.ts` compatibility wildcard
+- `Companion` names the extension consumer/product relationship, not a core domain responsibility. Source headers, Zones, module names, public API names, and domain docs should use the owned capability (`delivery`, `activity`, `sections`, `voice`, or extension interop); reserve companion terminology for the external extension that composes those APIs.
+- Public handler API matrix: low-level buses use `registerTelegramUpdateHandler(handler)`, `registerTelegramInboundHandler(kind, handler)`, and `registerTelegramOutboundHandler(kind, handler)` without ids; high-level surfaces use stable identity (`registerTelegramSection({ id, ... })`, `registerTelegramVoiceTranscriptionProvider(provider, { id })`, and `registerTelegramVoiceSynthesisProvider(provider, { id })`). Imperative `/delivery` operations resolve the current runtime on every call and use generation-bound logical handles rather than registration ids or captured Pi contexts. Inbound handlers and command-backed outbound handlers use command templates as the standard config contract; built-in outbound buttons use inline keyboards plus callback routing because no polling command execution is needed
 - Telegram prompt-template commands are discovered from Pi slash commands with `source: "prompt"`; Pi template names are mapped to Bot API-compatible aliases (`fix-tests` → `/fix_tests`), aliases that conflict with built-in bridge commands or hidden shortcuts are not displayed, prompt-template aliases stay out of the Telegram bot command menu, and the bridge expands template files before queueing because extension-originated `sendUserMessage()` bypasses Pi's interactive template expansion
+- Target-aware companion delivery follows [`docs/delivery.md`](./docs/delivery.md): `active-turn`, `instance`, `aggregate`, and explicit target scopes resolve through current profile/role state; followers may target only their assigned thread or aggregate surface, leaders may target current live bindings, logical handles reconcile chunked send/edit/delete, and reload/session replacement invalidates old generations
 - Unknown callback data not owned by pi-telegram prefixes (`compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `section:`, `settings:`) may be forwarded as `[callback] <data>` after built-in handlers decline it; update-handler extensions should follow `docs/callback-namespaces.md` and must not poll the same bot independently
 - Command templates stay compact and shell-free: no `command` field, no shell execution, inline defaults are allowed as `{name=default}`, `template` may be a string or an ordered composition array, only `args`/`defaults` inherit into leaves, top-level `timeout` wraps composed sequences, stdout pipes to the next step's stdin by default, and multi-step work should use `template: [...]` rather than provider-specific fields; `pipe` is only a legacy local alias
 - Command-template documentation examples should use portable executable placeholders such as `/path/to/stt` and `/path/to/tts`, not host-local skill paths or machine-specific install locations

package/BACKLOG.md

@@ -1,50 +1,6 @@
 # Project Backlog
 
-_This backlog tracks only open release-relevant work: live promoted-follower verification, evidence-gated Telegram client/runtime follow-ups, and upstream Pi API blockers. Completed validation evidence belongs in `CHANGELOG.md`, not in this queue._
-
-## P1 — Guest Media Live Follow-Ups
-
-Context: 0.20.5 shipped deterministic Guest Mode file/audio delivery coverage. Post-release private-DM smoke confirmed that one local document reaches the remote conversation through `answerGuestQuery`; remaining checks validate Telegram client behavior rather than gate the implemented transport.
-
-Open work:
-
-- [x] Confirm one local document in a private Guest Mode DM after extension reload.
-- [x] Confirm one synthesized paired-comment voice result in a private Guest Mode DM; Telegram delivered it to the correctly attributed remote peer without visible fallback text.
-- [ ] Confirm one local document and one synthesized voice/audio result in group Guest Mode.
-- [ ] Record a focused client/API caveat only if live behavior contradicts the one-result and staging contracts.
-
-Done when: private and group Guest Mode each have direct document and voice/audio delivery evidence, or a confirmed Telegram limitation is documented.
-
-## P1 — Compaction Status Ownership And Native Activity
-
-Context: Pi already renders its own compaction lifecycle, while pi-telegram currently overrides its terminal status row with `compacting` whenever the shared compaction flag is set. This duplicates Pi-owned state and hides the distinction between Telegram-owned activity and unrelated automatic/session compaction. Manual `/compact` already calls the typing-loop port and automatic compaction starts typing only when an active Telegram turn exists, so the reported absence of Telegram `…typing` needs transport-level and live verification rather than an assumed rewrite.
-
-Planned work:
-
-- [x] Remove `compacting` as a pi-telegram terminal status label while retaining the internal compaction flag for queue/dispatch safety and explicit diagnostics.
-- [x] Track compaction origin for status projection: confirmed Telegram `/compact` and auto-compaction inside a Telegram-owned turn render normal `Active`; local/autonomous/background compaction keeps the stable `connected`, `leader`, or `follower` role.
-- [x] Define and verify the native activity matrix: Telegram-owned compaction targets the invoking/active thread plus `All`; non-Telegram compaction uses the connected instance target plus `All` without changing terminal role semantics.
-- [x] Trace manual confirmation, `session_before_compact`, `session_compact`, completion, error, timeout, abort, and shutdown ordering to ensure one keyed typing loop remains active for the whole compaction window and always stops.
-- [x] Add transport-level regressions that assert actual `sendChatAction(typing)` targets and keepalive lifecycle, not only invocation of a mocked `startTypingLoop` callback.
-- [x] Replace status tests that currently require `compacting` with Telegram-owned `Active` and non-Telegram stable-role cases; preserve `/telegram-status` compaction diagnostics where operationally useful.
-- [ ] Capture live evidence for manual Telegram compaction, auto-compaction during a Telegram turn, and non-Telegram auto-compaction before finalizing the activity contract.
-
-Done when: Pi remains the only terminal owner of the `compacting` label, pi-telegram status reflects Telegram ownership rather than generic compaction, and Telegram native `…typing` remains visible and correctly targeted throughout every confirmed compaction class without leaking afterward.
-
-## P1 — Leader Endpoint Loss Recovery
-
-Context: live evidence showed a process retaining a fresh transport lock and active polling while its Threaded Mode Unix socket path was absent. The likely trigger was external removal of the shared Telegram temp directory while the owner process remained alive. The local server keeps listening on the unlinked Unix socket but `start()` treats its in-memory server handle as sufficient, leader health checks only Bot API transport, and a new instance therefore exhausts follower-registration retries with `ENOENT`. This is a real diagnosable recovery gap, but not yet evidence for a broad readiness protocol or automatic takeover; force-acquiring while the old owner may still run `getUpdates` would risk split-brain.
-
-Planned work:
-
-- [x] Reproduce deterministically by unlinking only the active Unix leader socket while its process, polling runtime, and in-memory server remain live. Native Windows named pipes have no equivalent filesystem path to unlink, so recovery remains Unix-specific unless separate named-pipe evidence appears.
-- [x] Let the owning Threaded Mode runtime detect an externally missing Unix endpoint during its existing health/prune cadence and restart only the local bus server without changing lock ownership, leader epoch, polling, or thread bindings.
-- [x] Make initial follower registration report `live owner / unreachable bus endpoint` after bounded retries, with direct operator guidance; do not add automatic or force takeover without separate evidence that the old owner cannot still poll.
-- [x] Keep intentional classic ownership unchanged because classic mode does not require a bus endpoint.
-- [x] Add focused regressions for Unix endpoint unlink/rebind, bounded follower diagnosis, leader reload overlap, and no duplicate `getUpdates` ownership; add Windows coverage only for behavior the named-pipe transport can reproduce.
-- [ ] Capture live recovery evidence without deleting lock/state or creating a replacement Telegram thread.
-
-Done when: the confirmed endpoint-loss scenario either self-recovers under the existing owner or produces precise safe remediation, while classic mode and single-owner polling remain unchanged.
+_This backlog tracks only open release-relevant work: live runtime verification, evidence-gated Telegram client follow-ups, and upstream Pi API blockers. Completed outcomes and validation evidence belong in `CHANGELOG.md`, not in this queue._
 
 ## P1 — Promoted Follower Reload Evidence
 
@@ -98,6 +54,8 @@ Blocked: upstream Pi core API. Issue: https://github.com/earendil-works/pi/issue
 
 Context: Threaded Mode manual followers are separate visible Pi processes. Same-thread `/new` is a different feature: replacing the current Pi session inside the same Telegram thread. Extension-only hacks are rejected because they would desynchronize Pi lifecycle/TUI semantics.
 
+Current upstream evidence: Pi 0.80.6 safely exposes `ctx.newSession()` to registered extension commands through `ExtensionCommandContext`, including fresh-context rebinding after replacement. Telegram update and callback handlers still receive only `ExtensionContext`, and extension-origin `pi.sendUserMessage()` deliberately disables slash-command handling. The upstream maintainer described an async extension bridge as potentially possible after the current refactor, but no supported API exists yet.
+
 Required upstream shape:
 
 - `pi.newSession(...)` or `pi.requestSessionReplacement(...)` callable from trusted extension runtime code.

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.21.0: Activity And Delivery Extension Platform
+
+- `[Platform Documentation]` Completed 0.21 discoverability across the README, public API inventory/smoke checklist, Activity and Delivery contracts, architecture map, Sections reference, package contents, documented consumer policy examples, and the external demo-project reference. Removed the completed platform epic from `BACKLOG.md` while preserving deferred media/process boundaries and the concrete callback revisit trigger in docs. Impact: extension authors can find and validate the complete supported surface without `/lib` imports, and open-work context now contains only unfinished work.
+- `[Platform Validation]` Added a full-runtime classic-mode regression proving public activity delivery reaches the assigned Telegram surface while `agent_start` remains independent from the consumer's pending Bot API send. Expanded scope coverage to distinguish active-turn, assigned-instance, and aggregate targets and verify autonomous activity can opt into aggregate delivery; existing leader/follower transport, authorization, stale-generation, ordering, chunk reconciliation, and cleanup regressions complete the platform matrix. Impact: the 0.21 extension contracts now carry focused domain, public-boundary, and runtime integration proof.
+- `[Callback Boundary]` Confirmed that the issue #126 consumer shape needs no second managed callback registry: Sections already own interactive Settings namespacing, answers, edits, navigation, and cleanup, while delivered activity rows remain non-interactive and raw update handlers stay the low-level escape hatch. Impact: the platform avoids duplicate callback ownership and records the concrete trigger for revisiting the boundary.
+- `[Activity API]` Added the public `@llblab/pi-telegram/activity` membrane and wired Pi input, agent, assistant text/reasoning, executed-tool, compaction, settlement, and shutdown lifecycle signals into evidence-based activity/source identities. Isolated asynchronous per-handler queues preserve semantic order, coalesce adjacent deltas, fence shutdown generations, report handler failures, and provide fresh target-aware delivery contexts without awaiting consumer work or duplicating bridge previews/finals. Impact: extension consumers can build lifecycle-adjacent Telegram surfaces without private Pi contexts, raw provider messages, or bridge transport ownership.
+- `[Delivery API]` Added the public `@llblab/pi-telegram/delivery` membrane for ownership-gated operational views and chat actions across active-turn, current-instance, aggregate, and explicitly authorized targets. Logical handles reconcile chunked send/edit/delete operations, per-target queues preserve ordering, followers route through the leader transport, and reload/session replacement invalidates old generations without captured Pi contexts. Impact: companion extensions can now deliver lifecycle-adjacent Telegram UI through stable ports instead of importing bridge internals or owning another bot client.
+- `[Public API]` Documented the complete capability inventory, intentional private boundaries, target policy, structured delivery failures, callback boundary decision, and deferred media/process controls; added public-boundary, classic/leader/follower policy, chunk reconciliation, ordering, and lifecycle regressions. Impact: extension authors can distinguish supported platform capabilities from deliberate safety boundaries and the completed 0.21 extension-platform surface.
+- `[Pi Compatibility]` Set the Activity platform floor to Pi/core/AI `0.80.6`, registered the public typed `agent_settled` lifecycle event directly, and aligned Telegram model controls with Pi's `max` thinking level. Impact: activity identity now closes at a supported terminal boundary without unsafe event casts or silently merging unrelated runs on older Pi versions.
+- `[Delivery Lifecycle]` Constructed a fresh Delivery runtime and generation for every session start, shut down displaced bindings, and fenced queued or multi-step in-flight work at every transport boundary. Impact: session replacement cannot revive old handles or let an old operation continue chunks, edits, deletes, or chat actions through a new session.
+- `[Delivery Recovery]` Added recoverable partial handles to failed multi-chunk sends and edit growth, tracking every message id that remains visible after transport failure. Impact: callers can deterministically retry or clean up a partially materialized logical view instead of losing its only valid handle.
+- `[Activity Compaction]` Added explicit abandonment for standalone compaction activities that never receive `session_compact`, triggered by the next run/compaction boundary or the bounded observer timeout, while preserving compaction inside an active agent identity and ignoring late completion. Impact: cancelled or failed compaction cannot leak its activity id or source into an unrelated run.
+- `[Activity Diagnostics]` Reconciled the public contract with implemented diagnostics: handler failures carry redacted identity metadata through the bounded bridge recorder, while 0.21 intentionally exposes no queue phase/length/latency telemetry or drop policy beyond adjacent delta coalescing. Impact: consumers can reason from documented backpressure behavior without relying on diagnostics the runtime does not emit.
+- `[Activity Lifecycle]` Recreated the Activity dispatcher with a fresh generation on every session start while stopping and clearing the retiring generation at shutdown, and bound handler contexts to their exact dispatcher generation and registration. Impact: same-process session replacement resumes normalized lifecycle delivery while blocked handlers from the retiring session fail closed instead of sending stale work through replacement Delivery.
+- `[Guest Identity]` Kept private Guest Mode location identity anchored to the strongest remote-conversation evidence and excluded bot-authored replies from guest resolution, while retaining a non-bot replied peer as a final fallback when chat/caller identity is absent. Impact: replying to a Guest Mode bot response preserves `[telegram|guest:<remote-user>]` alongside `[reply|from:<bot>]` instead of replacing the conversation peer with the bot username.
+
 ## 0.20.6: Guest Attribution And Voice Action Hotfix
 
 - `[Voice Action Syntax]` Hidden `telegram_voice` actions now accept the intuitive paired form `<!-- telegram_voice ... -->...<!-- /telegram_voice -->` alongside inline, attribute-text, and single-comment multiline forms. The parser captures a non-empty multiline body and preserves language/rate attributes while leaving surrounding prose visible. Impact: agents can use an explicit closing tag without leaking the intended TTS payload as ordinary text.

package/README.md

@@ -24,6 +24,8 @@ From git:
 pi install git:github.com/llblab/pi-telegram
 ```
 
+The 0.21 extension platform requires Pi `0.80.6` or newer. Its Activity API uses the public `agent_settled` lifecycle event to keep retries/continuations under one activity identity and release that identity only after the run fully settles.
+
 ## Quick Start
 
 ### 1. Create a Telegram bot
@@ -217,12 +219,14 @@ Companion extensions can integrate with Telegram without owning polling or trans
 - Register Telegram slash commands.
 - Add menu sections and settings surfaces.
 - Add compact status rows.
+- Deliver target-aware operational views and chat actions from companion code.
+- Observe normalized assistant, reasoning, tool, compaction, and settlement activity without blocking Pi.
 - Handle update/callback namespaces.
 - Provide inbound preprocessing handlers.
 - Provide outbound voice synthesis.
 - Use direct delivery helpers for explicit local/TUI sends.
 
-Stable public entrypoints are documented in [Public API](./docs/public-api.md), [Extension Sections](./docs/sections.md), [Inbound Handlers](./docs/inbound.md), [Outbound Handlers](./docs/outbound.md), [Updates](./docs/updates.md), and [Voice Integration](./docs/voice.md).
+Stable public entrypoints are documented in [Public API](./docs/public-api.md), [Telegram Delivery API](./docs/delivery.md), [Telegram Activity API](./docs/activity.md), [Extension Sections](./docs/sections.md), [Inbound Handlers](./docs/inbound.md), [Outbound Handlers](./docs/outbound.md), [Updates](./docs/updates.md), and [Voice Integration](./docs/voice.md).
 
 ## Safety Boundaries
 
@@ -241,6 +245,8 @@ Telegram is a companion surface around a live Pi runtime, not a second runtime.
 
 - [Architecture](./docs/architecture.md) — runtime, domains, queue, transport, and Threaded Mode overview.
 - [Public API](./docs/public-api.md) — package entrypoints and stable companion-extension contracts.
+- [Telegram Delivery API](./docs/delivery.md) — target-aware operational views, logical message handles, and lifecycle-safe transport.
+- [Telegram Activity API](./docs/activity.md) — normalized lifecycle events, source identity, non-blocking delivery contexts, and consumer policy examples.
 - [Inbound Handlers](./docs/inbound.md) — Telegram-to-Pi preprocessing pipelines.
 - [Outbound Handlers](./docs/outbound.md) — final text/voice/file transformation and delivery.
 - [Voice Integration](./docs/voice.md) — STT/TTS provider model and reply policies.

package/api/activity.ts

@@ -0,0 +1,15 @@
+/**
+ * Public Telegram activity API
+ * Zones: package boundary, pi agent lifecycle, extension interop
+ * Exposes normalized non-blocking activity registration while keeping lifecycle wiring and dispatch internals package-private
+ */
+
+export {
+  registerTelegramActivityHandler,
+  type TelegramActivityContext,
+  type TelegramActivityEnvelope,
+  type TelegramActivityEvent,
+  type TelegramActivityHandlerRegistration,
+  type TelegramActivitySource,
+  type TelegramActivityTarget,
+} from "../lib/activity.ts";

package/api/commands.ts

@@ -1,6 +1,6 @@
 /**
  * Public Telegram commands API
- * Zones: package boundary, companion extension interop
+ * Zones: package boundary, extension interop
  * Exposes the stable Telegram slash-command registration surface while keeping registry internals package-private
  */
 

package/api/delivery.ts

@@ -0,0 +1,21 @@
+/**
+ * Public Telegram delivery API
+ * Zones: package boundary, telegram delivery, extension interop
+ * Exposes target-aware operational view delivery while keeping transport and runtime binding internals package-private
+ */
+
+export {
+  deleteTelegramView,
+  editTelegramView,
+  sendTelegramChatAction,
+  sendTelegramView,
+  type SendTelegramViewOptions,
+  type TelegramDeliveryChatAction,
+  type TelegramDeliveryFailureReason,
+  type TelegramDeliveryHandle,
+  type TelegramDeliveryParseMode,
+  type TelegramDeliveryResult,
+  type TelegramDeliveryScope,
+  type TelegramDeliveryTarget,
+  type TelegramDeliveryView,
+} from "../lib/delivery.ts";

package/api/inbound.ts

@@ -1,6 +1,6 @@
 /**
  * Public Telegram inbound API
- * Zones: package boundary, companion extension interop
+ * Zones: package boundary, extension interop
  * Exposes the stable programmatic inbound handler surface while keeping handler runtime internals package-private
  */
 

package/api/keyboard.ts

@@ -1,6 +1,6 @@
 /**
  * Public Telegram keyboard API
- * Zones: package boundary, companion extension interop
+ * Zones: package boundary, extension interop
  * Exposes shared inline-keyboard structural types without runtime exports
  */
 

package/api/outbound.ts

@@ -1,6 +1,6 @@
 /**
  * Public Telegram outbound API
- * Zones: package boundary, companion extension interop
+ * Zones: package boundary, extension interop
  * Exposes stable outbound handler and diagnostics surfaces while keeping delivery internals package-private
  */
 

package/api/sections.ts

@@ -1,6 +1,6 @@
 /**
  * Public Telegram sections API
- * Zones: package boundary, companion extension interop
+ * Zones: package boundary, extension interop
  * Exposes the stable managed Telegram menu-section surface while keeping registry internals package-private
  */
 

package/api/status.ts

@@ -1,7 +1,7 @@
 /**
  * Public Telegram status API
- * Zones: package boundary, companion extension interop
- * Exposes compact status-menu line registration for companion extensions while keeping status rendering internals package-private
+ * Zones: package boundary, extension interop
+ * Exposes compact status-menu line registration for extension consumers while keeping status rendering internals package-private
  */
 
 export {

package/api/updates.ts

@@ -1,6 +1,6 @@
 /**
  * Public Telegram updates API
- * Zones: package boundary, companion extension interop
+ * Zones: package boundary, extension interop
  * Exposes the stable raw-update handler surface while keeping update routing internals package-private
  */
 

package/api/voice.ts

@@ -1,6 +1,6 @@
 /**
  * Public Telegram voice API
- * Zones: package boundary, companion extension interop
+ * Zones: package boundary, extension interop
  * Exposes the stable STT/TTS provider surface and voice policy helpers
  */
 

package/docs/README.md

@@ -8,6 +8,8 @@ Living index of project documentation in `/docs`.
 
 - [architecture.md](./architecture.md) — Overview of the Telegram bridge runtime, optional profile isolation, queueing model, native Rich Markdown delivery, UI/compat rendering, and interactive controls
 - [public-api.md](./public-api.md) — Stable public API map: package entrypoints, commands, config, assistant markup, extension APIs, smoke examples, and compatibility boundaries
+- [delivery.md](./delivery.md) — Target-aware companion delivery contract for operational views, logical message handles, target scopes, lifecycle fencing, and leader/follower transport
+- [activity.md](./activity.md) — Normalized Pi lifecycle API for extension-owned reasoning, intermediate prose, tool activity, source identity, delivery contexts, and consumer policy examples
 - [../.agents/skills/telegram-bot/SKILL.md](../.agents/skills/telegram-bot/SKILL.md) — Agent-facing Telegram Bot API lookup skill backed by a local full Bot API reference
 - [../.agents/skills/domain-dag/SKILL.md](../.agents/skills/domain-dag/SKILL.md) — Project-local Domain DAG architecture skill and validator guidance
 - [command-templates.md](./command-templates.md) — Portable command-template standard core

package/docs/activity.md

@@ -0,0 +1,294 @@
+# Telegram Activity API
+
+## Purpose
+
+The Telegram Activity API lets trusted extension consumers observe normalized Pi work lifecycle without importing pi-telegram internals, correlating raw Pi events with bridge state, or capturing session contexts.
+
+It is a higher-level event surface over the [Telegram Delivery API](./delivery.md). Activity owns lifecycle normalization and event routing; delivery owns target authorization, rendering transport, ordering, chunk reconciliation, and stale-generation behavior.
+
+The public membrane is:
+
+```ts
+import {
+  registerTelegramActivityHandler,
+} from "@llblab/pi-telegram/activity";
+```
+
+An issue #126 consumer can own optional Settings policy for reasoning, intermediate assistant prose, and tool rows. Those visibility choices do not become mandatory bridge-core settings.
+
+## Ownership Boundary
+
+Consumer extension code owns:
+
+- Which activity event classes are visible.
+- Settings state and presentation policy.
+- Rendering event payloads into operational views.
+- Coalescing or replacing its own visible activity documents.
+- Redacting additional domain-specific data before display.
+
+pi-telegram owns:
+
+- Mapping Pi lifecycle events into one normalized activity stream.
+- Correlating events with the current Telegram turn or Pi instance.
+- Stable activity/run identity within one runtime generation.
+- Default delivery scope selection.
+- Handler registration, ordering, isolation, disposal, and diagnostics.
+- Avoiding duplicate provider tool-call versus executed-tool events.
+- Session shutdown fencing and fresh delivery contexts.
+
+Pi owns the source lifecycle and provider event protocol. The Activity API requires Pi `0.80.6` or newer because `agent_settled` is the terminal boundary that distinguishes a fully settled activity from automatic retry, compaction, and queued continuation. The API does not invent reasoning when a provider does not expose it.
+
+## Registration
+
+```ts
+export interface TelegramActivityHandlerRegistration {
+  id: string;
+  order?: number;
+  handle: (
+    event: TelegramActivityEvent,
+    ctx: TelegramActivityContext,
+  ) => void | Promise<void>;
+}
+
+export function registerTelegramActivityHandler(
+  registration: TelegramActivityHandlerRegistration,
+): () => void;
+```
+
+Rules:
+
+- `id` is a stable consumer identity, normally derived from package identity plus a local activity suffix.
+- Duplicate active ids are rejected rather than silently stacking duplicate Telegram output.
+- Handlers run by `order`, then `id`.
+- Registration returns a stale-safe disposer that removes only its own registration.
+- Consumers register on `session_start` and dispose on `session_shutdown`.
+- The bridge creates a fresh dispatcher generation on every `session_start`; shutdown stops and clears only the retiring generation, so same-process session replacement resumes delivery instead of leaving Activity permanently stopped.
+- Handler failures are isolated and recorded in `/telegram-status`; they never break Pi lifecycle or other handlers.
+
+## Activity Identity And Source
+
+```ts
+export type TelegramActivitySource =
+  | "telegram"
+  | "local"
+  | "autonomous"
+  | "unknown";
+
+export type TelegramActivityTarget = Readonly<TelegramDeliveryTarget>;
+
+export interface TelegramActivityEnvelope {
+  activityId: string;
+  sequence: number;
+  source: TelegramActivitySource;
+  target?: TelegramActivityTarget;
+  timestamp: number;
+}
+```
+
+`activityId` identifies one logical settled-work sequence inside the current delivery generation. `sequence` increases monotonically within that activity and lets consumers reject stale asynchronous rendering. Telegram-owned activities carry a frozen `target` captured when the activity starts; it contains only safe chat/thread identity, never a Telegram client or Pi context.
+
+Source classification follows evidence, not guesses:
+
+- `telegram`: a dispatched active Telegram turn exists.
+- `local`: the initiating Pi input event reports `interactive` or `rpc` and no Telegram turn owns the run.
+- `autonomous`: the initiating input reports `extension` and no Telegram turn owns the run.
+- `unknown`: retries, restored continuations, or runtimes without enough input evidence cannot be classified safely.
+
+Automatic retries, overflow compaction retries, and tool continuations inherit the current activity identity/source until `agent_settled`. A new unrelated `agent_start` after settlement allocates a new activity id.
+
+A standalone compaction owns a temporary activity only until `session_compact`. Pi does not expose a sibling-extension cancellation/failure callback after `session_before_compact`, so pi-telegram abandons that temporary identity at the first provable fallback boundary: the next `agent_start`, a replacement compaction start, session shutdown, or the existing five-minute compaction-observer timeout. A late `session_compact` after abandonment is ignored and cannot attach to the next run. Compaction inside an existing agent activity never clears that agent's identity.
+
+## Event Contract
+
+```ts
+export type TelegramActivityEvent = TelegramActivityEnvelope & (
+  | { type: "agent-start" }
+  | {
+      type: "assistant-text-delta";
+      contentIndex: number;
+      delta: string;
+    }
+  | {
+      type: "assistant-segment";
+      contentIndex: number;
+      text: string;
+      placement: "intermediate" | "final" | "terminal-partial";
+    }
+  | {
+      type: "reasoning-delta";
+      contentIndex: number;
+      delta: string;
+    }
+  | {
+      type: "reasoning-end";
+      contentIndex: number;
+      text: string;
+    }
+  | {
+      type: "tool-start";
+      toolCallId: string;
+      toolName: string;
+      args: unknown;
+    }
+  | {
+      type: "tool-update";
+      toolCallId: string;
+      toolName: string;
+      update: unknown;
+    }
+  | {
+      type: "tool-end";
+      toolCallId: string;
+      toolName: string;
+      result: unknown;
+      isError: boolean;
+    }
+  | {
+      type: "compaction-start";
+      reason: "manual" | "threshold" | "overflow" | "unknown";
+    }
+  | {
+      type: "compaction-end";
+      reason: "manual" | "threshold" | "overflow" | "unknown";
+    }
+  | { type: "agent-end" }
+  | { type: "agent-settled" }
+);
+```
+
+### Assistant segment classification
+
+Provider stream events expose `text_start`, `text_delta`, and `text_end`, but `text_end` alone does not prove whether prose is intermediate or final. The normalizer therefore holds a completed text segment briefly until the next provider boundary proves placement:
+
+- A following `toolcall_start` classifies the pending text as `intermediate`.
+- A following successful `done` classifies it as `final`.
+- A following `error` classifies it as `terminal-partial`.
+- A new text block flushes any older still-pending segment as `intermediate` only when the provider event order proves another block follows.
+
+`assistant-text-delta` remains available for extensions that want progressive rendering. Consumers that only want complete intermediate prose should ignore deltas and render `assistant-segment` where `placement === "intermediate"`.
+
+### Reasoning
+
+Pi provider events use `thinking_*`; the public product term is `reasoning`. The normalizer maps `thinking_delta` to `reasoning-delta` and `thinking_end` to `reasoning-end`.
+
+- Signed/redacted provider metadata is not exposed as display text.
+- Empty reasoning blocks are skipped.
+- Providers that hide reasoning produce no reasoning events.
+- Consumers must treat reasoning as potentially sensitive and disabled by default.
+
+### Tools
+
+Tool activity uses Pi's executed-tool lifecycle (`tool_execution_start/update/end`), not provider `toolcall_*` payloads. Provider tool-call boundaries are used only to classify preceding assistant prose. This prevents duplicate tool rows and reports actual execution results.
+
+`args`, `update`, and `result` may contain paths, source text, command output, or other sensitive data. They are available to trusted local extension code but must not be rendered wholesale by default. Reference UI should summarize tool name/state and expose bounded details only through explicit policy.
+
+## Delivery Context
+
+```ts
+export interface TelegramActivityContext {
+  activityId: string;
+  sequence: number;
+  source: TelegramActivitySource;
+  defaultScope: TelegramDeliveryScope;
+  send(
+    view: TelegramDeliveryView,
+    options?: {
+      scope?: TelegramDeliveryScope;
+      replyToMessageId?: number;
+    },
+  ): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
+  edit(
+    handle: TelegramDeliveryHandle,
+    view: TelegramDeliveryView,
+  ): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
+  delete(
+    handle: TelegramDeliveryHandle,
+  ): Promise<TelegramDeliveryResult<void>>;
+  chatAction(
+    action: TelegramDeliveryChatAction,
+    options?: { scope?: TelegramDeliveryScope },
+  ): Promise<TelegramDeliveryResult<void>>;
+}
+```
+
+Default scope:
+
+- `telegram` uses `{ kind: "target", target: event.target }`, binding delayed handlers to the immutable originating thread rather than whichever turn happens to be active later.
+- `local`, `autonomous`, and `unknown` use `{ kind: "instance" }`.
+
+Handlers may explicitly choose aggregate or another authorized scope. Context methods delegate to the public delivery runtime on every call; they do not retain Telegram clients, Pi contexts, or transport ownership objects. The Delivery API rechecks authorization when an operation runs, so a captured target that is no longer owned fails closed instead of rerouting.
+
+A handler may still receive events while no target is currently deliverable. Delivery then returns the normal structured `target-unavailable`, `target-unauthorized`, or `runtime-unavailable` result.
+
+## Dispatch And Backpressure
+
+Pi lifecycle must not wait for extension rendering or Telegram transport.
+
+- Lifecycle hooks normalize and enqueue activity events synchronously, then return.
+- Each handler owns a serialized asynchronous queue so its event order is stable without blocking other handlers.
+- Handler queues and contexts are generation-bound. `session_shutdown` stops queued events immediately, and an already-running handler receives `runtime-unavailable` instead of delivering through a replacement session after it resumes.
+- Disposing a handler also fences contexts captured from that registration; they cannot outlive their ownership and adopt another registration with the same id.
+- High-frequency `assistant-text-delta`, `reasoning-delta`, and `tool-update` events may coalesce only with the immediately adjacent event of the same type, activity id, content/tool id, and handler queue.
+- Boundary events (`assistant-segment`, `reasoning-end`, tool start/end, compaction, agent end/settled) are never dropped or reordered.
+- The 0.21 dispatcher does not impose an event-count drop policy or emit queue-length diagnostics. Adjacent delta/update coalescing reduces common streaming pressure, but boundary events accumulate behind a slow handler; consumers must keep handler work bounded and delegate long-lived work outside the callback when appropriate.
+
+The Delivery API independently serializes concrete Telegram operations per target. Activity serialization preserves semantic event order; delivery serialization preserves transport order.
+
+## Lifecycle Mapping
+
+The bridge maps Pi hooks as follows:
+
+- `input`: capture source evidence for the next logical activity.
+- `agent_start`: allocate or reuse activity identity and emit `agent-start` after Telegram queue consumption establishes active-turn ownership.
+- `message_update.assistantMessageEvent`: normalize text/reasoning/provider boundaries.
+- `tool_execution_start/update/end`: emit executed tool events.
+- `session_before_compact` / `session_compact`: emit compaction boundaries and preserve activity identity across retry compaction; abandon an unterminated standalone compaction at the next lifecycle boundary or observer timeout rather than merging it into another run. A missing or unrecognized reason maps to `unknown` rather than guessing.
+- `agent_end`: emit low-level run completion but keep identity alive for retry/follow-up work.
+- `agent_settled`: emit terminal settlement, flush pending terminal segments, and release activity identity.
+- `session_shutdown`: stop dispatch, clear pending normalization state, and invalidate delivery generation through the existing delivery lifecycle.
+
+## Diagnostics
+
+Duplicate registration fails synchronously. When a handler throws or rejects, the dispatcher forwards only the handler id, event type, activity id, and error to pi-telegram's existing bounded/redacted runtime event recorder. The bridge does not copy reasoning, assistant prose, tool arguments/results, Telegram payloads, or queue contents into diagnostic metadata. It does not currently record queue phase, queue length, coalescing counts, or handler latency.
+
+The first implementation has no public Activity diagnostics getter because handler failures already flow through bridge runtime diagnostics and `/telegram-status`. Add queue telemetry or a dedicated getter only when an observed consumer needs inspectable backpressure state.
+
+## Security And Non-Goals
+
+The Activity API does not:
+
+- Enable reasoning visibility by default.
+- Guarantee reasoning availability across providers.
+- Expose signed/redacted reasoning metadata.
+- Render raw tool arguments or results automatically.
+- Replace assistant final replies or Rich Draft previews.
+- Mutate queues, models, thinking levels, sessions, or process state.
+- Expose Telegram clients, bot tokens, Pi contexts, or private runtime objects.
+- Block Pi lifecycle on extension handlers or Telegram delivery.
+
+## Validation Contract
+
+The implementation must cover:
+
+- Stable id registration, ordering, duplicate rejection, and stale-safe disposal.
+- Telegram, local, autonomous, and unknown source evidence.
+- Identity reuse across retry/compaction and reset at settlement.
+- Text delta flow and intermediate/final/terminal segment classification.
+- Reasoning mapping and empty/hidden reasoning behavior.
+- Executed tool start/update/end without provider tool-call duplication.
+- Default active-turn versus instance delivery scopes.
+- Adjacent delta/update coalescing and boundary preservation.
+- Handler error isolation, non-blocking lifecycle, shutdown fencing, and redacted diagnostics.
+- Public package import without `/lib` reach-through.
+
+## Consumer Policy Pattern
+
+The registration and delivery examples above provide the complete public building blocks for issue #126-style visibility policy:
+
+- Reasoning can default off and send completed `reasoning-end` blocks only when enabled.
+- Intermediate prose can default off and send only `assistant-segment` events with `placement: "intermediate"`, never the final assistant segment.
+- Tool rows can default on, show only tool name/state, and edit generation-bound logical handles from running to done/failed without exposing arguments or results.
+- Interactive toggles belong in a registered Section and Settings row; activity messages can remain non-interactive.
+- `session_shutdown` should dispose stable registrations and drop retained delivery handles, so reload/session replacement cannot reuse old contexts or handles.
+
+The separate [`pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) project remains the maintained companion-extension and managed-UI reference. This document owns the Activity-specific usage pattern; pi-telegram does not ship a redundant `examples/` package directory.