@llblab/pi-kit 0.1.0 → 0.1.3

package/BACKLOG.md

@@ -1,3 +1,3 @@
 # Backlog
 
-- [ ] `Release`: Configure npm Trusted Publishing and publish the first validated package release after explicit authorization.
+No open work.

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.1.3 - 2026-08-20
+
+- `Extension Releases`: Advances `@llblab/pi-codex-usage` to `0.9.3` for current Pi header-type compatibility and Trusted Publisher releases, and `@llblab/pi-grow-loop` to `0.7.2` for audited Trusted Publisher releases.
+
+## 0.1.2 - 2026-08-20
+
+- `Trusted Release Automation`: Adds tag-gated validation, npm Trusted Publisher provenance, immutable package/tag identity checks, public package verification, and workflow-owned GitHub Release creation through `.github/workflows/release.yml`.
+
+## 0.1.1 - 2026-08-20
+
+- `Telegram Release`: Advances `@llblab/pi-telegram` to `0.36.7`, bringing proactive prompt-button delivery, explicit connection-state context, scoped Telegram control activation, provider-neutral voice configuration guidance, separated tool errors, host compatibility, prompt-block compatibility, and orphan-journal protection into the bundled kit.
+
 ## 0.1.0 - 2026-08-18
 
 - `Package`: Established a version-pinned Pi distribution bundling Actors, Codex usage, Grow Loop, and Telegram extensions with their declared Skills behind one installable package.

package/README.md

@@ -7,9 +7,9 @@
 | Package | Version | Resources |
 | --- | ---: | --- |
 | `@llblab/pi-actors` | `0.49.1` | Extension and Skills |
-| `@llblab/pi-codex-usage` | `0.9.2` | Extension |
-| `@llblab/pi-grow-loop` | `0.7.1` | Extension and Skills |
-| `@llblab/pi-telegram` | `0.36.1` | Extension and Skills |
+| `@llblab/pi-codex-usage` | `0.9.3` | Extension |
+| `@llblab/pi-grow-loop` | `0.7.2` | Extension and Skills |
+| `@llblab/pi-telegram` | `0.36.7` | Extension and Skills |
 
 Versions are exact by design. Updating an extension does not change an installed kit until this repository explicitly advances that dependency and publishes a new kit version.
 
@@ -18,7 +18,7 @@ Versions are exact by design. Updating an extension does not change an installed
 From npm after publication:
 
 ```bash
-pi install npm:@llblab/pi-kit@0.1.0
+pi install npm:@llblab/pi-kit@0.1.1
 ```
 
 For local development:

package/node_modules/@llblab/pi-codex-usage/CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 
-## Unreleased
+## 0.9.3: Trusted Release Automation
+
+- Added tag-gated release automation with exact package/lock/tag identity checks, full package validation, npm Trusted Publisher provenance, public registry verification, and workflow-owned GitHub Release creation through `.github/workflows/release.yml`.
+- Normalized nullable provider headers into the string-only request header contract, preserving compatibility with current Pi model-registry types while omitting intentionally removed headers.
 
 ## 0.9.1: Clear Weekly Quota Status
 

package/node_modules/@llblab/pi-codex-usage/index.ts

@@ -652,7 +652,10 @@ async function resolvePiCodexAuth(
       continue;
     }
 
-    const headers = { ...(auth.headers ?? {}) };
+    const headers: Record<string, string> = {};
+    for (const [name, value] of Object.entries(auth.headers ?? {})) {
+      if (value !== null) headers[name] = value;
+    }
     if (!hasHeader(headers, "Authorization") && auth.apiKey) {
       headers.Authorization = `Bearer ${auth.apiKey}`;
     }

