@llblab/pi-telegram 0.24.7 → 0.24.9

package/AGENTS.md

@@ -125,7 +125,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - Voice reply mode Settings UI standard: the top-level Settings row is `👄 Voice reply: hidden|mirror|always`; `hidden` is the true default, persists no `voice.replyMode`, adds no voice context, and still allows explicit agent-authored `telegram_voice`; `mirror` activates automatic voice context only for voice/audio input, and `always` activates it for every Telegram turn. The submenu title is `👄 Voice reply mode:`; choice buttons use lowercase labels with a model-style active dot (`🟢 hidden`, `🟢 mirror`) rather than per-mode emoji; the explanatory submenu body uses compact HTML-code bullets such as `<code>-</code> <code>hidden</code> (default): ...`. Preserve this wording/icons unless the operator explicitly asks to redesign it
 - Outbound voice delivery is one fallback pipeline: configured `outboundHandlers` with `type: "voice"` run first in `telegram.json` order, then programmatic voice handlers, then registered voice synthesis providers as zero-config progressive fallbacks; provider extensions must not override operator-configured handlers
 - `telegram_voice` text is arbitrary TTS-target text and the prompt should show only forms that include text to speak: `<!-- telegram_voice text="Short summary" -->` or `<!-- telegram_voice: Short summary -->`. Avoid raw Markdown/code/tables in voice text.
-- `telegram_button` has three canonical forms: `<!-- telegram_button: OK -->` for label-only buttons, `<!-- telegram_button label=Continue prompt="Continue with the current plan." -->` for one-line prompts, or `<!-- telegram_button label="Show risks"\nList the main risks first.\n-->` for multiline prompts. The bridge preserves agent-authored label text and emoji, and owns post-selection state through Telegram's green `success` button style without changing that label. Do not author JSON button specs, inline-after-text comments, standalone button tools, or comments inside code/quotes/lists/indented examples; write normal Markdown plus top-level hidden comments, and add visible parent text when buttons would otherwise be the only output
+- `telegram_button` has three canonical forms: `<!-- telegram_button: OK -->` for label-only buttons, `<!-- telegram_button label=Continue prompt="Continue with the current plan." -->` for one-line prompts, or `<!-- telegram_button label="Show risks"\nList the main risks first.\n-->` for multiline prompts. The bridge preserves agent-authored label text and emoji, and owns post-selection state without changing that label: optional `selected_style="primary|success|danger"` selects blue, green, or red after queue admission, with `primary` as the default, and color never suppresses the prompt. Do not author JSON button specs, inline-after-text comments, standalone button tools, or comments inside code/quotes/lists/indented examples; write normal Markdown plus top-level hidden comments, and let the bridge supply the standard `☑️ **Choose an option:**` Rich Markdown heading when buttons are the only output
 
 ## 6. Engineering Conventions
 

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.24.9: Button-Only Heading Hotfix
+
+- `Prompt Buttons`: The automatic parent text for button-only assistant replies now follows the bridge-owned dialog heading grammar as `☑️ **Choose an option:**`. Impact: fallback button prompts match reasoning, model, and settings choice surfaces with a semantic icon, bold title, and trailing colon instead of appearing as unformatted assistant text.
+
+## 0.24.8: Prompt Button Reliability Hotfix
+
+- `Prompt Buttons`: Button-only assistant replies now receive `Choose an option:` as visible fallback text after hidden markup extraction. Accepted choices use Telegram's blue `primary` style by default; agents may set `selected_style` to `success`, `danger`, or `primary` so quiz-like choices become green, red, or blue while preserving their labels and always queueing the selected prompt. Impact: Telegram can reliably create the keyboard message and retain agent-authored visual feedback instead of silently dropping an empty visible reply or forcing every accepted choice to appear green.
+- `Status`: Threaded Mode identity now renders on a dedicated `Thread: <name> @<role>` row instead of appending `@leader` or `@follower` to the execution status. Impact: `Status` remains an unambiguous `active`/`idle` signal while the current Telegram thread and transport role stay visible separately.
+
 ## 0.24.7: Thread Cleanup Hotfix
 
 - `Thread Cleanup`: Renamed the Telegram Settings control from `Auto thread cleanup` to `Thread cleanup` while preserving `threads.automaticCleanup`. Graceful leader/follower teardown now persists exact generation-fenced cleanup intent before deletion and lets the current or successor leader retry until Telegram confirms removal. If a follower's graceful envelope never arrives, cleanup runs only after stale heartbeat, enabled policy, OS-confirmed death of the exact registered PID, serialized exclusion of replacement registration, an unpublished follower endpoint during durable replay, and cancellation of intents superseded by a current replacement binding. Impact: normal and missed Ctrl-C exits remove only the intended tab without turning heartbeat loss, live/unknown process state, reload, or IPC uncertainty into deletion authority.

