@llblab/pi-telegram 0.45.11 → 0.47.0

package/BACKLOG.md

@@ -2,6 +2,11 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
+- [ ] `Session-aware Thread binding` (`next minor`, primary outcome): Replace profile-scoped exact-`cwd` reuse as the sole Workspace identity with a durable composite of normalized exact `cwd` and Pi's stable public session identity. `/telegram-connect` must persist that session-to-Thread binding so reopening, resuming, or continuing the same Pi session automatically restores the same Telegram Thread and letter slot when the retained binding has not been validly displaced. Different sessions in one directory must receive distinct live slots, while the same session must not allocate a duplicate after process restart. Session number/name are bounded lookup or presentation aliases only, never routing authority. Preserve authenticated live-owner, accepted-work, displacement, retirement, and slot-pressure fences. This is the principal deliverable of the next minor release.
+  - [x] `Identity and migration contract`: [`docs/multi-instance-bus.md`](./docs/multi-instance-bus.md#approved-next-contract-session-aware-workspace-identity) now fixes the public session source, composite authority, binding-key derivation, lifecycle semantics, exact legacy `{ cwd, ∅ }` coexistence, fail-closed malformed present identity behavior, mixed-version fence, and non-ownership boundaries.
+  - [x] `Store and allocation foundation`: Session-qualified identity, persistence, independent same-cwd claims/slots, strict digest validation, cleanup and retirement snapshots, and exact legacy cwd-only coexistence are locally implemented. The former staged-adoption claim state and commit exceptions have been removed, so no latent mutation path can consume a cwd-only binding. Absence of session identity remains its own key across reload and stale status persistence; same-session restore retains its letter while another session cannot reuse it.
+  - [x] `Leader/follower lifecycle wiring`: Leader assembly now reads public `ctx.sessionManager.getSessionId()`, passes it through sync provisioning, and restores the matching session-qualified Workspace without creating a duplicate Thread; cwd-only legacy state remains an independent `{ cwd, ∅ }` identity and is never exposed through a session lookup. Authenticated follower registration now carries a strict bounded session ID over the bus, preserves it in the live registry, and passes it into leader-owned provisioning; fresh same-cwd follower sessions therefore commit distinct session-qualified bindings. Production follower assembly sources the value from the current Pi context, independently of process instance and session generation. Follower-to-leader promotion now resolves the exact current session binding and preserves its target, slot, generated name, and acknowledged display title through leader handoff. Startup restore and `/telegram-connect` share the session-bearing registration envelope and leader provisioner. Protocol v2 makes session identity mandatory for every cwd-scoped participant and rejects protocol-v1 0.45.x peers before provisioning; the supported upgrade path stops all instances, updates them together, then starts a fresh session-native leader. Session-aware stale-target replacement is now regression-covered: replacing session A updates only A's binding and leaves same-cwd session B untouched. Capability rejection is covered independently from the older durable-admission gate. Startup restore eligibility now checks the current session exactly and never treats a legacy cwd-only binding as that session, so neither a sibling nor `{ cwd, ∅ }` can make a fresh session auto-connect. Explicit `/telegram-connect`, restore-only registration, and reconnect handoff all use the same session-bearing registration runtime; focused tests cover restore-only and handoff transmission. The production integration harness now supplies a distinct stable `sessionManager.getSessionId()` per mocked context, and the lifecycle/cleanup integration regression passes with session-aware leader provisioning. Legacy `{ cwd, ∅ }` records remain readable but inert and independent: they are never adopted, migrated, or used for a v2 session. Full-suite closure is green: the bundled Show Me wording is compressed within its disclosure budget, integration contexts preserve one session manager across idle/active phases, and the complete test command passes.
+  - [ ] `Compatibility and acceptance` (`local-actionable` plus live gate, current): Exact lookup now treats both presence and absence of session ID symmetrically: `{ cwd, ∅ }` cannot match a session binding, and `{ cwd, session }` cannot match legacy. Focused store, follower, leader, and polling suites pass across coexistence, restore-only, same-session process replacement, follower reload/handoff, distinct same-cwd session allocation (the `/fork`/`/new` identity effect), promotion, session-isolated rename, stale-target replacement, malformed identity, and rolling-upgrade capability behavior. Full slot-pressure retirement now selects the oldest eligible exact binding across legacy and session-qualified identities and persists the victim's session component; protection and exact-intent fences remain unchanged. The Pi adapter now has explicit evidence that restart/reload/resume/continue-recent aliases do not influence authority: only the public stable session ID is read, while a forked ID remains distinct. Local acceptance is complete: generation-fenced stale ownership cannot mutate a replacement; target displacement is exact-session isolated; strict legacy and session-qualified snapshots coexist without aliasing or stale resurrection; protocol-v1 peers are explicitly rejected, while all protocol-v2 cwd participants use session-qualified identity. Update the current-contract docs only with locally validated behavior. Remaining gate: a separately operator-authorized live smoke for same-session restoration and two concurrent sessions in one directory.
 - [ ] `Prompt enqueue hotfix` (`optional`, `operator-gated`): Optional nonblocking operator-authorized disposable-follower smoke: overlap delayed voice processing with turn completion and confirm one-time ordered consumption and truthful counts against the [queue contract](./docs/architecture.md#queue-and-dispatch-safety). Separately authorized supported recovery investigation remains open: prevention does not repair an already-wedged in-memory queue; establish the exact recovery path and preservation/discard consequences before mutation, otherwise report the blocker. No journal/ownership edits, replay of settled input, implicit queue clearing, or restart; live activation requires separate operator authorization.
 - [ ] `Channel multimedia posts` (`0.45.1`, live-acceptance-gated): `telegram_message` channel delivery accepts one local `.jpg`/`.jpeg`/`.png`/`.webp` photo or `.mp4` video, uploads it through the multipart transport as `sendPhoto`/`sendVideo` with `text` as the HTML caption, validates kind and size (photo ≤ 10 MiB, video ≤ 50 MiB) plus ≤ 1024 visible caption characters before issuance, and rejects unsupported types and albums instead of downgrading them to links. The channel-post journal binds kind/file name/byte size/SHA-256 and caption, so duplicate requests and lost acknowledgements never re-upload; media-post edits replace the caption through `editMessageCaption`, and Markdown spoilers render as `<tg-spoiler>`. Live image publication passed on `@llb_log`. Regressions cover confirmed publication, duplicate requests, lost ACK, pre-issuance rejection, caption edits, and reconnect replacement. Remaining: operator-authorized disposable-channel acceptance of rejected upload, duplicate request, and caption edit.
 - [ ] `Manual Thread naming` (`gated-but-preparable`, release priority): Local bot-owned `/name Name` and bare `/name` flows avoid model dispatch. One expiring exact-target input dialog immediately accepts the next valid name, always offers cancel, and offers **Reset to automatic** only while a manual override exists; duplicate/stale callbacks cannot repeat mutation. Durable manual override supersedes every automatic display mode, reset is leader/follower generation- and target-fenced, and Letters remains the default without rewriting recovery identity. Local review findings are remediated, including Bot-API-wait target-replacement regressions for leader/follower rename and reset. Remaining: disposable live acceptance for command-menu ordering, dialog, invalid input, duplicate callbacks, leader/follower rename and reset.
@@ -32,5 +37,4 @@ _This file owns unresolved project work only. Completed behavior belongs in `CHA
   - [ ] Harden the implemented pre-queue `app::method` / strict-JSON bound-action route with revision capture for agent-mediated initial surfaces, profile/target authority, follower transport evidence, voice output delivery, and commit-unknown diagnostics while preserving generation-plus-revision stale-click rejection, fail-closed malformed/absent methods, ordinary model prompts, and native single-colon callbacks.
   - [ ] Harden the implemented cross-process transition lock, dead-owner recovery, expected-generation/revision comparison, repaired partial-tail/current-state recovery, transactional `init` reset, and output-only methods with process-birth proof, bounded lock diagnostics, more interruption points, and explicit commit-unknown evidence.
   - [ ] Complete the capability-owned Music Player adapter evidence beyond the successful real `ffplay` singleton install and no-model-turn bound `next`, `pause`, resume/`play`, and terminal `stop` Controls: exercise generated relative-volume controls over arbitrary absolute Actor percentages, `toggle`, `previous`, `status`, compatible singleton reuse, checkpoint restart, missing/terminal Run, unavailable backend, process timeout/cancellation/stream bounds, and redacted errors while keeping actor reality authoritative and rejecting generic remote-terminal methods.
-  - [ ] Extend the implemented new-message default plus opt-in `viewMode: "edit"` bound-action update into optional output-only `refresh` scheduling from `refreshAfterMs`, clamped to at least two seconds and serialized after prior completion; retain one latest logical view handle per app/profile/target, skip unchanged frame digests, honor Telegram retry/backoff, cancel on lifecycle replacement, stop and forget the handle on known deletion or message-not-found, and never recreate a deleted live view without a fresh user action.
   - [ ] Cover CML and JSON equivalence, both mutually exclusive Tool shapes, direct agent-authored app discovery, install/copy and existing-app `init`, scalar/object/no-argument methods, agent-side diagnostic invocation, bounded CLI adaptation, refresh coalescing/rate limits/backoff/deletion, identity/path traversal, duplicate/overlapping prefixes, state recovery, handler failure, stale clicks, session replacement, follower routing, and the invariant that bound actions perform no model turn. `tests/generative-apps.test.ts` now covers scalar/object/no-argument argument shapes, throwing-method failure containment (state and journal untouched), and bounded argument/output/state/module limits before durable mutation; the remaining items stay open.

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## Unreleased
 
+## 0.47.0: Built runtime and live surfaces
+
+- `Startup`: npm installs now load a compiled JavaScript extension from a nested `dist/pi-telegram` entrypoint while source checkouts retain `index.ts`. Stable public subpath exports ship compiled JavaScript plus declarations, packaged Skills follow the distributive root, and validation checks the built extension import.
+- `Button authoring`: Native `telegram_button` fences now accept adjacent top-level JSON/CML objects without an outer array or commas as vertical singleton rows. Explicit outer matrices remain equivalent, nested arrays still own horizontal layout, and malformed sequences activate no controls.
+- `Activity`: Native typing remains continuously re-armed during agent/message work, pauses only for local UI prompts, resumes for unsettled agent or compaction work, and retargets queued turns without leaking keepalive ticks across Threads; transport and session fences still suppress stale actions.
+- `Live views`: Validated `refreshAfterMs` drives non-overlapping timers after hinted `telegram_bind` delivery. Refreshes and current-surface actions edit one generation-fenced Delivery handle through the Markdown/button planner across classic, leader, and follower targets; hints reschedule and omission closes. Retryable failures retain one frame; unavailable messages invalidate with a bounded diagnostic. Take, shutdown, and replacement fence late refreshes and cancel memory-only surfaces.
+- `Thread display`: Adds explicit `directory-snake` and `directory-title` profile modes with shared Unicode-aware path tokenization, uppercase-abbreviation preservation, live Settings previews, initial/reconciled title projection, and negotiated peer capability fencing. Their slot suffixes now follow authenticated concurrent live same-directory ownership and disappear after disconnect or confirmed-dead pruning; dormant bindings and sticky legacy metadata are ignored. Retained `directories` stays unchanged.
+
+## 0.46.0: Session-aware Workspace Threads
+
+- `Session-aware Thread binding`: Workspace identity restored session-qualified bindings from Pi's stable public session identity, so reopening, resuming, or replacing a process reclaims the same Telegram Thread and letter while distinct sessions in one directory keep independent targets. Strict legacy cwd-only records remain inert and coexist safely; protocol v2 rejects mixed 0.45.x peers before provisioning, and exact-session cleanup, displacement, rename, promotion, and slot-pressure fences are preserved.
+
 ## 0.45.11: Consumer-owned companion semantics
 
 - `Extension boundaries`: Removes consumer-specific state-scope emoji from the Telegram UI registry. The bridge continues to own generic Rich Message headings and inspection semantics, while companion extensions independently own their domain labels, composition rules, and presentation through the public section API.

package/README.md

@@ -6,7 +6,7 @@
 
 `pi-telegram` turns a private Telegram DM into a mobile operator surface for Pi. It accepts prompts, queues work, streams readable previews, delivers final replies and files, exposes safe controls, and lets companion extensions add Telegram-native capabilities without owning a second bot loop.
 
-It is a **runtime adapter**, not a remote terminal. Start or supervise work in the Pi TUI, then continue from Telegram while away from the keyboard. Each Telegram destination follows a running Pi instance and sends prompts into that instance's currently active session; it is not permanently bound to one session file or session identity. The bridge preserves Pi session semantics instead of pretending Telegram is a PTY, shell, process launcher, or session browser. That boundary is the product: Telegram gets safe runtime handles, not raw terminal power.
+It is a **runtime adapter**, not a remote terminal. Start or supervise work in the Pi TUI, then continue from Telegram while away from the keyboard. In Threaded Mode, a durable Workspace binding uses Pi's stable public session identity to restore the same Telegram Thread when that session resumes; live instance ownership and the exact Telegram target still authorize routing. The bridge preserves Pi session semantics instead of pretending Telegram is a PTY, shell, process launcher, or session browser. That boundary is the product: Telegram gets safe runtime handles, not raw terminal power.
 
 Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. While Telegram is connected, local, autonomous, and unclassified extension follow-up work also projects visible checkpoints and the final answer to the authorized Telegram target once and in order, preserving assistant-authored `telegram_button` comments as interactive prompt buttons. This connected companion projection is always active rather than configurable. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate `Activity` setting defaults to `verbose` so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose `quiet`. See [Outbound](docs/outbound.md#public-assistant-output) and the [configuration reference](docs/public-api.md#configuration-api).
 
@@ -55,7 +55,7 @@ Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved tok
 /telegram-connect
 ```
 
-The connected Pi instance owns Telegram polling. Use `/telegram-connect <profile>` to activate a named profile, and optionally append `as=Name` to name a fresh Workspace Thread. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. A reopened follower Workspace with a remembered Thread reconnects automatically at session startup; a new Workspace still requires explicit `/telegram-connect`.
+The connected Pi instance owns Telegram polling. Use `/telegram-connect <profile>` to activate a named profile, and optionally append `as=Name` to name a fresh Workspace Thread. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. Reopening or resuming the same Pi session restores its remembered Thread at session startup; a distinct session in the same directory has its own binding and still requires explicit `/telegram-connect` when no remembered binding exists.
 
 After an unclean computer shutdown, `/telegram-connect` detects truncated or structurally invalid temporary ownership/routing files, quarantines only the damaged files under `tmp/telegram/recovery/`, and retries once. A journal snapshot removed by older broad temp cleanup is rebuilt when its complete segment history proves an empty result, while a revisionless snapshot is repaired from the first surviving segment's exact predecessor when the reconstructed tail validates. Otherwise the snapshot and segments are quarantined as recovery evidence, a fresh journal is published, and startup continues with an informational diagnostic instead of requiring manual JSON repair. Unsupported journal versions block recovery without rewriting or quarantining the retained files; use a compatible runtime rather than deleting journals. Saved `telegram.json` configuration and runtime diagnostics remain intact. Recovery never replaces a verifiable live owner; if safe automatic recovery cannot complete, the command gives one explicit Pi-restart instruction instead of requiring deletion of the whole `tmp/` directory.
 
@@ -226,7 +226,7 @@ Voice notes, audio, images, PDFs, and other media can pass through configured in
 
 ### Buttons And Callbacks
 
-Assistant replies can place controls between paragraphs using standalone triple-backtick `telegram_button` blocks, or keep them in the footer using top-level hidden `telegram_button` comments. Both wrappers accept singleton cells and mixed JSON/CML matrices. Native in-body rows allow up to eight buttons; HTML compatibility moves these rows to the footer. In-body clicks acknowledge without recoloring the Rich body, while footer selection styles remain unchanged. Hidden comments accept a JSON object, adaptive JSON/CML matrix, or positional Compact Matrix Literal (CML). One adaptive matrix may mix named JSON objects with positional CML cells; separators are optional and one trailing comma is tolerated, including inside JSON objects. Top-level cells become full-width rows while nested rows group one or more buttons horizontally without an artificial parser-level width cap; generated surfaces default to five columns and use six to eight only for short position-bearing labels. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style` set to `primary`, `success`, or `danger`; omitting the first atom leaves the existing prompt-as-label fallback in charge, while the optional style still requires a non-empty prompt. A fourth atom adds disabled state: `{|Next||1}` or `{|Next||true}` disables, `0` or `false` enables (exact lowercase), and omission stays enabled; the third atom may be empty in this form. JSON uses boolean `disabled`. Disabled controls require no prompt or selected style: `{Next|||1}` shows only a label, while `{|||1}` is a blank disabled cell. Disabled controls remain visible without registering callbacks or invoking prompts/app methods. It trims atom boundaries, preserves non-structural text literally, and decodes only `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Buttons use `label` plus `prompt`, or the compact `value` key when both are identical. The bridge strips every assistant-authored HTML comment from Telegram previews and final replies regardless of Markdown position or owning extension, while only recognized top-level comments activate buttons or voice; comment-only output sends no text message and the Pi terminal transcript remains unchanged. It renders valid inline buttons and routes callbacks back into Pi as queued prompts or extension-owned callback actions. Button-only replies receive the standard `☑️ **Choose an option:**` heading as automatic visible fallback text. Once a generated prompt button is accepted, only that exact button switches to its optional `selected_style` (`primary` blue by default, `success` green, or `danger` red) without altering its agent-authored label or emoji; every style still queues the selected prompt.
+Assistant replies can place controls between paragraphs using standalone triple-backtick `telegram_button` blocks, or keep them in the footer using top-level hidden `telegram_button` comments. Both wrappers accept singleton cells and mixed JSON/CML matrices. Native in-body rows allow up to eight buttons; HTML compatibility moves these rows to the footer. In-body clicks acknowledge without recoloring the Rich body, while footer selection styles remain unchanged. Hidden comments accept a JSON object, adaptive JSON/CML matrix, or positional Compact Matrix Literal (CML). One adaptive matrix may mix named JSON objects with positional CML cells; separators are optional and one trailing comma is tolerated, including inside JSON objects. Top-level cells become full-width rows while nested rows group one or more buttons horizontally without an artificial parser-level width cap; inside a fenced block, adjacent top-level JSON/CML objects may omit the outer array and commas. Generated surfaces default to five columns and use six to eight only for short position-bearing labels. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style` set to `primary`, `success`, or `danger`; omitting the first atom leaves the existing prompt-as-label fallback in charge, while the optional style still requires a non-empty prompt. A fourth atom adds disabled state: `{|Next||1}` or `{|Next||true}` disables, `0` or `false` enables (exact lowercase), and omission stays enabled; the third atom may be empty in this form. JSON uses boolean `disabled`. Disabled controls require no prompt or selected style: `{Next|||1}` shows only a label, while `{|||1}` is a blank disabled cell. Disabled controls remain visible without registering callbacks or invoking prompts/app methods. It trims atom boundaries, preserves non-structural text literally, and decodes only `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Buttons use `label` plus `prompt`, or the compact `value` key when both are identical. The bridge strips every assistant-authored HTML comment from Telegram previews and final replies regardless of Markdown position or owning extension, while only recognized top-level comments activate buttons or voice; comment-only output sends no text message and the Pi terminal transcript remains unchanged. It renders valid inline buttons and routes callbacks back into Pi as queued prompts or extension-owned callback actions. Button-only replies receive the standard `☑️ **Choose an option:**` heading as automatic visible fallback text. Once a generated prompt button is accepted, only that exact button switches to its optional `selected_style` (`primary` blue by default, `success` green, or `danger` red) without altering its agent-authored label or emoji; every style still queues the selected prompt.
 
 ### Threaded Mode And Multi-Instance Bus
 
@@ -236,16 +236,16 @@ Classic private DM mode is the base product mode. When Telegram private-chat Thr
 - Followers are visible Pi processes started by the operator.
 - Each connected instance gets a Telegram thread target.
 - Queued work for a live follower transfers through authenticated exact-journal handoff rather than replaying under the transport owner.
-- Follower session replacement preserves registration, and a reopened follower Workspace with a remembered Thread reconnects automatically without allocating a Thread for an unremembered Workspace.
+- Reopening, resuming, or replacing the process for the same Pi session restores its remembered Thread; distinct sessions in one directory keep independent bindings and letter slots.
 - Unknown threads are preserved and offered explicit reroute/restore choices.
 - Telegram never launches hidden Pi processes.
 
-In Threaded Mode, open Settings → **🧵 Thread display** to choose **Letters** (default), **Names**, or **Directories** for this bot profile. Fresh tabs are created with the active mode's title instead of being visibly renamed afterward. Telegram tab titles, Pi terminal status, live Thread choosers/notices, prompt attribution, and named `telegram_message` targeting use the same acknowledged display name; target IDs and live registrations still own routing. Names shows the generated dictionary name chosen for the slot, such as `Anchor` for slot `A`. Directory mode adds persistent global-letter suffixes when a Workspace has multiple instances, such as `extensions_a` and `extensions_c`. `/name` sets a manual Thread display name; **Reset to automatic** restores the selected automatic projection. Switching preserves Thread IDs, slots, generated recovery identity, and queue ownership. Partial application reports an error and can be retried without recreating Threads.
+In Threaded Mode, open Settings → **🧵 Thread display** to choose **Letters** (default), **Names**, **directory-snake**, or **directory-title** for this bot profile; a retained **directories** value remains available as an unchanged legacy presentation. The Settings detail shows a bounded live preview computed from current Workspace bindings. Fresh tabs are created with the active mode's title instead of being visibly renamed afterward. Telegram tab titles, Pi terminal status, live Thread choosers/notices, prompt attribution, and named `telegram_message` targeting use the same acknowledged display name; target IDs and live registrations still own routing. Names shows the generated dictionary name chosen for the slot, such as `Anchor` for slot `A`; the directory formats produce `api_tools` or `Api Tools` and append `_a` or ` · A` only while two or more authenticated live instances share that exact directory. Dormant retained bindings do not keep those suffixes visible. `/name` sets a manual Thread display name; **Reset to automatic** restores the selected automatic projection. Switching preserves Thread IDs, slots, generated recovery identity, and queue ownership. Partial application reports an error and can be retried without recreating Threads.
 
 | Mode | Best for | Runtime shape |
 | --- | --- | --- |
 | Classic DM | One running Pi instance and its active session controlled from one private bot chat | One polling owner, one queue/runtime surface |
-| Threaded Mode | Several visible Pi instances sharing one bot | One leader owns transport; each named private-chat thread follows its assigned instance and current session |
+| Threaded Mode | Several visible Pi sessions sharing one bot | One leader owns transport; each private-chat Thread retains one session-qualified Workspace binding |
 
 ## Environment Configuration
 

package/dist/api/activity.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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/dist/api/activity.js

@@ -0,0 +1,6 @@
+/**
+ * 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, } from "../lib/activity.js";

package/dist/api/commands.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram commands API
+ * Zones: package boundary, extension interop
+ * Exposes the stable Telegram slash-command registration surface while keeping registry internals package-private
+ */
+export { registerTelegramCommand, type TelegramExtensionCommandContext, type TelegramExtensionCommandRegistration, } from "../lib/commands.ts";

package/dist/api/commands.js

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram commands API
+ * Zones: package boundary, extension interop
+ * Exposes the stable Telegram slash-command registration surface while keeping registry internals package-private
+ */
+export { registerTelegramCommand, } from "../lib/commands.js";

package/dist/api/delivery.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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/dist/api/delivery.js

@@ -0,0 +1,6 @@
+/**
+ * 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, } from "../lib/delivery.js";

package/dist/api/inbound.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram inbound API
+ * Zones: package boundary, extension interop
+ * Exposes the stable programmatic inbound handler surface while keeping handler runtime internals package-private
+ */
+export { registerTelegramInboundHandler, type TelegramInboundHandlerFile, type TelegramInboundHandlerOutput, type TelegramInboundProgrammaticHandler, type TelegramInboundProgrammaticHandlerInput, type TelegramInboundProgrammaticHandlerResult, } from "../lib/inbound.ts";

package/dist/api/inbound.js

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram inbound API
+ * Zones: package boundary, extension interop
+ * Exposes the stable programmatic inbound handler surface while keeping handler runtime internals package-private
+ */
+export { registerTelegramInboundHandler, } from "../lib/inbound.js";

package/dist/api/keyboard.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram keyboard API
+ * Zones: package boundary, extension interop
+ * Exposes shared inline-keyboard structural types without runtime exports
+ */
+export type { TelegramInlineKeyboardButton, TelegramInlineKeyboardButtonStyle, TelegramInlineKeyboardMarkup, } from "../lib/keyboard.ts";

package/dist/api/keyboard.js

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

package/dist/api/outbound.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram outbound API
+ * Zones: package boundary, extension interop
+ * Exposes stable outbound handler and diagnostics surfaces while keeping delivery internals package-private
+ */
+export { recordTelegramRuntimeEvent, registerTelegramOutboundHandler, type TelegramOutboundProgrammaticHandler, } from "../lib/outbound.ts";

package/dist/api/outbound.js

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram outbound API
+ * Zones: package boundary, extension interop
+ * Exposes stable outbound handler and diagnostics surfaces while keeping delivery internals package-private
+ */
+export { recordTelegramRuntimeEvent, registerTelegramOutboundHandler, } from "../lib/outbound.js";

package/dist/api/sections.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public Telegram sections API
+ * Zones: package boundary, extension interop
+ * Exposes the stable managed Telegram menu-section surface while keeping registry internals package-private
+ */
+export type { TelegramInputRichBlock, TelegramInputRichMessage, TelegramRichText } from "../lib/telegram-api.ts";
+export { getTelegramSectionDiagnostics, registerTelegramSection, type TelegramSectionCallbackContext, type TelegramSectionCallbackResult, type TelegramSectionContext, type TelegramSectionDiagnostic, type TelegramSectionRegistration, type TelegramSectionSettingsRegistration, type TelegramSectionView, } from "../lib/sections.ts";

package/dist/api/sections.js

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram sections API
+ * Zones: package boundary, extension interop
+ * Exposes the stable managed Telegram menu-section surface while keeping registry internals package-private
+ */
+export { getTelegramSectionDiagnostics, registerTelegramSection, } from "../lib/sections.js";

package/dist/api/status.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram status API
+ * Zones: package boundary, extension interop
+ * Exposes compact status-menu line registration for extension consumers while keeping status rendering internals package-private
+ */
+export { registerTelegramStatusLineProvider, type TelegramStatusLineProvider, type TelegramStatusLineProviderContext, type TelegramStatusLineProviderResult, } from "../lib/status.ts";

package/dist/api/status.js

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram status API
+ * Zones: package boundary, extension interop
+ * Exposes compact status-menu line registration for extension consumers while keeping status rendering internals package-private
+ */
+export { registerTelegramStatusLineProvider, } from "../lib/status.js";

package/dist/api/updates.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram updates API
+ * Zones: package boundary, extension interop
+ * Exposes the stable raw-update handler surface while keeping update routing internals package-private
+ */
+export { assertTelegramUpdateExecutionCurrent, carryTelegramUpdateExecutionFence, createTelegramUpdateExecutionFenceGuard, getTelegramUpdateExecutionFence, registerTelegramUpdateHandler, type TelegramUpdateExecutionFence, type TelegramUpdateHandler, type TelegramUpdateHandlerVerdict, } from "../lib/updates.ts";

package/dist/api/updates.js

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram updates API
+ * Zones: package boundary, extension interop
+ * Exposes the stable raw-update handler surface while keeping update routing internals package-private
+ */
+export { assertTelegramUpdateExecutionCurrent, carryTelegramUpdateExecutionFence, createTelegramUpdateExecutionFenceGuard, getTelegramUpdateExecutionFence, registerTelegramUpdateHandler, } from "../lib/updates.js";

package/dist/api/voice.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram voice API
+ * Zones: package boundary, extension interop
+ * Exposes the stable STT/TTS provider surface and voice policy helpers
+ */
+export { TELEGRAM_VOICE_REPLY_MODES, computeVoicePromptContribution, computeVoiceTurnFlags, getTelegramVoiceReplyMode, isVoiceTurn, registerTelegramVoiceSynthesisProvider, registerTelegramVoiceTranscriptionProvider, shouldSuppressPreviewForVoice, type TelegramVoiceReplyMode, type TelegramVoiceSynthesisProvider, type TelegramVoiceSynthesisProviderResult, type TelegramVoiceTranscriptionFile, type TelegramVoiceTranscriptionProvider, type TelegramVoiceTranscriptionProviderResult, type TelegramVoiceTurnView, } from "../lib/voice.ts";

package/dist/api/voice.js

@@ -0,0 +1,6 @@
+/**
+ * Public Telegram voice API
+ * Zones: package boundary, extension interop
+ * Exposes the stable STT/TTS provider surface and voice policy helpers
+ */
+export { TELEGRAM_VOICE_REPLY_MODES, computeVoicePromptContribution, computeVoiceTurnFlags, getTelegramVoiceReplyMode, isVoiceTurn, registerTelegramVoiceSynthesisProvider, registerTelegramVoiceTranscriptionProvider, shouldSuppressPreviewForVoice, } from "../lib/voice.js";

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Telegram package entrypoint
+ * Zones: telegram, pi agent, public API
+ * Re-exports the extension composition root without owning runtime wiring.
+ */
+export { default } from "./lib/extension.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * Telegram package entrypoint
+ * Zones: telegram, pi agent, public API
+ * Re-exports the extension composition root without owning runtime wiring.
+ */
+export { default } from "./lib/extension.js";

package/dist/lib/activity-verbosity.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Bridge-owned Telegram activity verbosity projection
+ * Zones: telegram activity, rich rendering, operational delivery
+ * Owns persistent bounded thinking and tool disclosures; excludes activity normalization, assistant answer rendering, and transport authority policy
+ */
+import type { TelegramActivityEvent, TelegramActivityPublicationRuntime } from "./activity.ts";
+import type { TelegramEditMessageTextBody, TelegramInputRichMessage, TelegramSendMessageBody, TelegramSendRichMessageBody, TelegramSentMessage } from "./telegram-api.ts";
+import type { TelegramTarget } from "./target.ts";
+export declare const TELEGRAM_ACTIVITY_DETAIL_MAX_CHARS = 1200;
+export declare const TELEGRAM_ACTIVITY_MESSAGE_MAX_CHARS = 3900;
+export declare const TELEGRAM_ACTIVITY_MESSAGE_MAX_TOOLS = 6;
+export declare const TELEGRAM_REASONING_MESSAGE_MAX_FRAMES = 24;
+export declare const TELEGRAM_REASONING_BUFFER_MAX_CHARS = 1200;
+export declare const TELEGRAM_REASONING_MIN_INTERVAL_MS = 1200;
+export declare const TELEGRAM_TOOL_UPDATE_MAX_ENTRIES = 4;
+interface ToolActivity {
+    id: string;
+    name: string;
+    args: string;
+    updates: string[];
+    droppedUpdates: number;
+    result?: string;
+    isError?: boolean;
+    complete: boolean;
+}
+export declare function renderTelegramToolActivityHtml(tools: readonly ToolActivity[]): string;
+export declare function renderTelegramToolActivityRichMessage(tools: readonly ToolActivity[]): TelegramInputRichMessage;
+export declare function renderTelegramThinkingActivityHtml(text: string): string;
+export interface TelegramActivityVerbosityRuntime {
+    accept: (event: TelegramActivityEvent) => void;
+    reset: () => void;
+    stop: () => void;
+    waitForIdle: () => Promise<void>;
+}
+export interface TelegramActivityVerbosityBinding extends TelegramActivityVerbosityRuntime {
+    bind: (runtime: TelegramActivityVerbosityRuntime) => void;
+}
+export declare function createTelegramActivityVerbosityBinding(): TelegramActivityVerbosityBinding;
+export declare function createTelegramActivityVerbosityRuntime<TAuthority>(deps: {
+    enqueue?: TelegramActivityPublicationRuntime["enqueue"];
+    getActivityMode: () => "quiet" | "thinking" | "tools" | "verbose";
+    refreshActivityMode?: () => Promise<void>;
+    getNowMs?: () => number;
+    resolveTarget: (event: TelegramActivityEvent) => TelegramTarget | undefined;
+    captureAuthority: () => TAuthority;
+    isAuthorityActive: (authority: TAuthority) => boolean;
+    sendMessage: (body: TelegramSendMessageBody) => Promise<TelegramSentMessage>;
+    sendRichMessage: (body: TelegramSendRichMessageBody) => Promise<TelegramSentMessage>;
+    editMessageText: (body: TelegramEditMessageTextBody) => Promise<"edited" | "unchanged">;
+    recordFailure?: (operation: "config-refresh" | "reasoning-send" | "reasoning-edit" | "tool-send" | "tool-edit", event: TelegramActivityEvent, error: unknown) => void;
+}): TelegramActivityVerbosityRuntime;
+export {};