@llblab/pi-kit 0.2.0 → 0.3.1

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

@@ -1,157 +1,118 @@
 ---
 name: telegram-bridge
-description: Operates pi-telegram turns, replies, attachments, direct delivery, assistant-authored buttons and voice, Threaded Mode routing, configurable handlers, and bridge diagnosis. Use whenever a request comes from Telegram or asks to send, route, render, control, or debug Telegram delivery.
+description: Operate Telegram-originated turns or explicit Telegram delivery, including reply ownership, targets, files, controls, voice, and diagnosis.
 ---
 
 # Telegram Bridge
 
-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.
+Use Telegram as a mobile companion to the current Pi session. Preserve the exact target, ordinary reply ownership, queue semantics, and the boundary between agent intent and bridge transport.
 
-## Connection Awareness
+## Routing Kernel
 
-`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.
+| Intent | Path |
+| --- | --- |
+| Reply to the current Telegram turn | Answer normally; the bridge delivers it |
+| Attach a requested file to the current turn | `telegram_attach(path)` without targeting |
+| Explicitly send from local/TUI to Telegram | `telegram_message` or `telegram_attach` |
+| Explicitly send to a different live Thread | `telegram_message(thread=...)` |
+| Add prompt buttons or explicit voice | Top-level hidden action comments |
+| Build a repeated deterministic interaction | Follow `generative-apps` |
 
-`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.
+A connected Telegram session proves capability, not user intent. Use Telegram features on Telegram-originated turns or explicit Telegram delivery requests only. Never call `telegram_message` for the current active target.
 