package/README.md

@@ -183,7 +183,7 @@ Voice notes, audio, images, PDFs, and other media can pass through configured in
 
 ### Buttons And Callbacks
 
-Assistant replies can include top-level hidden `telegram_button` comments. The bridge strips the comments from visible text, renders inline buttons, and routes callbacks back into Pi as queued prompts or extension-owned callback actions. Once a generated prompt button is accepted, only that exact button switches to Telegram's green success style so the chosen prompt remains visible without altering its agent-authored label or emoji.
+Assistant replies can include top-level hidden `telegram_button` comments. The bridge strips the comments from visible text, renders 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
 

package/api/keyboard.ts

@@ -6,5 +6,6 @@
 
 export type {
   TelegramInlineKeyboardButton,
+  TelegramInlineKeyboardButtonStyle,
   TelegramInlineKeyboardMarkup,
 } from "../lib/keyboard.ts";

package/docs/outbound.md

@@ -147,7 +147,8 @@ Rules:
 - Keep the canonical body form as `<!-- telegram_button label="Label"` + body + `-->`; closed heads must use `prompt="..."` or the colon shorthand to create a button.
 - Use one block per button; this mirrors HTML's singular element model and avoids a nested button DSL inside comments.
 - Button actions are stored in memory with short `callback_data`; Telegram never sees the full prompt in the button payload.
-- After Telegram accepts a generated button callback as a queued prompt, the bridge changes that exact button to Telegram's green `success` style without changing its agent-authored text or emoji. Other choices stay visually unchanged and remain available; the callback acknowledgement remains the fallback on clients that do not render button styles.
+- After Telegram accepts a generated button callback as a queued prompt, the bridge changes that exact button to its configured selection style without changing agent-authored text or emoji. Set `selected_style="primary"` (blue), `selected_style="success"` (green), or `selected_style="danger"` (red); omitted or invalid values fall back to `primary`. The style never suppresses queue admission. Other choices stay visually unchanged and remain available; the callback acknowledgement remains the fallback on clients that do not render button styles.
+- When generated button markup is the entire assistant reply, the bridge supplies the standard `☑️ **Choose an option:**` heading as visible message text so Telegram has a message to which it can attach the inline keyboard.
 
 Do not emit JSON button specs, inline comments after visible text, standalone button actions, or tool calls for ordinary Telegram-turn buttons. The agent writes Markdown plus hidden comments; the bridge strips comments and attaches Telegram `reply_markup` after `agent_end`. For local/TUI-originated direct sends, put the same Markdown and `telegram_button` comments in `telegram_message(text)`.
 
@@ -162,8 +163,8 @@ The extension injects prompt guidance by context:
 - For Telegram-originated turns, the prompt carries only minimal mobile/reply/file guidance; agents can call `telegram_help()` for full voice/button/direct-delivery/Threaded Mode/formatting/debug details.
 - For Telegram-originated turns, write the full technical answer as normal Markdown.
 - Add `telegram_voice` when a Telegram-native voice message is useful; use body text, `text="..."`, or colon shorthand for the text to synthesize. A companion summary is optional, no specific summary format is required.
