@llblab/pi-telegram 0.20.6 → 0.21.0

package/docs/architecture.md

@@ -14,6 +14,8 @@ The bridge is a mobile companion for a live Pi session, not a remote terminal. I
 This document is the architectural map. Focused behavior standards live in sibling docs:
 
 - [Public API](./public-api.md) — stable commands, config, package entrypoints, assistant markup, extension APIs, and compatibility boundaries.
+- [Telegram Delivery API](./delivery.md) — target-aware operational views, logical message handles, lifecycle fencing, and leader/follower transport.
+- [Telegram Activity API](./activity.md) — normalized Pi lifecycle events, activity/source identity, non-blocking extension dispatch, and delivery contexts.
 - [UI Style](./ui-style.md) — inline UI labels, navigation, state markers, cards, and dialogs.
 - [Callback Namespaces](./callback-namespaces.md) — callback prefix ownership and fallback rules.
 - [Sections](./sections.md) — structured Telegram menu sections.
@@ -64,6 +66,8 @@ The repository uses a **Flat Domain DAG**:
 - `sections`: Telegram menu-section registry, opaque section callback tokens, render/callback dispatch, safe section ports, and diagnostics.
 - `keyboard`: shared inline-keyboard reply-markup shape only; feature domains own labels, callback data, and behavior.
 - `preview` / `replies` / `rendering`: throttled native Rich Markdown draft delivery, native final reply delivery, reply parameters, transport-limit chunking, and remaining Telegram HTML rendering for bridge-owned UI/compatibility surfaces.
+- `delivery`: public extension operational-view delivery, active-turn/instance/aggregate/authorized target policy, logical chunk handles, per-target ordering, runtime generation fencing, and the process-local runtime membrane. Its bridge adapter composes the established UI/compat reply renderer with narrow bus-aware Telegram API and ownership ports; it never exposes bot clients or Pi contexts.
+- `activity`: public normalized Pi lifecycle registration, activity/source identity, assistant segment and reasoning normalization, executed-tool events, non-blocking per-handler queues, delivery contexts, compatibility adapters, and shutdown fencing. It does not own visibility policy or Telegram rendering.
 - `outbound-markup`: top-level assistant action comment parsing, attribute parsing, voice reply planning, and preview/delivery stripping.
 - `outbound`: outbound text transformations, voice/button artifact delivery, and generated callback actions.
 - `outbound-attachments`: `telegram_attach`, queued outbound files, stat/limit checks, and photo/document delivery classification.
@@ -233,7 +237,7 @@ Assistant delivery guarantees:
 
 - Model-authored Markdown is the source of truth; the bridge does not pre-render assistant Markdown to HTML unless the operator selects `assistant.rendering: "html"` for compatibility.
 - Before native Rich Markdown delivery, the bridge normalizes known Bot-API-fragile source forms without changing visible meaning, including space-after-marker blockquotes and dollar-prefixed ticker atoms that Telegram may otherwise treat as unterminated math.