package/node_modules/@llblab/pi-codex-usage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-codex-usage",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "private": false,
   "description": "Minimal Pi extension that shows primary Codex ChatGPT subscription usage limits",
   "keywords": [
@@ -28,8 +28,9 @@
     "check": "node --experimental-strip-types -e \"await import('./index.ts'); console.log('pi-codex-usage: extension import ok')\"",
     "test": "node --experimental-strip-types --test test/*.test.ts",
     "typecheck": "tsc --noEmit",
+    "audit": "npm audit --omit=peer",
     "pack:dry": "npm pack --dry-run",
-    "validate": "npm run typecheck && npm run test && npm run check && npm run pack:dry"
+    "validate": "npm run typecheck && npm run test && npm run check && npm run audit && npm run pack:dry"
   },
   "files": [
     "index.ts",

package/node_modules/@llblab/pi-grow-loop/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.2: Trusted Release Automation
+
+- [Release] Add tag-gated package validation, npm Trusted Publisher provenance, immutable package/tag identity checks, public registry verification, and workflow-owned GitHub Release creation through `.github/workflows/release.yml`.
+
 ## 0.7.1: Banner Presentation Hotfix
 
 - [Docs] Display the packaged project banner at the top of the README through its stable repository URL so GitHub and npm readers see the release identity immediately.

package/node_modules/@llblab/pi-grow-loop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-grow-loop",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "private": false,
   "description": "Semantic loop-engineering for agent-owned, visible, interruptible continuation in Pi",
   "keywords": [
@@ -29,8 +29,9 @@
     "check": "node --experimental-strip-types -e \"await import('./index.ts'); console.log('pi-grow-loop: extension import ok')\"",
     "typecheck": "tsc --noEmit",
     "test": "node --experimental-strip-types --test test/*.test.ts",
+    "audit": "npm audit --omit=peer",
     "pack:dry": "npm pack --dry-run",
-    "validate": "npm run test && npm run typecheck && npm run check && npm run pack:dry"
+    "validate": "npm run test && npm run typecheck && npm run check && npm run audit && npm run pack:dry"
   },
   "files": [
     "banner.jpg",

package/node_modules/@llblab/pi-telegram/BACKLOG.md

@@ -2,7 +2,6 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
-- [ ] `Automated release publication live proof`: Exercise the implemented tag-triggered release path on `v0.36.1` and verify reusable full validation, exact tag/version/lock/changelog preflight, npm Trusted Publisher provenance, idempotent package identity, public tarball contents, and one workflow-owned GitHub Release before declaring manual npm publication retired.
 - [ ] `Operator-confirmed pairing`: Replace first-contact automatic ownership with an explicit pending request that the trusted Pi interface can allow or reject before `allowedUserId` is persisted or any Telegram prompt executes; retain manual preconfiguration, bound pending-request lifetime and multiplicity, fail closed across session/transport replacement, and cover unauthorized-first-contact races.
 - [ ] `Environment-backed bot tokens`: Let each profile store an exact Pi-native `$ENV_VAR` or `${ENV_VAR}` reference in `telegram.json` instead of copying the resolved secret; preserve the originating alias when `/telegram-setup` prefills from a supported environment variable, resolve only at validation/activation boundaries, fail closed with a redacted named-variable diagnostic when unresolved, retain literal-token compatibility, and cover named profiles, reload, persistence, status, and secret-redaction paths.
 - [ ] [`Inference bypass Generative Apps`](./docs/generative-apps.md): Let the agent install and bind one managed JavaScript app owner for a generated-prompt prefix so deterministic controls can bypass model inference without creating another button grammar.

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -2,7 +2,33 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
-## Unreleased
+## 0.36.7: Context-Aware Proactive Controls
+
+- `Proactive Prompt Buttons`: Plans valid top-level `telegram_button` comments before local/autonomous assistant segments enter Rich or HTML proactive delivery, preserving the ordinary callback store and renderer path instead of silently hiding correct controls.
+- `Connection-Aware Agent Context`: Successful setup/connect and disconnect commands queue a hidden connection-state note for delivery with the next agent turn without triggering one. Connected system guidance and Telegram Skills now distinguish transport capability from user intent, reserving proactive Telegram controls for Telegram-originated turns or explicit requests.
+
+## 0.36.6: Orphan Journal Guard
+
+- `Orphan Journal Guard`: Rejects a missing journal snapshot when immutable revision segments still exist, preventing later admission from replacing uncertain durable authority with a new revisionless snapshot while preserving snapshot-first compaction and fail-closed recovery.
+- `Voice Configuration Guidance`: Guides agents from voice-configuration requests to provider-neutral `telegram.json` command templates, ordered STT fallbacks, OGG/Opus validation, and companion-provider alternatives while preserving `hidden` as the useful default for explicit `telegram_voice` delivery.
+
+## 0.36.5: Separated Tool Errors
+
+- `Separated Tool Errors`: Prefixes Telegram attachment and direct-message Tool failures with one normalized leading newline so Pi renders error evidence on a visually separated line beneath the Tool name without changing the underlying diagnostic text.
+
+## 0.36.4: Async Host Settings Compatibility
+
+- `Async Host Settings`: Normalizes synchronous or asynchronous settings construction plus legacy enabled-model methods or generic `get` / `set` services at the Pi adapter boundary before model-menu reads and scoped-model persistence, improving compatible-host interoperability without changing native Pi behavior or weakening required `agent_settled` semantics.
+
+## 0.36.3: Ordered Prompt Compatibility
+
+- `Prompt Compatibility`: Preserves plain and ordered-block system prompts across Pi-compatible runtimes; Telegram guidance remains a distinct block when the host supplies blocks, while unavailable transport strips only Telegram tool metadata without collapsing unrelated prompt context.
+
+## 0.36.2: Provider-Compatible Controls
+
+- `Provider-Compatible Bind Schema`: Exposes `telegram_bind` through one top-level JSON object schema while retaining runtime enforcement of mutually exclusive install and invocation forms, avoiding providers that reject top-level union schemas before any tool call can run.
+- `Reaction Shortcut Naming`: Removes obsolete reaction-action labels from setup guidance now that queue reaction semantics use their current naming.
+- `Compact Thinking Picker`: Keeps `off` on a distinct full-width row and groups the six ordered reasoning intensities into two three-button rows, reducing menu height without changing thinking-level values or callbacks.
 
 ## 0.36.1: Adaptive Control Surfaces
 
@@ -12,7 +38,7 @@
 - `Destructive Skip State`: Changes the active queue Skip selector from yellow to red and records the indicator in the UI registry, making deferred prompt removal visually distinct from Priority, Scoped, and other elevated but non-destructive states.
 - `Worker Cancellation Fence`: Makes Generative App workers acknowledge child-process abort handling before parent termination, with a bounded forced fallback for synchronously blocked methods, preventing Linux CI load from orphaning a cancelled process long enough to commit its delayed side effect.
 - `Capability App Routing`: Telegram interaction now prefers an already-advertised capability-owned Generative App for repeated controls before synthesizing one-shot prompt buttons, while the bridge remains generic and neither discovers capability-specific apps nor owns their state or identities.
-- `Hybrid Surface Breadcrumbs`: Generated Control Surface and Generative Apps now cross-route over one logical button matrix and shared JSON/CML runtime notation: ephemeral agent composition stays separate from reusable scripts, while one app view may combine deterministic bound methods with ordinary model-mediated prompts and no third button Skill is introduced.
+- `Hybrid Surface Routing`: Generated Control Surface and Generative Apps now cross-route over one logical button matrix and shared JSON/CML runtime notation: ephemeral agent composition stays separate from reusable scripts, while one app view may combine deterministic bound methods with ordinary model-mediated prompts and no third button Skill is introduced.
 
 ## 0.36.0: Generative Apps
 

package/node_modules/@llblab/pi-telegram/README.md

@@ -8,7 +8,7 @@
 
 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.
 
-Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. Proactive push is enabled by default for local, autonomous, and unclassified extension follow-up work: `assistant.proactivePush` projects visible checkpoints and the final answer to the authorized Telegram target once and in order; set it explicitly to `false` to disable only that local/autonomous projection. 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).
+Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. Proactive push is enabled by default for local, autonomous, and unclassified extension follow-up work: `assistant.proactivePush` 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; set it explicitly to `false` to disable only that local/autonomous projection. 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).
 
 This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 
@@ -28,6 +28,8 @@ pi install git:github.com/llblab/pi-telegram
 
 The 0.21 extension platform requires Pi `0.80.6` or newer. Its Activity API uses the public `agent_settled` lifecycle event to keep retries/continuations under one activity identity and release that identity only after the run fully settles.
 
+Pi is the primary and only officially supported host. Narrow host-neutral adapters preserve ordered prompt blocks and normalize synchronous or asynchronous legacy/generic settings services for Pi-compatible hosts, but this is best-effort compatibility rather than an OMP support guarantee. Alternate-host shims must still reproduce required Pi lifecycle semantics—especially `agent_settled`—and their maintainers own ongoing validation.
+
 ## Quick Start
 
 ### 1. Create a Telegram bot