-- Add `telegram_button: ...` when label equals prompt, `telegram_button label="..." prompt="..."` for one-line prompts, or `telegram_button label="..."` with a body for multiline prompts. If the reply contains only button/voice comment blocks, add a short visible marker (for example `Choose one:`) before them so Telegram always has a visible parent message for attachment.
+- Add `telegram_button: ...` when label equals prompt, `telegram_button label="..." prompt="..."` for one-line prompts, or `telegram_button label="..."` with a body for multiline prompts. Use optional `selected_style="success|danger|primary"` for post-admission color. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
 - For ordinary Telegram-turn replies, do not call transport tools for voice or buttons; the bridge owns delivery, while registered voice synthesis providers own TTS and OGG/Opus conversion. For explicit local/TUI direct sends, `telegram_message` may include top-level `telegram_button` comments in its Markdown text because those buttons are attached to that text message.
-- Never send buttons without visible parent text. If the answer would contain only hidden comments, add a compact line such as `Choose one:` first.
+- Prefer meaningful visible parent text when it adds context; for a button-only answer, rely on the bridge's automatic `☑️ **Choose an option:**` fallback rather than manufacturing duplicate text.
 
 This keeps the agent focused on semantics, prevents Telegram action syntax from leaking into normal local replies, and lets the bridge handle low-latency Telegram adaptation.

package/docs/public-api.md

@@ -336,7 +336,7 @@ Contract:
 - Providers are synchronous because `/start` status text is rendered inline with the menu.
 - Return `undefined` when the line is not relevant for the active model.
 - Provider failures are isolated and skipped so optional companion status cannot break the core Telegram menu.
-- The bridge renders rows as `<Label>: <value>` in the same HTML status block as Status, Usage, Cost, and Context, capitalizing the first label character for Telegram UI consistency.
+- The bridge renders rows as `<Label>: <value>` in the same HTML status block as Status, the optional Threaded Mode `Thread: <name> @<role>` row, Usage, Cost, and Context, capitalizing the first label character for Telegram UI consistency.
 
 ## Updates
 

package/docs/ui-style.md

@@ -50,7 +50,7 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 | `↪️` | Reroute to an existing target | Thread chooser buttons that send a captured command/message from one thread to another live thread | Curved arrow means the message arrived here but bends to another target. |
 | `🔁` | Replace/restore mode | Thread replace/restore chooser entrypoints | Opens a second step for moving a Pi instance binding to the current source thread. |
 | `➡️` | Choose replacement target | Thread replace/restore target buttons that select which Pi instance should move to the current thread | Use inside the second replace/restore chooser, not for ordinary reroutes. |
-| `☑️` | Activate / choose this item | Model detail activation action | Positive action; use `🟢 Active` for already-current state. |
+| `☑️` | Activate / choose this item | Model detail activation action, generated button-only choice heading | Positive selection cue; use `🟢 Active` for already-current state. |
 | `❌` | No / cancel | Confirmation cancel buttons | Use for safe cancellation, not destructive removal. |
 | `🗑` | Delete / remove | Queue delete actions, destructive confirmations, remove reaction | Use only when something is removed/closed/deleted. |
 
@@ -177,7 +177,7 @@ Examples:
 
 ## Generated Prompt Buttons
 
-Assistant-generated prompt buttons use the default app style before selection. After queue admission, edit only the selected button to Telegram's `success` style; preserve its agent-authored text and emoji, and leave other choices at their default style. The callback acknowledgement remains the compatibility fallback when a client does not render button styles.
+A button-only assistant reply uses the standard Rich Markdown heading `☑️ **Choose an option:**`: semantic icon first, one space, bold heading text, and a final colon. Assistant-generated prompt buttons use the default app style before selection. After queue admission, edit only the selected button to its agent-configured `selected_style`: `primary` (default/blue), `success` (green), or `danger` (red). Preserve its agent-authored text and emoji, leave other choices at their default style, and always queue the selected prompt regardless of color. The callback acknowledgement remains the compatibility fallback when a client does not render button styles.
 
 ## Navigation
 

package/lib/keyboard.ts

@@ -4,10 +4,15 @@
  * Owns the shared Bot API reply-markup shape while feature domains own their button semantics
  */
 