-- Prompt context blocks use compact metadata (`[tag|key:value]`) as the stable inbound contract. `[telegram...]` names the current surface only: owner/current turns use `[telegram]` or `[telegram|thread:<name>]`; guest-mode turns use `[telegram|guest:<group-title-or-peer-username-or-id>]`. In a private Guest Mode turn the paired owner's `from` identity is never the guest: an explicit replied peer wins, then the remote private-chat identity, then non-owner caller metadata; username falls back to the remote display name and numeric id. Source authors for quoted/forwarded material and their files are carried by `[reply|from:<username-or-id>]`, `[forward|from:<username-or-id>]`, and `[attachments|from:<username-or-id>]`, while plain `[attachments]` remains current-turn attachments and is ordered before reply/forward/source context.
+- Prompt context blocks use compact metadata (`[tag|key:value]`) as the stable inbound contract. `[telegram...]` names the current surface only: owner/current turns use `[telegram]` or `[telegram|thread:<name>]`; guest-mode turns use `[telegram|guest:<group-title-or-peer-username-or-id>]`. In a private Guest Mode turn the paired owner's `from` identity is never the guest: the remote private-chat identity wins, then non-owner caller metadata, with a non-bot replied peer available only as a final identity fallback when stronger conversation evidence is absent; username falls back to the remote display name and numeric id. Reply attribution still belongs independently in `[reply|from:...]`, and a replied bot can never define or replace the current `[telegram|guest:...]` location identity. Source authors for quoted/forwarded material and their files are carried by `[reply|from:<username-or-id>]`, `[forward|from:<username-or-id>]`, and `[attachments|from:<username-or-id>]`, while plain `[attachments]` remains current-turn attachments and is ordered before reply/forward/source context.
 - Quoted rich replies use Telegram `rich_message` blocks as the prompt-context source when available, so `[reply]` context receives rendered plain text instead of raw `InputRichMessage.markdown` fallback text.
 - Long native Markdown replies are split only at Telegram Rich Message transport limits; oversized fenced code, display-math, and fully wrapped inline-formatting blocks are rewrapped per chunk so persisted Rich Markdown chunks remain structurally valid.
 - When Draft previews are enabled, streaming previews pass structurally closed assistant Markdown prefixes through to `sendRichMessageDraft` with ownership checks, voice suppression, and serialized flushes. Unclosed inline spans, links, fenced code, comments, and display-math blocks are held back until a safe boundary exists. Draft failures are recorded and the failing frame is skipped instead of degrading to raw plain-message previews, because partial Markdown can be invalid while the final message remains valid.