@@ -86,7 +88,7 @@ Enable the optional capabilities the bridge needs in the [@BotFather](https://t.
 
 1. Enable guest mode so the bot can answer mentions and replies in chats where it is not a member.
 2. Enable private-chat Threaded Mode; when it is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. Without it, the bridge stays in classic single-owner DM mode.
-3. Make the bot an administrator in any chat where the queue reaction shortcuts (👍 prioritize, 👎 suppress) should work. Reaction updates require admin rights, so the shortcuts silently do nothing in non-admin chats; private chats deliver reactions without admin rights.
+3. Make the bot an administrator in any chat where the queue reaction shortcuts should work. Reaction updates require admin rights, so the shortcuts silently do nothing in non-admin chats; private chats deliver reactions without admin rights.
 
 ## What It Feels Like
 
@@ -216,7 +218,7 @@ Inbound files land under `<agent-dir>/tmp/telegram` and default to a 50 MiB limi
 
 ### Voice And Media
 
-Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Explicit `telegram_voice` actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and one colon-free action marker.
+Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Configure provider-neutral local/API pipelines and ordered fallbacks through [`telegram.json` command templates](./docs/voice.md#choose-an-integration-path). The default `hidden` reply mode still supports intentional voice delivery through explicit `telegram_voice` actions; `mirror` and `always` add automatic voice policy. Explicit actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and one colon-free action marker.
 
 ### Buttons And Callbacks
 

package/node_modules/@llblab/pi-telegram/docs/architecture.md

@@ -88,6 +88,16 @@ The repository uses a **Flat Domain DAG**:
 - `bindings` / `lifecycle` / `prompts` / `prompt-templates` / `pi`: Pi-facing command/tool/hook registration and cohesive cross-domain binding assembly, including queue mutation/dispatch/watchdog composition over admission and transport ports; session-generation fencing and start/shutdown sequencing across Queue, grouped input, Delivery, polling, capability monitor, follower refresh, and assistant-output projection; Telegram prompt guidance; prompt-template discovery/expansion; and centralized direct Pi SDK imports.
 - `command-templates`: shell-free command-template helpers, composition expansion, placeholder substitution, executable resolution, warnings, and retry/timeout semantics.
 
+### Host Compatibility Boundary
+
+Pi is the primary and only officially supported host. `pi-telegram` may still accept narrow, host-neutral representation differences at its existing Pi-facing boundary when they preserve native Pi behavior and do not create a second runtime policy layer:
+
+- `prompts` preserves either Pi's plain system-prompt string or an ordered block array supplied by a compatible host, appending Telegram guidance without collapsing host-owned blocks.
+- `pi` normalizes settings-manager construction that is either synchronous or asynchronous, then adapts either Pi's legacy enabled-model methods or a generic `get` / `set` settings service before model-menu reads and scoped-model persistence use it. Hosts without an explicit reload method rely on fresh asynchronous construction; durable writes still require `flush`.
+- `lifecycle` continues to require Pi's semantic `agent_settled` boundary. It does not infer terminal settlement from host-specific `agent_end`, retry, or stop events; a compatibility shim must reproduce that contract before it can safely support activity identity and unrecovered-error finalization.
+
+This boundary uses no host-name detection, host package dependency, prototype patching, hidden agent process, PTY, or terminal forwarding. Representation adapters are best-effort compatibility rather than an OMP support guarantee. Alternate hosts and community contributors own validation of their compatibility shims and must supply every lifecycle semantic that the bridge requires.
+
 ### Guarded Invariants
 
 Architecture invariant tests protect:

package/node_modules/@llblab/pi-telegram/docs/outbound.md

@@ -12,7 +12,7 @@ Every completed `assistant-segment` with `placement: "intermediate"` from a Tele
 
 Proactive projection defaults on for local, autonomous, and unclassified extension follow-up Pi work. With `assistant.proactivePush` omitted or set to `true`, every completed public block—including visible commentary/checkpoints and the final answer—is projected to the instance's authorized target in source order; set it explicitly to `false` to opt out of only this local/autonomous projection. Both paths consume normalized complete Activity segments rather than raw token deltas, reasoning, or tool traffic.
 
-Projected blocks use `assistant.rendering` independently of voice policy. Rich mode sends native Rich Markdown and HTML mode keeps the established HTML renderer; projection does not synthesize voice or attach queued files merely because Rich rendering is active. Ordered admission revalidates the exact target, profile/token transport generation, leader epoch or follower registration generation, and session generation before each send. Active-turn final delivery waits for admitted commentary inside its existing background delivery task, preserving commentary-before-final order without blocking Pi lifecycle completion. A `commit-unknown` outcome never permits replay.
+Projected blocks use `assistant.rendering` independently of voice policy. Rich mode sends native Rich Markdown and HTML mode keeps the established HTML renderer; assistant-authored `telegram_button` comments are planned into prompt buttons before either renderer runs, while projection does not synthesize voice or attach queued files merely because Rich rendering is active. Ordered admission revalidates the exact target, profile/token transport generation, leader epoch or follower registration generation, and session generation before each send. Active-turn final delivery waits for admitted commentary inside its existing background delivery task, preserving commentary-before-final order without blocking Pi lifecycle completion. A `commit-unknown` outcome never permits replay.
 
 ## Technical Activity
 

package/node_modules/@llblab/pi-telegram/docs/public-api.md

@@ -40,8 +40,8 @@ import {
 Stable commands inside Pi:
 
 - `/telegram-setup` — configure/update the bot token.
-- `/telegram-connect` — start polling here and acquire external Telegram control ownership. Accepted queue/reply state stays local if ownership later moves elsewhere.
-- `/telegram-disconnect` — after destructive confirmation, stop polling and release ownership without deleting or silencing accepted local queue state. In Threaded Mode it deletes this instance's current Telegram thread; a follower waits for its active leader to confirm generation-fenced cleanup before stopping. Graceful Pi `quit` performs the same teardown without prompting, while `reload`, `new`, `resume`, and `fork` preserve same-process handoff.
+- `/telegram-connect` — start polling here and acquire external Telegram control ownership. Accepted queue/reply state stays local if ownership later moves elsewhere. A successful command queues a hidden connection-state note for delivery with the agent's next turn without triggering one; it says Telegram is connected and that connectivity alone is not user intent.
+- `/telegram-disconnect` — after destructive confirmation, stop polling and release ownership without deleting or silencing accepted local queue state. A successful command queues the corresponding hidden, non-triggering disconnected context note; cancelled or failed disconnects do not publish a false state transition. In Threaded Mode it deletes this instance's current Telegram thread; a follower waits for its active leader to confirm generation-fenced cleanup before stopping. Graceful Pi `quit` performs the same teardown without prompting, while `reload`, `new`, `resume`, and `fork` preserve same-process handoff.
 - `/telegram-status` — show connection, polling, execution, queue, and recent event diagnostics; debug output separates poller and worker progress, durable automatic-retry state, exact foreign queued-owner identity, and negotiated protocol/build/capabilities.
 
 ### Telegram commands

package/node_modules/@llblab/pi-telegram/docs/ui-style.md

@@ -168,22 +168,23 @@ Examples:
 - `⚫️ Priority` / `🟣 Normal`
 - `1` / `🟣 2` / `3`
 
-## Vertical Option Lists
+## Option Lists
 
-Vertical option lists choose one value from a potentially longer list, for example model selection, thinking level, voice reply mode, or time injection mode.
+Option lists choose one value from a fixed set, for example model selection, thinking level, voice reply mode, or time injection mode.
 
 Rules:
 
-- Put each option on its own row.
+- Put each option on its own row when labels are long, the set may grow, or scanning benefits from full width.
+- A fixed set of short, ordered peer values may use compact rows of up to three buttons.
+- Keep a semantically distinct value such as thinking `off` on its own full-width row before grouped intensity values.
 - Mark only the current value with `🟢`.
 - Leave non-current values without emoji.
 - Use lowercase labels when the option is a value.
 
 Examples:
 
-- `hidden`
-- `🟢 mirror`
-- `always`
+- Vertical: `hidden`, `🟢 mirror`, `always`.
+- Thinking: full-width `off`, then `minimal` / `low` / `🟢 medium`, then `high` / `xhigh` / `max`.
 
 ## Generated Prompt Buttons
 

package/node_modules/@llblab/pi-telegram/docs/voice.md

@@ -6,10 +6,20 @@ Voice messages flow through an **inbound transcription → outbound voice reply*
 
 1. **Inbound:** A voice message arrives via Telegram. Inbound handlers transcribe it to text.
 2. **Processing:** The transcription becomes the agent prompt. The bridge tags the turn if it originated from voice.
-3. **Outbound:** If voice replies are enabled, the agent's text response is converted to voice and sent back. No text draft appears in Telegram during generation.
+3. **Outbound:** When automatic voice delivery is selected or the agent emits an explicit `telegram_voice` action, the agent's text is converted to voice and sent back.
 
 The bridge owns Telegram transport, queue integration, reply-mode policy, preview suppression, fallback text delivery, and Settings UI. Provider extensions own STT/TTS calls, speech rewriting, provider-specific menus, transcript preference, and OGG/Opus conversion.
 
+### Choose an integration path
+
+Use the smallest path that fits the operator's available capabilities:
+
+1. **`telegram.json` command templates:** Compose trusted local executables through `inboundHandlers` and `outboundHandlers`. This works equally well for local models and API-backed scripts, supports ordered STT fallbacks, and requires no companion extension.
+2. **Companion extension:** Register programmatic STT/TTS providers when installation, provider-owned settings, lifecycle integration, or zero-config reuse justifies code.
+3. **Hybrid:** Keep explicit operator command templates first and let installed providers supply progressive fallbacks.
+
+pi-telegram does not catalog speech providers. Configuration agents should discover applicable Skills or trusted local executables, verify required environment variables by presence without exposing values, preserve unrelated `telegram.json` state, ensure TTS ends as OGG/Opus, and test each stage before the live Telegram path. `hidden` remains the safe and useful default: it disables only automatic voice replies, while explicit `telegram_voice` actions continue to use the configured synthesis pipeline.
+
 ## Voice Detection
 
 Voice messages arrive as `message.voice` in Telegram updates. The bridge's media processing detects these and sets `kind: "voice"` on the downloaded file. Regular audio files (`message.audio`) get `kind: "audio"`; `mirror` mode treats both voice notes and audio uploads as voice input for reply-policy tagging.

package/node_modules/@llblab/pi-telegram/index.ts

@@ -539,6 +539,8 @@ export default function (pi: Pi.ExtensionAPI) {
         sendRichMessage,
         editMessage: editTelegramMessageText,
         getAssistantRenderingMode: configControls.getAssistantRenderingMode,
+        planButtonReply:
+          Outbound.createTelegramButtonReplyPlanner(buttonActionStore),
         execCommand: CommandTemplates.execCommandTemplate,
         getHandlers: configStore.getOutboundHandlers,
         recordRuntimeEvent,

package/node_modules/@llblab/pi-telegram/lib/bindings.ts

@@ -514,6 +514,18 @@ export function registerTelegramCommandsAndTools({
       sendMarkdownReply(chatId, undefined, markdown, options),
     recordRuntimeEvent,
   });
+  const queueAgentConnectionContext = (connected: boolean): void => {
+    pi.sendMessage(
+      {
+        customType: "telegram-connection-state",
+        content: connected
+          ? Prompts.TELEGRAM_CONNECTED_CONTEXT_MESSAGE
+          : Prompts.TELEGRAM_DISCONNECTED_CONTEXT_MESSAGE,
+        display: false,
+      },
+      { deliverAs: "nextTurn" },
+    );
+  };
   Commands.registerTelegramBridgeCommands(pi, {
     promptForConfig: async (ctx, profileName) => {
       const nextProfileName = profileName ?? undefined;
@@ -581,8 +593,11 @@ export function registerTelegramCommandsAndTools({
         recordRuntimeEvent,
       });
       const completion = await runSetup(ctx);
-      if (profileName && completion.status === "success") {
-        ctx.ui.notify(`Profile "${profileName}" saved and connected.`, "info");
+      if (completion.status === "success") {
+        queueAgentConnectionContext(true);
+        if (profileName) {
+          ctx.ui.notify(`Profile "${profileName}" saved and connected.`, "info");
+        }
       }
     },
     getStatusLines,
@@ -599,6 +614,7 @@ export function registerTelegramCommandsAndTools({
     stopPolling: stopPolling ?? lockedPollingRuntime.stop,
     recoverPollingStart,
     getDisconnectThreadName,
+    queueAgentConnectionContext,
     updateStatus,
     getProfileNames: () =>
       Config.getTelegramProfileNames(configStore.getStoredConfig()),

package/node_modules/@llblab/pi-telegram/lib/commands.ts

@@ -334,6 +334,7 @@ export interface TelegramBridgeCommandRegistrationDeps {
     error: unknown,
   ) => Promise<TelegramPollingStartRecoveryResult>;
   getDisconnectThreadName?: () => string | undefined;
+  queueAgentConnectionContext?: (connected: boolean) => void;
   updateStatus: (ctx: ExtensionCommandContext) => void;
   getProfileNames?: () => string[];
   activateDefaultProfileConfig?: (ctx: ExtensionCommandContext) => Promise<void>;
@@ -468,6 +469,9 @@ export function registerTelegramBridgeCommands(
       if (result?.message) {
         ctx.ui.notify(result.message, result.ok ? "info" : "warning");
       }
+      if (!result || result.ok) {
+        deps.queueAgentConnectionContext?.(true);
+      }
       deps.updateStatus(ctx);
     },
   });
@@ -490,6 +494,7 @@ export function registerTelegramBridgeCommands(
       try {
         const message = await deps.stopPolling();
         if (message) ctx.ui.notify(message, "info");
+        deps.queueAgentConnectionContext?.(false);
       } catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
         ctx.ui.notify(

package/node_modules/@llblab/pi-telegram/lib/generative-apps.ts

@@ -871,21 +871,14 @@ export function registerTelegramBindTool(
     label: "Telegram Bind",
     description:
       "Install, explicitly replace, or invoke one named method on a managed Generative App; successful output displays directly in the active Telegram turn unless display is false.",
-    parameters: Type.Union([
-      Type.Object({
-        app: Type.String(),
-        script: Type.String(),
-        replace: Type.Optional(Type.Boolean()),
-        display: Type.Optional(Type.Boolean()),
-        argument: Type.Optional(Type.Unknown()),
-      }, { additionalProperties: false }),
-      Type.Object({
-        app: Type.String(),
-        method: Type.String(),
-        display: Type.Optional(Type.Boolean()),
-        argument: Type.Optional(Type.Unknown()),
-      }, { additionalProperties: false }),
-    ]),
+    parameters: Type.Object({
+      app: Type.String(),
+      script: Type.Optional(Type.String()),
+      method: Type.Optional(Type.String()),
+      replace: Type.Optional(Type.Boolean()),
+      display: Type.Optional(Type.Boolean()),
+      argument: Type.Optional(Type.Unknown()),
+    }, { additionalProperties: false }),
     async execute(_toolCallId, params) {
       try {
         const result = await bindGenerativeApp({

package/node_modules/@llblab/pi-telegram/lib/journal.ts

@@ -1757,6 +1757,30 @@ export function createTelegramUpdateJournalStore(
     } catch (error) {
       if (error instanceof TelegramUpdateJournalError) throw error;
       if ((error as { code?: unknown })?.code === "ENOENT") {
+        const segmentDirectory = getTelegramUpdateJournalSegmentDirectory(path);
+        let orphanedSegmentNames: string[];
+        try {
+          orphanedSegmentNames = readdirSync(segmentDirectory).filter((name) =>
+            /^\d{16}\.json$/u.test(name),
+          );
+        } catch (segmentError) {
+          if ((segmentError as { code?: unknown })?.code === "ENOENT") {
+            return { file: emptyFile(), exists: false, serializedBytes: 0 };
+          }
+          throw createJournalError(
+            "io",
+            segmentDirectory,
+            "could not be read while the journal snapshot is missing",
+            segmentError,
+          );
+        }
+        if (orphanedSegmentNames.length > 0) {
+          throw createJournalError(
+            "invalid",
+            path,
+            `is missing while ${segmentDirectory} retains revision segments`,
+          );
+        }
         return { file: emptyFile(), exists: false, serializedBytes: 0 };
       }
       throw createJournalError("io", path, "could not be read", error);

package/node_modules/@llblab/pi-telegram/lib/lifecycle.ts

@@ -40,8 +40,15 @@ export function createAgentStartDedupHook(
   };
 }
 
+type TelegramBeforeAgentStartEvent = Omit<
+  BeforeAgentStartEvent,
+  "systemPrompt"
+> & {
+  systemPrompt: string | string[];
+};
+
 export interface TelegramBeforeAgentStartResult {
-  systemPrompt?: string;
+  systemPrompt?: string | string[];
 }
 
 type TelegramBeforeAgentStartReturn =
@@ -72,7 +79,7 @@ export interface TelegramLifecycleRegistrationDeps {
     ctx: ExtensionContext,
   ) => Promise<void> | void;
   onBeforeAgentStart: (
-    event: BeforeAgentStartEvent,
+    event: TelegramBeforeAgentStartEvent,
     ctx: ExtensionContext,
   ) => TelegramBeforeAgentStartReturn;
   onModelSelect: (
@@ -581,7 +588,16 @@ export function registerTelegramLifecycleHooks(
     if (!isActive(ctx)) return;
     await deps.onSessionCompact?.(event, ctx);
   });
-  pi.on("before_agent_start", async (event, ctx) => {
+  // The Pi SDK still types this result as a string; compatible runtimes may
+  // preserve ordered system prompt blocks through the same public hook.
+  const registerBeforeAgentStart = pi.on.bind(pi) as unknown as (
+    event: "before_agent_start",
+    handler: (
+      event: TelegramBeforeAgentStartEvent,
+      ctx: ExtensionContext,
+    ) => TelegramBeforeAgentStartReturn,
+  ) => void;
+  registerBeforeAgentStart("before_agent_start", async (event, ctx) => {
     return deps.onBeforeAgentStart(event, ctx);
   });
   pi.on("model_select", async (event, ctx) => {

package/node_modules/@llblab/pi-telegram/lib/menu-model.ts

@@ -119,7 +119,9 @@ export interface TelegramModelMenuStateBuilderDeps<
     TelegramModelMenuStateBuilderContext<TModel>,
 > {
   runtime: TelegramModelMenuRuntime<TModel>;
-  createSettingsManager: (cwd: string) => MenuSettingsManager;
+  createSettingsManager: (
+    cwd: string,
+  ) => MenuSettingsManager | PromiseLike<MenuSettingsManager>;
   getActiveModel: (ctx: TContext) => TModel | undefined;
 }
 
@@ -490,7 +492,7 @@ export function createTelegramModelMenuStateBuilder<
   threadId?: number,
 ) => Promise<TelegramModelMenuState<TModel>> {
   return async (chatId, ctx, threadId) => {
-    const settingsManager = deps.createSettingsManager(ctx.cwd);
+    const settingsManager = await deps.createSettingsManager(ctx.cwd);
     return deps.runtime.buildState({
       chatId,
       threadId,

package/node_modules/@llblab/pi-telegram/lib/menu-thinking.ts

@@ -128,13 +128,14 @@ export function buildThinkingMenuReplyMarkup(
   currentThinkingLevel: ThinkingLevel,
 ): TelegramReplyMarkup {
   const rows = [[{ text: "⬆️ Main menu", callback_data: "menu:back" }]];
+  const levelButtons = THINKING_LEVELS.map((level) => ({
+    text: level === currentThinkingLevel ? `🟢 ${level}` : level,
+    callback_data: `thinking:set:${level}`,
+  }));
   rows.push(
-    ...THINKING_LEVELS.map((level) => [
-      {
-        text: level === currentThinkingLevel ? `🟢 ${level}` : level,
-        callback_data: `thinking:set:${level}`,
-      },
-    ]),
+    levelButtons.slice(0, 1),
+    levelButtons.slice(1, 4),
+    levelButtons.slice(4, 7),
   );
   return { inline_keyboard: rows };
 }

package/node_modules/@llblab/pi-telegram/lib/outbound-attachments.ts

@@ -436,6 +436,11 @@ async function buildTelegramOutboundAttachmentViews(options: {
   return pendingAttachments;
 }
 
+function formatTelegramOutboundToolError(error: unknown): Error {
+  const message = error instanceof Error ? error.message : String(error);
+  return new Error(`\n${message.replace(/^\n+/u, "") || "Telegram outbound operation failed."}`);
+}
+
 export function registerTelegramOutboundAttachmentTool(
   pi: ExtensionAPI,
   deps: TelegramOutboundAttachmentToolRegistrationDeps,
@@ -496,7 +501,7 @@ export function registerTelegramOutboundAttachmentTool(
           phase: "queue",
           count: params.paths.length,
         });
-        throw error;
+        throw formatTelegramOutboundToolError(error);
       }
     },
   });
@@ -548,7 +553,7 @@ export function registerTelegramOutboundMessageTool(
         });
       } catch (error) {
         deps.recordRuntimeEvent?.("message", error, { phase: "direct" });
-        throw error;
+        throw formatTelegramOutboundToolError(error);
       }
     },
   });

package/node_modules/@llblab/pi-telegram/lib/outbound.ts

@@ -958,6 +958,10 @@ export function createTelegramAssistantOutputSender<
   ) => Promise<TelegramSentMessage>;
   editMessage: (body: TelegramEditMessageTextBody) => Promise<unknown>;
   getAssistantRenderingMode: () => "rich" | "html";
+  planButtonReply?: (markdown: string) => {
+    markdown: string;
+    replyMarkup?: TReplyMarkup;
+  };
   execCommand: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["execCommand"];
   getHandlers?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["getHandlers"];
   recordRuntimeEvent?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["recordRuntimeEvent"];
@@ -997,11 +1001,19 @@ export function createTelegramAssistantOutputSender<
       getHandlers: deps.getHandlers,
       recordRuntimeEvent: deps.recordRuntimeEvent,
     });
+    const buttonReply = deps.planButtonReply?.(event.text) ?? {
+      markdown: event.text,
+    };
     await outboundRuntime.sendMarkdownReply(
       target.chatId,
       undefined,
-      event.text,
-      { target },
+      buttonReply.markdown,
+      {
+        target,
+        ...(buttonReply.replyMarkup
+          ? { replyMarkup: buttonReply.replyMarkup }
+          : {}),
+      },
     );
   };
 }

package/node_modules/@llblab/pi-telegram/lib/pi.ts

@@ -151,16 +151,82 @@ export function createExtensionApiRuntimePorts(
   };
 }
 
-export function createSettingsManager(cwd: string): PiSettingsManager {
-  return SettingsManager.create(cwd);
+type PiSettingsManagerFactory = {
+  create: (cwd: string) => unknown | PromiseLike<unknown>;
+};
+
+type HostSettingsManager = {
+  reload?: () => void | PromiseLike<void>;
+  flush?: () => void | PromiseLike<void>;
+  getEnabledModels?: () => unknown;
+  setEnabledModels?: (patterns: string[] | undefined) => void;
+  get?: (key: string) => unknown;
+  set?: (key: string, value: unknown) => void;
+};
+
+function readEnabledModels(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    return [...value];
+  }
+  throw new TypeError("Host settings enabledModels must be a string array or undefined.");
+}
+
+export function normalizeSettingsManager(manager: unknown): PiSettingsManager {
+  if (typeof manager !== "object" || manager === null) {
+    throw new TypeError("Host settings manager must be an object.");
+  }
+  const host = manager as HostSettingsManager;
+  if (typeof host.flush !== "function") {
+    throw new TypeError("Host settings manager must provide flush().");
+  }
+  const read = typeof host.getEnabledModels === "function"
+    ? () => host.getEnabledModels!.call(host)
+    : typeof host.get === "function"
+      ? () => host.get!.call(host, "enabledModels")
+      : undefined;
+  const write = typeof host.setEnabledModels === "function"
+    ? (patterns: string[] | undefined) =>
+        host.setEnabledModels!.call(host, patterns)
+    : typeof host.set === "function"
+      ? (patterns: string[] | undefined) =>
+          host.set!.call(host, "enabledModels", patterns ?? [])
+      : undefined;
+  if (!read || !write) {
+    throw new TypeError(
+      "Host settings manager must provide enabled-model read and write capabilities.",
+    );
+  }
+  return {
+    reload: async () => {
+      await host.reload?.call(host);
+    },
+    flush: async () => {
+      await host.flush!.call(host);
+    },
+    getEnabledModels: () => readEnabledModels(read()),
+    setEnabledModels: write,
+  };
+}
+
+export async function createSettingsManager(
+  cwd: string,
+): Promise<PiSettingsManager> {
+  // Pi returns its legacy settings surface synchronously. Compatible hosts may
+  // resolve a generic settings service asynchronously; normalize both once at
+  // the SDK boundary instead of leaking host distinctions into menu domains.
+  const factory = SettingsManager as unknown as PiSettingsManagerFactory;
+  return normalizeSettingsManager(await factory.create(cwd));
 }
 
 export function createScopedModelPatternPersister(deps: {
-  createSettingsManager: (cwd: string) => PiSettingsManager;
+  createSettingsManager: (
+    cwd: string,
+  ) => PiSettingsManager | PromiseLike<PiSettingsManager>;
   clearCachedModelMenuInputs: () => void;
 }): (patterns: string[], ctx: ExtensionContext) => Promise<void> {
   return async (patterns, ctx) => {
-    const settingsManager = deps.createSettingsManager(ctx.cwd);
+    const settingsManager = await deps.createSettingsManager(ctx.cwd);
     settingsManager.setEnabledModels(
       patterns.length > 0 ? patterns : undefined,
     );

package/node_modules/@llblab/pi-telegram/lib/prompts.ts

@@ -7,9 +7,14 @@
 import type { BeforeAgentStartEvent } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
+export const TELEGRAM_CONNECTED_CONTEXT_MESSAGE =
+  "Telegram session connected. Use Telegram features for Telegram-originated turns or explicit Telegram requests; connectivity alone is not user intent.";
+export const TELEGRAM_DISCONNECTED_CONTEXT_MESSAGE =
+  "Telegram session disconnected. Do not use Telegram delivery, actions, or Telegram-specific reply features unless the user reconnects it.";
+
 const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram bridge available. Load the \`telegram-bridge\` Skill for Telegram delivery, actions, Threaded Mode, or diagnosis. Do not use Telegram from local/TUI prompts unless explicitly asked.`;
+${TELEGRAM_CONNECTED_CONTEXT_MESSAGE} Load the \`telegram-bridge\` Skill for Telegram-originated turns or explicit requests involving Telegram delivery, actions, Threaded Mode, or diagnosis. Do not use Telegram-specific features from unrelated local/TUI prompts.`;
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
@@ -31,6 +36,15 @@ export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
 ] as const;
 
+const TELEGRAM_TOOL_METADATA_LINES = Object.fromEntries(
+  [
+    `- telegram_attach: ${TELEGRAM_ATTACH_PROMPT_SNIPPET}`,
+    `- telegram_message: ${TELEGRAM_MESSAGE_PROMPT_SNIPPET}`,
+    ...TELEGRAM_ATTACH_PROMPT_GUIDELINES.map((line) => `- ${line}`),
+    ...TELEGRAM_MESSAGE_PROMPT_GUIDELINES.map((line) => `- ${line}`),
+  ].map((line) => [line, true]),
+) as Record<string, true>;
+
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([
   "telegram_attach",
   "telegram_bind",
@@ -132,13 +146,30 @@ export function createTelegramModelContextAvailabilityRuntime(deps: {
   };
 }
 
+export type TelegramSystemPrompt = string | string[];
+
+type TelegramBeforeAgentStartEvent = Omit<
+  BeforeAgentStartEvent,
+  "systemPrompt"
+> & {
+  systemPrompt: TelegramSystemPrompt;
+};
+
+type TelegramBeforeAgentStartResult = {
+  systemPrompt: TelegramSystemPrompt;
+};
+
+type TelegramBeforeAgentStartHook = (
+  event: TelegramBeforeAgentStartEvent,
+) => TelegramBeforeAgentStartResult;
+
 export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;
-  systemPrompt: string;
+  systemPrompt: TelegramSystemPrompt;
   telegramPrefix?: string;
   localSystemPromptSuffix: string;
   telegramTurnSystemPromptSuffix: string;
-}): { systemPrompt: string } {
+}): TelegramBeforeAgentStartResult {
   const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
   const telegramHead = telegramPrefix.endsWith("]")
     ? telegramPrefix.slice(0, -1)
@@ -151,8 +182,14 @@ export function buildTelegramBridgeSystemPrompt(options: {
     ? `${options.telegramTurnSystemPromptSuffix}\n- The current user message came from Telegram.`
     : "";
   return {
-    systemPrompt:
-      options.systemPrompt + options.localSystemPromptSuffix + telegramSuffix,
+    systemPrompt: Array.isArray(options.systemPrompt)
+      ? [
+          ...options.systemPrompt,
+          options.localSystemPromptSuffix + telegramSuffix,
+        ]
+      : options.systemPrompt +
+        options.localSystemPromptSuffix +
+        telegramSuffix,
   };
 }
 
@@ -162,7 +199,7 @@ export function createTelegramBeforeAgentStartHook(
     localSystemPromptSuffix?: string;
     telegramTurnSystemPromptSuffix?: string;
   } = {},
-): (event: BeforeAgentStartEvent) => { systemPrompt: string } {
+): TelegramBeforeAgentStartHook {
   return (event) =>
     buildTelegramBridgeSystemPrompt({
       prompt: event.prompt,
@@ -176,23 +213,23 @@ export function createTelegramBeforeAgentStartHook(
     });
 }
 
-function stripTelegramToolMetadataFromSystemPrompt(
-  systemPrompt: string,
-): string {
-  const telegramLines = new Set([
-    `- telegram_attach: ${TELEGRAM_ATTACH_PROMPT_SNIPPET}`,
-    `- telegram_message: ${TELEGRAM_MESSAGE_PROMPT_SNIPPET}`,
-    ...TELEGRAM_ATTACH_PROMPT_GUIDELINES.map((line) => `- ${line}`),
-    ...TELEGRAM_MESSAGE_PROMPT_GUIDELINES.map((line) => `- ${line}`),
-  ]);
+function stripTelegramToolMetadataFromString(systemPrompt: string): string {
   return systemPrompt
     .split("\n")
-    .filter((line) => !telegramLines.has(line))
+    .filter((line) => TELEGRAM_TOOL_METADATA_LINES[line] !== true)
     .join("\n");
 }
 
+function stripTelegramToolMetadataFromSystemPrompt(
+  systemPrompt: TelegramSystemPrompt,
+): TelegramSystemPrompt {
+  return Array.isArray(systemPrompt)
+    ? systemPrompt.map(stripTelegramToolMetadataFromString)
+    : stripTelegramToolMetadataFromString(systemPrompt);
+}
+
 export interface TelegramProactivePromptHookDeps<TContext> {
-  baseHook?: (event: BeforeAgentStartEvent) => { systemPrompt: string };
+  baseHook?: TelegramBeforeAgentStartHook;
   reconcileAvailability?: () => void;
   isAvailable: (ctx: TContext) => boolean;
 }
@@ -200,9 +237,9 @@ export interface TelegramProactivePromptHookDeps<TContext> {
 export function createTelegramProactiveBeforeAgentStartHook<TContext>(
   deps: TelegramProactivePromptHookDeps<TContext>,
 ): (
-  event: BeforeAgentStartEvent,
+  event: TelegramBeforeAgentStartEvent,
   ctx: TContext,
-) => Promise<{ systemPrompt: string }> {
+) => Promise<TelegramBeforeAgentStartResult> {
   const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
   return async (event, ctx) => {
     deps.reconcileAvailability?.();

package/node_modules/@llblab/pi-telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.36.1",
+  "version": "0.36.7",
   "private": false,
   "publishConfig": {
     "access": "public"

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generated-control-surface
-description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use on Telegram turns and other prompt-button transports whenever controls materially shorten likely feedback, without requiring an explicit user request; route reusable deterministic loops toward Generative Apps, omit decorative UI, and preserve domain ownership while fixed transport menus and callbacks remain with their runtime owners.
+description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use without an explicit button request on Telegram-originated turns when controls materially shorten likely feedback, or when a user explicitly requests controls on another prompt-button transport; connection or proactive projection alone is not activation intent. Route reusable deterministic loops toward Generative Apps, omit decorative UI, and preserve domain ownership while fixed transport menus and callbacks remain with their runtime owners.
 ---
 
 # Generated Control Surface
@@ -29,7 +29,7 @@ This Skill and `generative-apps` share one logical button-matrix and `label + pr
 
 When a generated surface reveals repeated stable interaction with bounded state and deterministic transitions, load the complementary `generative-apps` Skill and consider compiling that loop. A Generative App may retain ordinary model-mediated prompt buttons beside deterministic bound methods, so only the stable actions need bypass inference. Conversely, keep one-off, interpretive, changing, and context-heavy interaction here when a reusable script would add no concrete latency, token, cost, reliability, or UX value.
 
-On Telegram turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. Load and apply it when a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
+On Telegram-originated turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. A connected Telegram session, available button syntax, or proactive projection of local output is capability evidence, not activation intent: do not load this Skill for an unrelated local/TUI prompt merely because its answer may also appear in Telegram. Load and apply it when the current turn is Telegram-originated or the user explicitly requests a prompt-button surface and a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
 
 A control surface may expose:
 

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/SKILL.md

@@ -7,6 +7,12 @@ description: Operates pi-telegram turns, replies, attachments, direct delivery,
 
 Use pi-telegram as a mobile companion surface for the current Pi session. Preserve the current Telegram target, ordinary reply ownership, durable queue semantics, and the boundary between agent intent and bridge transport.
 
+## Connection Awareness
+
+`Telegram session connected.` means this Pi instance currently has authorized Telegram transport, so Telegram tools and proactive projection may be available. It does not mean the current prompt came from Telegram and does not grant intent to add Telegram actions to unrelated local/TUI work. Use Telegram-specific reply features proactively only on a turn carrying structured Telegram origin; from local/TUI prompts, use them only when the user explicitly requests Telegram delivery or the established workflow is explicitly Telegram-mediated.
+
+`Telegram session disconnected.` revokes that availability. Do not attempt Telegram delivery, actions, buttons, or voice until a later connected context is present. Treat the newest connection-state context as authoritative.
+
 ## Turn Recognition
 
 Telegram-originated prompts carry structured context:
@@ -46,9 +52,9 @@ Use `telegram_attach` outside Telegram turns only when the user explicitly reque
 
 ## Assistant-Authored Actions
 
-Before compiling assistant-authored controls, inspect already-loaded capability guidance for an advertised maintained Generative App or view/controller adapter. When that owner-provided view exists and the current intent concerns repeated interaction, load and follow the bundled `generative-apps` Skill and prefer binding or invoking the existing app over synthesizing one-shot prompt buttons. This is a routing breadcrumb, not permission for the bridge to discover capability-specific apps, own their state, or hard-code their identities.
+Before compiling assistant-authored controls, inspect already-loaded capability guidance for an advertised maintained Generative App or view/controller adapter. When that owner-provided view exists and the current intent concerns repeated interaction, load and follow the bundled `generative-apps` Skill and prefer binding or invoking the existing app over synthesizing one-shot prompt buttons. This routing guidance is not permission for the bridge to discover capability-specific apps, own their state, or hard-code their identities.
 
-Otherwise, on Telegram turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not wait for an explicit button request, and accept zero controls when its admission rules reject decorative or low-value UI.
+Otherwise, only on Telegram-originated turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not activate it merely because Telegram is connected or local output may be projected by proactive push. Do not wait for an explicit button request on a Telegram-originated turn, and accept zero controls when its admission rules reject decorative or low-value UI.
 
 `telegram_button` and `telegram_voice` are hidden top-level HTML comments, not tools. Emit them at column zero, outside lists, quotes, code blocks, and indentation.
 
@@ -116,6 +122,8 @@ Prefer no-code command-template configuration in `telegram.json` before adding a
 - `outboundHandlers` transforms final replies.
 - Voice transcription handlers can match `type: "voice"` or `mime: "audio/*"`; stdout becomes `[outputs]`.
 
+When asked to configure voice rather than merely operate it, follow the provider-neutral contracts in `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect the available Skill catalog and trusted local executables for STT, TTS, and media conversion capabilities; check only whether required environment variables exist, never reveal their values. Preserve unrelated `telegram.json` fields, order multiple matching inbound handlers as fallbacks, require OGG/Opus output for native voice delivery, and validate each stage before a live Telegram smoke test. Keep `voice.replyMode` at its existing value unless the user requests a policy change: the default `hidden` mode is fully functional because explicit top-level `telegram_voice` actions still use the configured synthesis pipeline.
+
 When configuration is insufficient, use documented `@llblab/pi-telegram/*` public API subpaths. Never import package-private `lib/*`, start another polling loop, or bypass bridge ownership with raw Bot API access.
 
 ## Safety

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -41,9 +41,9 @@
   ],
   "dependencies": {
     "@llblab/pi-actors": "0.49.1",
-    "@llblab/pi-codex-usage": "0.9.2",
-    "@llblab/pi-grow-loop": "0.7.1",
-    "@llblab/pi-telegram": "0.36.1"
+    "@llblab/pi-codex-usage": "0.9.3",
+    "@llblab/pi-grow-loop": "0.7.2",
+    "@llblab/pi-telegram": "0.36.7"
   },
   "bundledDependencies": [
     "@llblab/pi-actors",
@@ -63,5 +63,11 @@
       "./node_modules/@llblab/pi-grow-loop/skills",
       "./node_modules/@llblab/pi-telegram/skills"
     ]
-  }
+  },
+  "bundleDependencies": [
+    "@llblab/pi-actors",
+    "@llblab/pi-codex-usage",
+    "@llblab/pi-grow-loop",
+    "@llblab/pi-telegram"
+  ]
 }