+export type TelegramInlineKeyboardButtonStyle =
+  | "danger"
+  | "success"
+  | "primary";
+
 export interface TelegramInlineKeyboardButton {
   text: string;
   callback_data: string;
-  style?: "danger" | "success" | "primary";
+  style?: TelegramInlineKeyboardButtonStyle;
 }
 
 export interface TelegramInlineKeyboardMarkup {

package/lib/outbound-buttons.ts

@@ -6,7 +6,10 @@
 
 import { randomUUID } from "node:crypto";
 
-import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
+import type {
+  TelegramInlineKeyboardButtonStyle,
+  TelegramInlineKeyboardMarkup,
+} from "./keyboard.ts";
 import {
   parseTelegramCommentAttributes,
   parseTopLevelTelegramComment,
@@ -24,6 +27,7 @@ const TELEGRAM_BUTTON_ACTION_TTL_MS = 24 * 60 * 60 * 1000;
 export interface TelegramOutboundButtonAction {
   text: string;
   prompt: string;
+  selectedStyle?: TelegramInlineKeyboardButtonStyle;
 }
 
 export interface TelegramOutboundButtonStoredAction extends TelegramOutboundButtonAction {
@@ -86,11 +90,18 @@ function normalizeMarkdownAfterButtonExtraction(markdown: string): string {
 function parseButtonsCommentAttributes(input: string): {
   label?: string;
   prompt?: string;
+  selectedStyle?: TelegramInlineKeyboardButtonStyle;
 } {
   const attributes = parseTelegramCommentAttributes(input);
+  const selectedStyle = attributes.selected_style;
   return {
     ...(attributes.label ? { label: attributes.label } : {}),
     ...(attributes.prompt ? { prompt: attributes.prompt } : {}),
+    ...(selectedStyle === "success" ||
+    selectedStyle === "danger" ||
+    selectedStyle === "primary"
+      ? { selectedStyle }
+      : {}),
   };
 }
 
@@ -107,14 +118,34 @@ function parseButtonsCommentRows(
     }
     const attributes = parseButtonsCommentAttributes(head);
     return attributes.label && attributes.prompt
-      ? [[{ text: attributes.label, prompt: attributes.prompt }]]
+      ? [
+          [
+            {
+              text: attributes.label,
+              prompt: attributes.prompt,
+              ...(attributes.selectedStyle
+                ? { selectedStyle: attributes.selectedStyle }
+                : {}),
+            },
+          ],
+        ]
       : [];
   }
 
-  const label = parseButtonsCommentAttributes(head).label;
+  const attributes = parseButtonsCommentAttributes(head);
   const prompt = body.trim();
-  if (!label || !prompt) return [];
-  return [[{ text: label, prompt }]];
+  if (!attributes.label || !prompt) return [];
+  return [
+    [
+      {
+        text: attributes.label,
+        prompt,
+        ...(attributes.selectedStyle
+          ? { selectedStyle: attributes.selectedStyle }
+          : {}),
+      },
+    ],
+  ];
 }
 
 export function createTelegramButtonActionStore(
@@ -144,11 +175,20 @@ export function createTelegramButtonActionStore(
       const action = actions.get(callbackData);
       if (!action) return undefined;
       actions.delete(callbackData);
-      return { text: action.text, prompt: action.prompt };
+      return {
+        text: action.text,
+        prompt: action.prompt,
+        ...(action.selectedStyle
+          ? { selectedStyle: action.selectedStyle }
+          : {}),
+      };
     },
   };
 }
 
+const DEFAULT_TELEGRAM_BUTTON_REPLY_MARKDOWN =
+  "☑️ **Choose an option:**";
+
 export function planTelegramButtonReply(
   markdown: string,
   deps: { registerAction: (action: TelegramOutboundButtonAction) => string },
@@ -168,8 +208,12 @@ export function planTelegramButtonReply(
     }
     return "";
   });