@@ -265,6 +269,8 @@ Unknown callback data outside owned prefixes is forwarded as `[callback] <data>`
 
 - Raw update observation/consumption: [Updates](./updates.md).
 - Telegram-native slash commands: `registerTelegramCommand()` from [Public API](./public-api.md#commands).
+- Target-aware operational views and chat actions: [Telegram Delivery API](./delivery.md).
+- Normalized non-blocking Pi lifecycle events: [Telegram Activity API](./activity.md); the separate [`pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) project remains the companion-extension reference.
 - Structured inline UI sections: [Sections](./sections.md).
 - Callback namespace discipline: [Callback Namespaces](./callback-namespaces.md).
 - Voice/STT/TTS providers: [Voice Integration](./voice.md).

package/docs/delivery.md

@@ -0,0 +1,224 @@
+# Telegram Delivery API
+
+## Purpose
+
+The Telegram Delivery API gives trusted extension consumers a safe programmatic way to render operational Telegram UI without importing bridge internals or owning Telegram transport.
+
+It fills the boundary between callback-scoped `TelegramSectionContext.open()` and agent-callable `telegram_message` / `telegram_attach`. It does not replace normal active-turn final replies, Sections, outbound handlers, or raw update handlers.
+
+The public package membrane is:
+
+```ts
+import {
+  deleteTelegramView,
+  editTelegramView,
+  sendTelegramChatAction,
+  sendTelegramView,
+} from "@llblab/pi-telegram/delivery";
+```
+
+## Ownership Boundary
+
+Consumer extension code owns:
+
+- When an operational view should appear.
+- View text, parse mode, and optional inline keyboard.
+- Its own settings and callback policy.
+- Retaining a returned handle only for the current live extension generation.
+
+pi-telegram owns:
+
+- Active-turn and current-instance target resolution.
+- Pairing and target authorization.
+- Classic direct transport versus follower-to-leader routing.
+- Named-profile isolation.
+- Per-target operation ordering.
+- Telegram text limits, rendering, and chunk reconciliation.
+- Runtime generation checks, shutdown behavior, and diagnostics.
+- Bot credentials, polling, offsets, retries, and raw API clients.
+
+## Public Contract
+
+### Views
+
+```ts
+export type TelegramDeliveryParseMode = "plain" | "html" | "markdown";
+
+export interface TelegramDeliveryView {
+  text: string;
+  parseMode?: TelegramDeliveryParseMode;
+  replyMarkup?: TelegramInlineKeyboardMarkup;
+}
+```
+
+`plain` is the default. Operational activity should prefer `plain` or explicit `html`. `markdown` exists for extension-authored content that naturally owns Markdown; the bridge converts it through the existing UI/compat Markdown-to-HTML renderer rather than entering the native assistant final-reply pipeline.
+
+`replyMarkup` accepts only structural keyboard data. Callback ownership stays with Sections or a registered raw update handler. The documented issue #126 consumer shape uses Sections for interactive Settings toggles and keeps delivered activity rows non-interactive, so a second managed callback registry would duplicate token, answer, edit, navigation, and cleanup ownership without a proven use case. Revisit only when a public-import-only consumer must generate managed callbacks independently of a registered Section context for arbitrary delivered messages.
+
+### Target scopes
+
+```ts
+export type TelegramDeliveryScope =
+  | { kind: "active-turn" }
+  | { kind: "instance" }
+  | { kind: "aggregate" }
+  | { kind: "target"; target: TelegramDeliveryTarget };
+
+export interface TelegramDeliveryTarget {
+  chatId: number;
+  threadId?: number;
+}
+```
+
+Resolution rules:
+
+- `active-turn` requires a current Telegram-owned turn and resolves its exact `{ chatId, threadId? }`.
+- `instance` resolves the current process's assigned follower/leader thread, or the paired private chat in classic mode. It does not silently fall back to an unrelated active thread.
+- `aggregate` resolves the paired private chat without `threadId`; it is the Threaded Mode `All` surface and the ordinary classic chat. Follower aggregate messages carry an internal authenticated-bus marker that the leader validates for the assigned chat and strips before Bot API transport; unmarked or cross-chat threadless follower writes remain denied.
+- `target` validates an explicit destination against the active profile and current runtime authority. A classic owner may target its paired private chat. A follower may target only its assigned thread or aggregate surface. A leader may target its own thread, aggregate surface, or a currently live bound thread for that profile. Unknown, stale, cross-profile, and unpaired targets are rejected.
+
+No scope selects another named profile. Profile activation remains session-local bridge state.
+
+### Handles
+
+```ts
+export interface TelegramDeliveryHandle {
+  readonly target: TelegramDeliveryTarget;
+  readonly messageIds: readonly number[];
+  readonly generation: string;
+}
+```
+
+A handle represents one logical view, which may span multiple Telegram messages after chunking. `generation` is an opaque runtime identity, not an authorization secret. Callers must not construct handles or persist them across reload/session replacement.
+
+Edit reconciles the logical view as one operation:
+
+- Existing chunks are edited in order.
+- Additional chunks are sent when the new view grows.
+- Surplus old chunks are deleted when the new view shrinks.
+- The returned handle replaces the previous handle.
+
+Delete removes every message still represented by the handle. Partial transport failure returns a structured failure and records diagnostics; it never pretends the whole logical view succeeded.
+
+### Results
+
+```ts
+export type TelegramDeliveryFailureReason =
+  | "runtime-unavailable"
+  | "target-unavailable"
+  | "target-unauthorized"
+  | "stale-handle"
+  | "invalid-view"
+  | "transport-failed";
+
+export type TelegramDeliveryResult<T> =
+  | { ok: true; value: T }
+  | {
+      ok: false;
+      reason: TelegramDeliveryFailureReason;
+      message: string;
+      partial?: T;
+    };
+```
+
+Expected availability, authorization, and lifecycle outcomes return failures rather than throwing. Programmer errors may still throw for malformed objects that cannot satisfy the TypeScript contract. Transport failures are redacted before reaching callers and are also recorded in bridge runtime diagnostics.
+
+When a multi-chunk `send` or growing `edit` fails after materializing part of the logical view, `partial` contains a valid handle for every message still visible from that operation. Callers may pass it to `editTelegramView` to reconcile the view or to `deleteTelegramView` for cleanup. A failure before any message exists omits `partial`; callers must never infer message ids or construct a handle.
+
+### Operations
+
+```ts
+export interface SendTelegramViewOptions {
+  scope: TelegramDeliveryScope;
+  replyToMessageId?: number;
+}
+
+export function sendTelegramView(
+  view: TelegramDeliveryView,
+  options: SendTelegramViewOptions,
+): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
+
+export function editTelegramView(
+  handle: TelegramDeliveryHandle,
+  view: TelegramDeliveryView,
+): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
+
+export function deleteTelegramView(
+  handle: TelegramDeliveryHandle,
+): Promise<TelegramDeliveryResult<void>>;
+
+export function sendTelegramChatAction(
+  action: "typing" | "upload_document" | "upload_photo" | "record_voice",
+  options: { scope: TelegramDeliveryScope },
+): Promise<TelegramDeliveryResult<void>>;
+```
+
+`replyToMessageId` applies only to the first chunk and must belong to the resolved chat. The initial contract exposes only actions already used by bridge-owned activity and delivery paths; it is not a generic Bot API action string.
+
+## Runtime Binding
+
+The public functions resolve a process-local runtime binding on every call. They never capture a Pi `ExtensionContext` or command context.
+
+The bridge constructs and binds a genuinely fresh delivery runtime during every `session_start`. It unbinds and shuts down the current runtime during `session_shutdown` before session-bound transport state is discarded; binding an unexpected replacement also shuts down the displaced runtime. Reload and session replacement therefore produce these outcomes:
+
+- A new call resolves the newly bound runtime after startup.
+- An old handle returns `stale-handle` for edit and delete.
+- A call while no generation is bound returns `runtime-unavailable`.
+- Queued operations from the old generation stop before transport begins.
+- An already-issued Telegram request may resolve during shutdown, but the old operation returns `runtime-unavailable` and cannot issue another edit, delete, chunk, or chat action afterward.
+- Old operations never adopt the replacement generation implicitly.
+
+The binding uses the same `globalThis` membrane pattern as other extension registries so package load order does not expose bridge internals. Only pi-telegram may bind or replace the runtime port.
+
+## Ordering And Delivery Semantics
+
+- Operations serialize per profile and concrete target. Different targets may progress independently.
+- `send`, logical `edit`, and logical `delete` preserve caller order for the same target.
+- Delivery uses the existing bridge API runtime so followers route allowlisted calls through the leader rather than contacting Telegram directly.
+- Text is chunked through the existing parse-mode-appropriate renderer/splitter. HTML chunks remain balanced, extension-authored Markdown becomes balanced UI/compat HTML, and plain chunks preserve text.
+- Inline keyboard markup attaches only to the final chunk of a logical view. Reply parameters attach only to the first chunk.
+- Edit growth sends additional chunks; edit shrink deletes surplus chunks; delete removes every chunk in handle order.
+- A partial send failure returns the ids already sent. A partial edit failure returns the original surviving ids plus every newly sent id, minus any surplus ids already deleted during shrink. The returned handle therefore remains sufficient for deterministic retry or cleanup.
+- The API does not participate in assistant preview/final deduplication and does not mutate the Telegram turn queue.
+- A successful operational send does not imply agent work, create a Pi prompt, or alter terminal status.
+
+## Diagnostics
+
+Failures record redacted runtime events under a delivery-specific category with operation, scope kind, profile, and failure reason. Diagnostics must not include bot tokens, unrestricted message bodies, callback payload secrets, or raw transport responses.
+
+A future `getTelegramDeliveryDiagnostics()` is unnecessary for the first slice because callers receive structured results and `/telegram-status` already owns bridge diagnostics. Add a dedicated diagnostics getter only if a real consumer needs registry-level introspection.
+
+## Security And Non-Goals
+
+The API does not expose:
+
+- Bot tokens or raw Telegram clients.
+- Arbitrary Bot API methods.
+- A second polling loop.
+- Cross-profile delivery.
+- Unrestricted cross-instance targeting.
+- Session replacement, reload, process launch, or Pi slash-command dispatch.
+- File/media uploads in the first 0.21 slice.
+- Captured Pi contexts or mutable queue/session state.
+
+Extension consumers remain trusted local code, but the contract still preserves product ownership boundaries so accidental misuse cannot silently bypass Threaded Mode routing or target identity.
+
+## Validation Contract
+
+The implementation must cover:
+
+- Classic `instance` and `aggregate` resolution.
+- Leader own-thread, aggregate, and live-bound explicit target resolution.
+- Follower assigned-thread and aggregate routing through the leader.
+- Missing active turns and disconnected runtimes.
+- Cross-profile, unknown, stale, and unauthorized explicit targets.
+- Plain, HTML, and Markdown chunking.
+- Reply-first and keyboard-last chunk placement.
+- Send/edit growth/edit shrink/delete ordering.
+- Reload/session-replacement generation invalidation.
+- In-flight shutdown fencing and redacted diagnostics.
+- Package-boundary imports with no `/lib` access.
+
+## Relationship To Activity
+
+The Activity API builds on this contract rather than duplicating transport. Activity handlers receive a fresh target-aware context whose `send`, `edit`, `delete`, and chat-action methods delegate to the same delivery runtime. The Activity API owns lifecycle normalization; this API owns delivery only.

package/docs/public-api.md

@@ -9,6 +9,8 @@
 - **Compatibility:** older import/config paths that remain supported but should not be used for new code.
 - **Internal:** exported from source for tests or domain reuse, but not a compatibility promise.
 
+The 0.21 Activity surface requires Pi `0.80.6` or newer. This minimum belongs to the package peer contract because `agent_settled` provides the only safe terminal boundary after retries, compaction, and queued continuations.
+
 ## Package Entrypoints
 
 Preferred public imports:
@@ -21,6 +23,8 @@ import { registerTelegramUpdateHandler } from "@llblab/pi-telegram/updates";
 import { registerTelegramCommand } from "@llblab/pi-telegram/commands";
 import { registerTelegramInboundHandler } from "@llblab/pi-telegram/inbound";
 import { registerTelegramOutboundHandler } from "@llblab/pi-telegram/outbound";
+import { sendTelegramView } from "@llblab/pi-telegram/delivery";
+import { registerTelegramActivityHandler } from "@llblab/pi-telegram/activity";
 import {
   registerTelegramVoiceSynthesisProvider,
   registerTelegramVoiceTranscriptionProvider,
@@ -118,6 +122,12 @@ High-level stable APIs:
 - `registerTelegramStatusLineProvider()`
   - Identity: required `id`.
   - Purpose: compact companion status rows in the `/start` menu status text.
+- `sendTelegramView()` / `editTelegramView()` / `deleteTelegramView()` / `sendTelegramChatAction()`
+  - Identity: current process-local delivery generation and returned logical message handles.
+  - Purpose: ownership-gated operational delivery to active-turn, current-instance, aggregate, or explicitly authorized targets.
+- `registerTelegramActivityHandler()`
+  - Identity: required stable `id`.
+  - Purpose: normalized non-blocking Pi lifecycle activity with source identity and fresh delivery contexts.
 - `registerTelegramVoiceTranscriptionProvider()`
   - Identity: required stable `id` for new code.
   - Purpose: STT fallback for voice/audio input.
@@ -145,6 +155,45 @@ Advanced stable diagnostics:
 
 All registration APIs return a disposer. Companion extensions should call disposers on shutdown and re-register on session start when they recreate runtime state. Low-level bus APIs intentionally avoid ids and run in registration order. High-level provider/UI APIs require stable identity in their public contract so diagnostics, replacement, and cleanup are understandable. Generated voice-provider ids remain a temporary compatibility path where documented.
 
+## Capability Inventory And Gap Classification
+
+This inventory maps the complete bridge capability plane to its supported extension boundary. A capability may stay private deliberately; completeness means every meaningful capability has an explicit classification, not that every internal helper becomes public.
+
+### Public now
+
+- **Extension loading:** The root export loads the bridge as a Pi extension; companion code uses the domain subpaths below rather than importing root runtime state.
+- **Telegram commands:** `/commands` registers explicit Telegram-native slash commands with scoped reply and prompt-enqueue ports.
+- **Managed menu and Settings UI:** `/sections` registers main-menu views, Settings rows, namespaced callbacks, standalone callback-scoped messages, and diagnostics.
+- **Programmatic target-aware delivery:** `/delivery` sends, edits, deletes, and signals operational views against active-turn, current-instance, aggregate, or explicitly authorized targets through generation-bound logical handles.
+- **Normalized lifecycle activity:** `/activity` registers non-blocking extension handlers for evidence-based run/source identity, assistant prose/reasoning segments, executed tools, compaction, and settlement with fresh delivery contexts.
+- **Compact status projection:** `/status` contributes synchronous status rows to the `/start` menu.
+- **Raw inbound update interception:** `/updates` observes or consumes Telegram updates before default routing and remains the low-level callback escape hatch.
+- **Inbound content transforms:** `/inbound` adds Telegram-to-Pi text/media preprocessing after operator-configured handlers.
+- **Final outbound transforms:** `/outbound` adds final text/voice transformation fallbacks and exposes redacted runtime-event recording.
+- **Voice providers and policy helpers:** `/voice` registers STT/TTS providers and exposes stable voice-mode projections.
+- **Keyboard structures:** `/keyboard` exposes inline-keyboard structural types without transport operations.
+- **Agent-callable delivery:** `telegram_message` and `telegram_attach` provide ownership-gated text/file delivery to the agent, not a JavaScript companion-extension transport API.
+
+### Intentionally private
+
+- **Credentials and raw transport:** Bot tokens, Telegram clients, unrestricted Bot API calls, polling, retry loops, offsets, and multipart/download internals stay private so companions cannot bypass pairing or open a second transport owner.
+- **Ownership and multi-instance routing:** Locks, named-profile isolation, leader/follower IPC, authorization capabilities, thread provisioning, reconciliation, and sync assumptions stay bridge-owned.
+- **Session and queue coordination:** Active turns, queue lanes, dispatch gates, abort/compaction state, previews, final-reply ordering, and session-bound context stores stay internal invariants rather than shared mutable extension state.
+- **Core operator UI:** Built-in menus, model/thinking controls, rendering internals, prompt-template expansion, status diagnostics assembly, and thread naming remain core policy; companions extend them through commands, sections, and status providers.
+- **Raw Pi runtime objects:** Companion APIs never return captured `ExtensionContext`, `ExtensionCommandContext`, session managers, or private session-replacement/runtime handles.
+
+### Assessed and not required for 0.21
+
+- **General managed callbacks outside Sections:** The documented issue #126 consumer shape needs interactive Settings toggles, not interactive activity rows. `/sections` already owns stable callback namespacing, callback answers, edits, navigation, and cleanup for those toggles; `/delivery` can render the resulting non-interactive activity views. A second callback registry would duplicate ownership without a proven use case, while `/updates` remains the deliberate low-level escape hatch for consumers that truly need raw callback interception. Revisit only when a public-import-only consumer must generate managed callbacks independently of a registered Section context for arbitrary delivered messages.
+
+### Explicitly deferred
+
+- **Programmatic artifact/media delivery:** `telegram_attach` covers agent-authored artifacts, while companion JavaScript has no general file/media send contract. The first 0.21 delivery slice targets operational text/activity views; media should earn a typed extension only from a concrete companion use case.
+- **General configuration mutation:** Companions own their configuration and Settings state. pi-telegram does not expose unrestricted mutation of `telegram.json`, profile identity, pairing, rendering, queue, or transport settings.
+- **Process and session control:** Reload, new-session, fork, resume, process launch, and arbitrary Pi slash-command dispatch remain outside the Telegram companion API until Pi exposes safe async extension hooks.
+
+The 0.21 platform boundary lets a public-import-only consumer own reasoning, intermediate-prose, and tool-row policy while pi-telegram retains target selection, transport, authorization, lifecycle safety, and delivery ordering. Activity-specific examples live in this documentation; the separate [`pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) project remains the maintained companion-extension reference.
+
 ## Commands
 
 Import from `@llblab/pi-telegram/commands`. This registers Telegram slash commands only; it does not expose Pi slash commands and is unrelated to command-template handlers.
@@ -209,6 +258,48 @@ Contract:
 
 Full behavior: [Extension Sections](./sections.md).
 
+## Telegram Delivery API
+
+Import from `@llblab/pi-telegram/delivery`.
+
+```ts
+const sent = await sendTelegramView(
+  {
+    text: "<b>Indexing…</b>",
+    parseMode: "html",
+  },
+  { scope: { kind: "instance" } },
+);
+if (!sent.ok) {
+  recordLocalDiagnostic(sent.reason, sent.message);
+}
+```
+
+The delivery runtime resolves its live binding on every call and returns structured failures for unavailable runtimes, missing or unauthorized targets, stale handles, invalid views, and transport failures. A logical handle may represent several chunked Telegram messages; edit and delete reconcile the whole logical view. If send or edit growth fails after materializing messages, the failure carries a valid partial handle for deterministic retry or cleanup. Followers route through the existing leader transport, and reload/session replacement invalidates old handles rather than retaining Pi contexts.
+
+Full behavior: [Telegram Delivery API](./delivery.md).
+
+## Telegram Activity API
+
+Import from `@llblab/pi-telegram/activity`.
+
+```ts
+const off = registerTelegramActivityHandler({
+  id: "@scope/activity-view",
+  async handle(event, ctx) {
+    if (event.type !== "tool-start") return;
+    await ctx.send({
+      text: `Tool: ${event.toolName}`,
+      parseMode: "plain",
+    });
+  },
+});
+```
+
+Handlers receive ordered normalized events but run outside Pi's critical lifecycle path. Each handler has an isolated asynchronous queue; adjacent high-frequency deltas may coalesce while semantic boundaries remain ordered. Activity contexts choose active-turn delivery for Telegram-owned work and instance delivery for local/autonomous/unknown work, delegating every operation through the current `/delivery` generation.
+
+Full behavior and consumer policy examples: [Telegram Activity API](./activity.md).
+
 ## Status Lines
 
 Import from `@llblab/pi-telegram/status`.
@@ -458,7 +549,7 @@ async function synthesizeDemoOgg(_text: string): Promise<string> {
 
 ### Smoke Checklist
 
-- The extension imports only public package membranes: `@llblab/pi-telegram`, `/commands`, `/sections`, `/status`, `/updates`, `/inbound`, `/outbound`, `/voice`, or `/keyboard`.
+- The extension imports only public package membranes: `@llblab/pi-telegram`, `/commands`, `/sections`, `/status`, `/delivery`, `/activity`, `/updates`, `/inbound`, `/outbound`, `/voice`, or `/keyboard`.
 - It does not import `@llblab/pi-telegram/lib/*`.
 - It registers on `session_start` and disposes on `session_shutdown`.
 - Stable high-level registrations use durable ids.

package/docs/sections.md

@@ -441,10 +441,11 @@ Available programmatically via `getTelegramSectionDiagnostics()`. Main-menu/sett
 
 ## 15. Demo Extension
 
-`@llblab/pi-telegram-extension-demo` (`extensions/pi-telegram-extension-demo/`) is the reference implementation:
+[`@llblab/pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) is the maintained companion-extension reference:
 
-- Main menu: `🧪 Demo submenu` — enqueue prompt, answer callback, show info, interactive counter
-- Settings: `🧪 Demo settings` — ON/OFF toggle with dynamic `getLabel()` status indicator, enqueue from settings
-- Navigation: full Back/Main menu hierarchy across all three levels
+- Main-menu and Settings surfaces with dynamic labels.
+- Managed section callbacks, buttons, edits, navigation, and cleanup.
+- Public `@llblab/pi-telegram/*` imports rather than package-private `/lib` paths.
+- Independent package and lifecycle ownership outside pi-telegram core.
 
-Use it as a template for new section-based extensions.
+Use it as a template for section-based extensions. Activity-specific registration and delivery patterns remain in [Telegram Activity API](./activity.md); pi-telegram does not duplicate the demo as an in-package `examples/` directory.

package/index.ts

@@ -4,6 +4,7 @@
  * Keeps the runtime wiring in one place while delegating reusable domain logic to /lib modules
  */
 
+import * as Activity from "./lib/activity.ts";
 import * as Bindings from "./lib/bindings.ts";
 import * as BusApi from "./lib/bus-api.ts";
 import * as Bus from "./lib/bus.ts";
@@ -13,6 +14,7 @@ import * as BusTransport from "./lib/bus-transport.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Commands from "./lib/commands.ts";
 import * as Config from "./lib/config.ts";
+import * as Delivery from "./lib/delivery.ts";
 import * as Threads from "./lib/threads.ts";
 import * as Inbound from "./lib/inbound.ts";
 import * as Lifecycle from "./lib/lifecycle.ts";
@@ -531,6 +533,54 @@ export default function (pi: Pi.ExtensionAPI) {
   });
   const { replyTransport, editInteractiveMessage, sendInteractiveMessage } =
     replyRuntime;
+  const getDeliveryTargetPolicyView = function (): Delivery.TelegramDeliveryTargetPolicyView {
+    const ownsDirect = lockRuntime.owns();
+    const followerTarget = telegramBusFollowerRegistrationState.getTarget();
+    return {
+      canDeliver:
+        ownsDirect || telegramBusFollowerRegistrationState.isRegistered(),
+      ownsDirect,
+      allowedChatId: configStore.getAllowedUserId(),
+      followerTarget,
+      leaderTarget: telegramBusLeaderTarget,
+      liveTargets: threadStore.list().map(function (record) {
+        return record.target;
+      }),
+    };
+  };
+  const deliveryGenerationSeed = `${telegramInstanceId}:${Date.now()}`;
+  const deliveryLifecycleRuntime =
+    Delivery.createTelegramBridgeDeliveryLifecycleHooks({
+      generationSeed: deliveryGenerationSeed,
+      getTargetPolicyView: getDeliveryTargetPolicyView,
+      getActiveTurnTarget() {
+        if (activeTurnRuntime.getGuestQueryId()) return undefined;
+        return activeTurnRuntime.getTarget();
+      },
+      api: telegramApiRuntime,
+      recordOwnership(input) {
+        messageOwnershipStore.record({
+          ...input,
+          instanceId: telegramInstanceId,
+        });
+      },
+      recordFailure(operation, error, target) {
+        recordRuntimeEvent("delivery", error, {
+          operation,
+          scope: target?.threadId === undefined ? "aggregate" : "thread",
+        });
+      },
+    });
+  const activityRuntime = Activity.createTelegramActivityBridgeRuntime({
+    generation: deliveryGenerationSeed,
+    recordFailure(handlerId, event, error) {
+      recordRuntimeEvent("activity", error, {
+        handlerId,
+        eventType: event.type,
+        activityId: event.activityId,
+      });
+    },
+  });
   const { sendTextReply, sendMarkdownReply } =
     Outbound.createTelegramOutboundTextReplyRuntime({
       sendTextReply: replyRuntime.sendTextReply,
@@ -1238,11 +1288,13 @@ export default function (pi: Pi.ExtensionAPI) {
     queueSessionLifecycle,
     {
       async onSessionStart(event, ctx) {
+        await deliveryLifecycleRuntime.onSessionStart();
         await lockedPollingRuntime.onSessionStart(event, ctx);
         telegramThreadCapabilityMonitor.start(ctx);
         queueDispatchWatchdogRuntime.start(ctx);
       },
       async onSessionShutdown() {
+        await deliveryLifecycleRuntime.onSessionShutdown();
         queueDispatchWatchdogRuntime.stop();
         telegramThreadCapabilityMonitor.stop();
       },
@@ -1301,6 +1353,7 @@ export default function (pi: Pi.ExtensionAPI) {
       ...sessionLifecycleRuntime,
       onModelSelect: currentModelRuntime.onModelSelect,
     },
+    activityRuntime,
     configStore,
     abort,
     typing,