@llblab/pi-telegram 0.20.6 → 0.21.1

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.

package/docs/architecture.md

@@ -2,18 +2,20 @@
 
 ## Purpose
 
-`pi-telegram` is a session-local Pi extension that binds one Telegram DM to one running Pi session. It owns the Telegram bridge boundary:
+`pi-telegram` is a session-aware Pi runtime extension that binds Telegram destinations to running Pi instances and routes each accepted prompt into the assigned instance's currently active session. It owns the Telegram bridge boundary:
 
 - Poll Telegram updates and enforce single-user pairing.
 - Translate Telegram text, callbacks, media, and files into Pi turns.
 - Stream previews and deliver final Pi responses back to Telegram.
 - Provide Telegram-native controls for queueing, model/thinking/settings menus, compaction, abort/stop, prompt templates, reactions, and outbound artifacts.
 
-The bridge is a mobile companion for a live Pi session, not a remote terminal. It should let an operator start work in the TUI and continue supervising from Telegram, while staying inside Pi's extension-facing contracts.
+The bridge is a mobile companion for a live Pi runtime, not a remote terminal or session browser. It should let an operator start work in the TUI and continue supervising the instance's active session from Telegram, while staying inside Pi's extension-facing contracts.
 
 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.
@@ -28,7 +30,7 @@ This document is the architectural map. Focused behavior standards live in sibli
 
 ### Extension Boundary Vs Supervisor Control
 
-`pi-telegram` runs inside the current Pi process as an extension. That gives it safe access to public extension APIs such as aborting work, compacting, sending follow-up prompts, observing lifecycle events, and rendering Telegram-native controls. It does not own the terminal, the interactive-mode chat transcript, or the process lifecycle.
+`pi-telegram` runs inside the current Pi process as an extension. That gives it safe access to public extension APIs such as aborting work, compacting, dispatching queued prompts, observing lifecycle events, and rendering Telegram-native controls. It does not own the terminal, the interactive-mode chat transcript, or the process lifecycle.
 
 Keep this boundary explicit:
 
@@ -37,6 +39,16 @@ Keep this boundary explicit:
 - Commands that require interactive session replacement or TUI rerendering, such as a true Telegram `/new`, need a public Pi API that invokes the same runtime path as the terminal command.
 - A separate PTY supervisor or daemon could choose to own those risks, but that would be a different product mode rather than this extension's runtime contract.
 
+### Instance, Session, And Context Cost
+
+A Telegram destination follows a Pi instance, not an immutable Pi session file. Ordinary Telegram prompts enter whichever session is active in that assigned instance when dispatch occurs. If the operator replaces or resumes a session locally, pi-telegram rebinds its session-scoped runtime state while preserving the instance's Telegram target where supported. Telegram currently exposes compaction for the active session, but not new-session, resume, fork, tree navigation, session switching, or full reload; those operations require safe public Pi extension APIs.
+
+`/telegram-connect` never launches a hidden or headless Pi process. A long-lived background Pi process can own Telegram only when something else explicitly launched that process and it satisfies the normal lock/runtime rules. Pi `print` and `json` modes stay passive and exit rather than becoming hidden polling owners.
+
+Pi session JSONL and pi-telegram runtime JSONL serve different purposes. Pi session files contain model conversation, tool, usage, branch, and compaction entries. Profile-scoped `logs.jsonl` / `logs.<profile>.jsonl` contain redacted bridge operations from one or more instances and never become model context. Sharing a Telegram profile or working directory does not by itself merge Pi session identities or model histories.
+
+A Telegram prompt is a normal Pi model turn. It inherits the active post-compaction context just like a TUI prompt in the same session; pi-telegram does not promise context isolation or token cost proportional only to the new message. Current prompt guidance uses a small transient system note and the on-demand `telegram_help` tool instead of persisting the former large guidance suffix in every user turn. Existing session files created by older versions may still contain those historical repeated suffixes until session replacement or compaction removes them from active context.
+
 The repository uses a **Flat Domain DAG**:
 
 - Local imports must form a directed acyclic graph.
@@ -64,6 +76,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.
@@ -189,7 +203,7 @@ Dispatch requires:
 
 A dispatched prompt remains queued until `agent_start` consumes it. This keeps the active Telegram turn bound for previews, attachments, aborts, and final replies.
 
-Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere. When a queued Telegram prompt is forwarded into Pi, it uses Pi's explicit `followUp` delivery option so Telegram input preserves the existing non-steering queue contract even if Pi is still settling active work.
+Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere. When a queued Telegram prompt is forwarded into Pi, it uses a normal `sendUserMessage(content)` turn after the bridge's idle/dispatch guards pass; it does not use Pi's `followUp` delivery option or inject terminal input.
 
 ### Controls And Menus
 
@@ -233,7 +247,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 +279,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.