+  const visibleMarkdown = normalizeMarkdownAfterButtonExtraction(stripped);
   return {
-    markdown: normalizeMarkdownAfterButtonExtraction(stripped),
+    markdown:
+      keyboard.length > 0 && !visibleMarkdown
+        ? DEFAULT_TELEGRAM_BUTTON_REPLY_MARKDOWN
+        : visibleMarkdown,
     ...(keyboard.length > 0
       ? { replyMarkup: { inline_keyboard: keyboard } }
       : {}),
@@ -212,13 +256,14 @@ export function createTelegramButtonPromptTurn(options: {
 export function markTelegramButtonSelected(
   replyMarkup: TelegramOutboundButtonMarkup,
   callbackData: string,
+  selectedStyle: TelegramInlineKeyboardButtonStyle = "primary",
 ): TelegramOutboundButtonMarkup | undefined {
   let matched = false;
   const inlineKeyboard = replyMarkup.inline_keyboard.map((row) =>
     row.map((button) => {
       if (button.callback_data !== callbackData) return { ...button };
       matched = true;
-      return { ...button, style: "success" as const };
+      return { ...button, style: selectedStyle };
     }),
   );
   return matched ? { inline_keyboard: inlineKeyboard } : undefined;
@@ -253,7 +298,11 @@ export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
   }
   const selectedMarkup =
     query.data && query.message?.reply_markup
-      ? markTelegramButtonSelected(query.message.reply_markup, query.data)
+      ? markTelegramButtonSelected(
+          query.message.reply_markup,
+          query.data,
+          action.selectedStyle,
+        )
       : undefined;
   if (selectedMarkup && deps.editMessageReplyMarkup) {
     await deps.editMessageReplyMarkup(chatId, messageId, selectedMarkup);

package/lib/prompts.ts

@@ -143,8 +143,9 @@ Assistant-authored Telegram actions:
 - Keep voice text TTS-friendly; avoid raw Markdown, code, and tables in voice text.
 - Voice delivery generates and attaches OGG automatically; do not also call \`telegram_attach\` for the same audio.
 - Voice reply modes are compact: \`hidden\` emits no automatic context, \`mirror\` emits it for voice/audio input, and \`always\` emits it for every Telegram turn. Explicit \`telegram_voice\` remains available for an intentionally distinct spoken payload.
-- Button forms: \`<!-- telegram_button: OK -->\`, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\`, or multiline \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\`.
-- If hidden comments would be the whole reply, add visible text such as \`Choose one:\`.
+- Button forms: \`<!-- telegram_button: OK -->\`, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\`, or multiline \`<!-- telegram_button label="Show risks" selected_style="danger"\nList the main risks first.\n-->\`.
+- Optional \`selected_style\` controls the button after queue admission: \`primary\` (default, blue), \`success\` (green), or \`danger\` (red). It never suppresses the prompt.
+- If hidden button comments form the whole reply, the bridge supplies the standard \`☑️ **Choose an option:**\` heading automatically.
 
 Local/TUI direct delivery:
 - Do not send Telegram actions from local/TUI prompts unless explicitly asked.

package/lib/status.ts

@@ -1272,11 +1272,13 @@ function buildStatusSummary(ctx: TelegramStatusContext): string {
   return "unknown";
 }
 
-function buildTelegramStatusRoleSuffix(
+function buildTelegramStatusThreadSummary(
   state: TelegramBridgeStatusLineState | undefined,
-): string {
-  if (state?.botThreadMode !== "enabled" || !state.busRole) return "";
-  return ` @${state.busRole}`;
+): string | undefined {
+  if (state?.botThreadMode !== "enabled" || !state.busRole) return undefined;
+  const threadName = state.instanceThreadName?.trim();
+  const identity = threadName || (state.instanceSlot ? `[${state.instanceSlot}]` : "");
+  return identity ? `${identity} @${state.busRole}` : undefined;
 }
 
 export function buildStatusHtml(
@@ -1288,12 +1290,11 @@ export function buildStatusHtml(
   const usesSubscription = activeModel
     ? ctx.modelRegistry.isUsingOAuth(activeModel)
     : false;
-  const lines: string[] = [
-    buildStatusRow(
-      "Status",
-      `${buildStatusSummary(ctx)}${buildTelegramStatusRoleSuffix(bridgeStatus)}`,
-    ),
-  ];
+  const lines: string[] = [buildStatusRow("Status", buildStatusSummary(ctx))];
+  const threadSummary = buildTelegramStatusThreadSummary(bridgeStatus);
+  if (threadSummary) {
+    lines.push(buildStatusRow("Thread", threadSummary));
+  }
   const usageSummary = buildUsageSummary(stats);
   const costSummary = buildCostSummary(stats, usesSubscription);
   if (usageSummary) {

package/package.json

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