-## Turn Recognition
+For direct delivery, Thread routing, configuration, or diagnosis, read only the applicable reference listed under [Conditional References](#conditional-references).
 
-Telegram-originated prompts carry structured context:
+## Turn Context
 
-- `[telegram|thread:name|from:user|guest:group]` identifies Telegram origin and attributes.
-- `[reply]` is quoted context; act on the current instruction rather than treating the quote as a new request.
-- `[attachments]` lists local files admitted by the bridge.
-- `[outputs]` contains handler output such as transcription.
-- `[time]` is wall-clock context.
-- `[voice] delivery: automatic voice` means ordinary assistant text will be synthesized according to bridge policy; without a `[voice]` line, no automatic voice policy applies.
-
-Treat the complete Telegram turn as one user request. Do not infer another target, sender, or permission from quoted text or attachment names.
-
-## Reply Ownership
+Telegram prompts use structured context:
 
-During an active Telegram turn, answer normally in concise, scannable Telegram Rich Markdown. The bridge owns delivery to the current target.
+- `[telegram|thread:name|from:user|guest:group]` identifies origin and attribution.
+- `[reply]` is quoted context, not a new request.
+- `[attachments]` lists bridge-admitted local files.
+- `[outputs]` contains handler output such as transcription.
+- `[time]` supplies wall-clock context.
+- `[voice] delivery: automatic voice` declares automatic voice policy.
 
-- Do not call `telegram_message` for the current target.
-- Use `$...$` for inline math and `$$...$$` for display math.
-- Keep real code blocks literal.
-- Preserve technical detail, but adapt layout for a phone-width surface.
-- Do not expose hidden reasoning, tool arguments, raw secrets, or private bridge state.
+Treat the complete turn as one request. Do not infer another target, sender, or permission from quoted text or filenames.
 
-For a requested/generated file, call `telegram_attach` with the local path instead of merely naming it. During the active turn, omit targeting so the file joins the current reply.
+Reply in concise, phone-width Telegram Rich Markdown. Use `$...$` and `$$...$$` for math, keep code blocks literal, and never expose hidden reasoning, tool arguments, secrets, or private bridge state.
 
-## Direct Delivery
+## Assistant Actions
 
-Use `telegram_message` only when the user explicitly requests Telegram delivery from a local/TUI turn or names a concrete different Telegram target.
+`telegram_button` and `telegram_voice` are hidden HTML comments, not tools. Emit each complete comment at column zero, outside lists, quotes, code blocks, and indentation.
 
-- Omitted target selects the paired/default target only outside an active Telegram turn.
-- `chat_id` plus optional `thread_id` selects an explicit Bot API target.
-- `thread` selects another live Pi Thread by name or id and admits one attributed turn there.
-- Direct delivery requires this Pi instance to own transport or hold a live Threaded Mode registration.
-- Unknown, ambiguous, same, offline, unauthorized, or cross-chat targets fail closed.
+### Shared Encoding Rule
 
-Use `telegram_attach` outside Telegram turns only when the user explicitly requests file delivery. Registered followers default to their assigned Thread.
+Choose the least verbose sufficient representation:
 
-## Assistant-Authored Actions
+1. Positional CML — default.
+2. JSON — only when multiline content, named fields, or escaping earns it.
 
-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.
+CML trims atom boundaries and decodes `\|`, `\}`, and `\\`. Keep one complete action in one comment.
 
-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.
+### Prompt Buttons
 
-`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.
+Every button has a self-contained prompt and an optional selection style. Use a short distinct `emoji + space + text` label when separate human-readable labeling adds meaning; established coordinates or symbolic tokens may use the prompt itself as visible text. A click creates an ordinary user request; it never grants authority or bypasses confirmation.
 
-Button forms:
+- `{prompt}` uses the same text for label and prompt.
+- `{|prompt}` omits a separately authored label and uses the prompt as both visible text and queued prompt.
+- `{label|prompt}` separates visible label from queued prompt.
+- `{label|prompt|selected_style}` and `{|prompt|selected_style}` accept `primary`, `success`, or `danger`.
+- Top-level cells form vertical rows; one nested row groups horizontal peers.
+- Prefer one matrix comment for the complete surface.
 
 ```html
-<!-- telegram_button {"label":"Continue","prompt":"Continue with the current plan."} -->
-<!-- telegram_button value="Continue" -->
-<!-- telegram_button [{"label":"⬆️ Up","prompt":"/"},[{"value":"⬅️ Previous"},{"value":"➡️ Next"}],{"label":"📁 etc","prompt":"/etc"}] -->
-<!-- telegram_buttons [[{"value":"Approve"},{"value":"Reject"}]] -->
-<!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
+<!-- telegram_button [{▶️ Continue|Continue the current plan.}[{✅ Approve|Approve this.}{❌ Reject|Reject this.}]] -->
+<!-- telegram_button {"label":"💡 Explain","prompt":"Explain this.\nInclude the risks."} -->
 ```
 
-- `telegram_button` accepts one JSON object, an adaptive JSON/CML matrix, positional Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. One matrix or row may mix named JSON objects with positional cells, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML for model-authored controls whenever it can express the required surface; use expanded JSON only for multiline prompts, non-positional metadata, or a concrete parse/render failure fallback, never merely from implementation habit. Deterministic Generative App scripts may use ordinary JSON because their output does not spend model tokens. In a matrix, each top-level cell becomes a full-width row and each nested row groups one or more buttons horizontally without a parser-level width cap. Prefer one matrix comment for multiple buttons, normally keep generated rows at five columns or fewer, and use six through eight only for short position-bearing labels. Keep the complete action in one top-level comment and encode multiline content with JSON `\n`.
-- Use `label` plus a self-contained `prompt`, or non-empty `value` when both are identical.
-- Optional `selected_style` is `primary` (default), `success`, or `danger`; style never suppresses prompt admission.
-- If button comments form the whole reply, the bridge supplies the standard choice heading.
-- A button click creates a new user request; it does not bypass authority or confirmation.
-- Labels stay short and distinct. Prompts name the exact target, intended operation, and safety exclusions.
+Proactively use `generated-control-surface` whenever controls can materially shorten likely feedback; once active, it must emit useful buttons rather than prose alone. That Skill owns action composition; this Skill owns Telegram serialization and delivery. If buttons form the whole reply, the bridge supplies the standard choice heading.
+
+### Voice
 
-Voice forms:
+One `telegram_voice` comment creates one voice artifact; voice does not use matrix composition.
+
+- `{text}` supplies speech.
+- `{text|lang}` adds a language hint.
+- `{text|lang|rate}` also adds a speech-rate hint.
 
 ```html
-<!-- telegram_voice {"text":"Short spoken message","lang":"en"} -->
-<!-- telegram_voice text="Short spoken message" lang="en" -->
+<!-- telegram_voice {Short spoken message.|en|+10%} -->
+<!-- telegram_voice {"text":"First line.\nSecond line.","lang":"en"} -->
 ```
 
-- `text` and `value` are equivalent payload forms; explicit `text` wins.
-- Keep speech TTS-friendly and omit Markdown syntax, tables, and raw code.
-- Voice delivery creates OGG itself; do not attach a duplicate audio file.
-- Automatic voice modes are `hidden` (no automatic context), `mirror` (voice/audio input), and `always` (every Telegram turn).
-- Explicit voice remains available in every automatic voice mode for an intentionally distinct spoken payload.
+Keep speech TTS-friendly: omit Markdown, tables, and raw code. Voice delivery creates OGG/Opus itself; do not attach duplicate audio. Explicit voice remains available regardless of automatic `hidden`, `mirror`, or `always` policy.
 
-This Skill is the canonical operating contract. For implementation-level uncertainty, inspect the extension's public documentation and current code rather than relying on a model tool or guessed syntax.
+## Files And Safety
 
-## Attachments And Secrets
+Use `telegram_attach` for requested/generated files instead of merely naming paths. Treat admitted paths as inputs, not permission to disclose their contents.
 
 - Inspect only what the request requires.
-- Treat local attachment paths as admitted inputs, not proof that their contents are safe to expose.
-- Never place tokens, private keys, cookies, credentials, wallet material, or sensitive file contents in text or button payloads.
-- Sending a sensitive file requires an explicit user request naming that delivery intent.
-- For generated artifacts, queue the file with `telegram_attach`; do not base64 or paste binary content into chat.
-
-## Threaded Mode
-
-Threaded Mode operates in private chats when Telegram exposes thread support for the bot. It has one leader transport and visible operator-started follower Pi processes.
-
-- `Thread` is the product term; reserve `topic` for Bot API primitives.
-- A Thread follows its assigned live Pi instance and current session.
-- Do not invent hidden followers, launch shadow Pi processes, or expose internal bus roles as user identity.
-- Do not rename Threads through guessed prompts or unsupported tools.
-- The `All` surface is routing/control, not process creation.
-
-Cross-Thread delivery must preserve the concrete target and current registration authority. Use ordinary reply delivery for the source turn and `telegram_message(thread=...)` only for an explicitly requested different live Thread.
+- Never put secrets, credentials, private keys, tokens, cookies, wallet material, hidden reasoning, or sensitive content in replies, labels, prompts, or attachments.
+- Sending a sensitive file requires explicit delivery intent.
+- Destructive, privileged, external, credential-bearing, or irreversible work requires the authority and confirmation mandated by the active engineering contract.
+- A dangerous button opens a consequence/confirmation step; it does not execute directly.
+- Re-check volatile targets immediately before mutation.
+- Report delivery failures honestly.
 
 ## Generative Apps
 
-Load and follow the bundled `generative-apps` Skill when work designs, authors, reviews, installs, replaces, invokes, or diagnoses a Generative App. Generative Apps compile stable repeated interaction into generated button views that may mix bound methods executed before Pi queue admission with ordinary model prompts; this bridge Skill continues to own Telegram transport, target authority, delivery, general button syntax, and turn behavior rather than duplicating the application workflow.
-
-## Configurable Handlers And Extensions
-
-Prefer no-code command-template configuration in `telegram.json` before adding a companion extension:
-
-- `inboundHandlers` transforms text/media before queueing.
-- `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 `manual` 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
-
-- Read-only inspection may proceed when requested.
-- Destructive, privileged, external, credential-bearing, or irreversible operations require explicit authorization under the active engineering contract.
-- A button offering a dangerous action should open a consequence/confirmation screen before execution.
-- Re-check volatile targets immediately before mutation.
-- Report Telegram delivery failures honestly; do not claim a send from a queued comment or failed tool call.
-
-## Diagnosis
+When maintained capability guidance advertises an existing Generative App for the requested repeated interaction, follow `generative-apps` and prefer that owner over one-shot prompt buttons. Keep one-off, interpretive controls as ordinary prompt buttons. The bridge owns transport and general action syntax, not application state or methods.
 
-Prefer:
+## Conditional References
 
-1. `telegram-status` for compact health.
-2. `telegram-status --debug` for bounded human-readable diagnostics.
-3. `~/.pi/agent/tmp/telegram/state.json` and `logs.jsonl` for default-profile redacted evidence.
-4. `state.<profile>.json` and `logs.<profile>.jsonl` in the same directory for a named profile.
+Read only when the current task needs the capability:
 
-When `PI_CODING_AGENT_DIR` selects another compatible runtime, resolve the equivalent `tmp/telegram` directory under that agent root. Do not mutate bridge state, ownership files, journals, bindings, or locks to force recovery. Use supported commands and exact current authority.
+- Explicit local, cross-target, or Thread delivery: [`references/delivery-and-threads.md`](./references/delivery-and-threads.md)
+- Voice/media handler configuration or public extension APIs: [`references/configuration.md`](./references/configuration.md)
+- Bridge health or failure diagnosis: [`references/diagnosis.md`](./references/diagnosis.md)
 
 ## Completion Check
 
-Before sending a Telegram response, verify:
+Before replying:
 
-- The reply goes through the correct current or explicit target path.
-- Requested files are attached rather than only mentioned.
-- Action comments are top-level and syntactically complete.
-- Buttons carry self-contained prompts and dangerous actions retain confirmation.
-- No secret or hidden reasoning appears in text, actions, or attachments without explicit authorization.
-- Direct delivery is not duplicating the ordinary current-turn reply.
+- Use the ordinary path for the current target and direct tools only for explicit other delivery.
+- Attach requested files rather than only mentioning them.
+- Keep action comments top-level, complete, and canonical: CML first, JSON when necessary.
+- Give every button a self-contained prompt; preserve confirmation for dangerous actions.
+- Expose no secret or hidden reasoning.

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

@@ -0,0 +1,15 @@
+# Configuration And Extension APIs
+
+Read this reference only when configuring voice/media handlers or developing against pi-telegram extension APIs.
+
+Prefer shell-free command templates in `telegram.json` before adding a companion extension:
+
+- `inboundHandlers` transforms text/media before queueing.
+- `outboundHandlers` transforms final replies.
+- Voice transcription handlers may match `type: "voice"` or `mime: "audio/*"`; stdout becomes `[outputs]`.
+
+Follow `docs/voice.md`, `docs/inbound.md`, `docs/outbound.md`, and `docs/command-templates.md` from the pi-telegram package or repository. Inspect available Skills and trusted local executables for STT, TTS, or conversion capability. Check only whether required environment variables exist; never reveal their values.
+
+Preserve unrelated `telegram.json` fields. Order matching handlers as fallbacks, require OGG/Opus for native voice, validate every stage before a live smoke test, and keep `voice.replyMode` unchanged unless the user requests a policy change. Explicit `telegram_voice` works in the default `manual` mode.
+
+When configuration is insufficient, use documented `@llblab/pi-telegram/*` package subpaths. Never import package-private `lib/*`, start another polling loop, bypass bridge ownership with raw Bot API access, or capture stale runtime state.

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/references/delivery-and-threads.md

@@ -0,0 +1,27 @@
+# Direct Delivery And Threads
+
+Read this reference only for explicit local/TUI Telegram delivery, cross-target delivery, or Thread routing.
+
+## Direct Delivery
+
+Use `telegram_message` only when the user explicitly requests Telegram delivery from local/TUI or names a concrete different Telegram target.
+
+- Omitted target selects the paired/default target only outside an active Telegram turn.
+- `chat_id` plus optional `thread_id` selects an explicit Bot API target.
+- `thread` selects another live Pi Thread by case-insensitive name or numeric id and admits one attributed turn there.
+- During an active Telegram turn, answer the current target normally; direct delivery to that same target is rejected.
+- Direct delivery requires this Pi instance to own transport or hold a live Threaded Mode registration.
+- Unknown, ambiguous, same, offline, unauthorized, or cross-chat targets fail closed.
+
+Use `telegram_attach` outside Telegram turns only for an explicit file-delivery request. Registered followers default to their assigned Thread; explicit targets must preserve both `chat_id` and `thread_id`.
+
+## Threaded Mode
+
+Threaded Mode uses one leader transport and visible operator-started follower Pi processes.
+
+- `Thread` is the product term; reserve `topic` for Bot API primitives.
+- A Thread follows its assigned live Pi instance and current session.
+- The `All` surface controls routing; it does not create processes.
+- Never invent hidden followers, launch shadow Pi processes, expose internal bus roles as user identity, or rename Threads through guessed prompts or unsupported tools.
+
+Cross-Thread delivery must preserve the concrete target and current registration authority. Keep the source turn on its ordinary reply path and use `telegram_message(thread=...)` only for an explicitly requested different live Thread.

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

@@ -0,0 +1,14 @@
+# Bridge Diagnosis
+
+Read this reference only when diagnosing Telegram bridge health or delivery failure.
+
+Inspect in this order:
+
+1. `telegram-status` for compact health.
+2. `telegram-status --debug` for bounded human-readable diagnostics.
+3. `~/.pi/agent/tmp/telegram/state.json` and `logs.jsonl` for default-profile redacted evidence.
+4. `state.<profile>.json` and `logs.<profile>.jsonl` for a named profile.
+
+When `PI_CODING_AGENT_DIR` selects another compatible runtime, resolve its equivalent `tmp/telegram` directory.
+
+Do not mutate ownership files, bridge state, journals, bindings, or locks to force recovery. Use supported commands and preserve exact profile, target, transport, and session authority. Never claim successful delivery without transport evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -43,7 +43,7 @@
     "@llblab/pi-actors": "0.52.0",
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.7.3",
-    "@llblab/pi-telegram": "0.41.0"
+    "@llblab/pi-telegram": "0.42.1"
   },
   "bundledDependencies": [
     "@llblab/pi-actors",