@llblab/pi-kit 0.3.2 → 0.5.0

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

@@ -155,12 +155,14 @@ I can continue.
 
 Rules:
 
-- The payload may be a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row. Commas are optional between completed elements, and one trailing comma before a closing delimiter is tolerated; JSON object validation likewise tolerates trailing commas but does not invent missing values, property names, or internal separators. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style`; the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`.
+- The payload may be a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row. Commas are optional between completed elements, and one trailing comma before a closing delimiter is tolerated; JSON object validation likewise tolerates trailing commas but does not invent missing values, property names, or internal separators. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style`; the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. A fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling, permitting an empty style atom in this form: `{|Next||1}`. An omitted fourth position stays enabled. JSON uses boolean `disabled`; legacy attributes accept `disabled="true"` or `disabled="false"`. Invalid disabled values reject the candidate matrix atomically. Disabled cells require no prompt or selected style: `{Next|||1}` is label-only and `{|||1}` is blank, equivalent to JSON `{"label":"Next","disabled":true}` and `{"disabled":true}`. They retain their row and label, serialize as `{ text, disabled: {} }` (non-breaking-space text for a blank cell), and register no callback, prompt, or bound app action. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`.
 - Use `label` plus `prompt`, or the compact `value` key when both strings are identical. If only `label`, only `prompt`, one-field `{value}`, or prompt-only `{|prompt}` is present, that string supplies both visible label and queued prompt. An explicit counterpart takes precedence over `value`. Use JSON with `\n` escapes for multiline prompts.
 - The opening marker must start at column zero on a top-level line outside fenced code, quotes, lists, and indented examples; otherwise it does not activate a button action and is still removed from the Telegram surface.
-- Prefer one matrix comment for multiple buttons. Each top-level JSON object or CML cell becomes one full-width inline-keyboard row in source order; a nested row groups one or more buttons horizontally. The parser imposes no artificial per-row width cap; empty rows, malformed cells, unknown/trailing CML escapes, a third unescaped CML separator, empty prompt/style atoms, empty one-atom cells, unknown selected styles, and deeper nesting are rejected atomically. Only the first label position may be empty in a two- or three-atom button cell. Generated surfaces default to five columns and expand to six through eight only for short position-bearing labels. Repeated singular comments remain valid.
+- Prefer one matrix comment for multiple buttons. Each top-level JSON object or CML cell becomes one full-width inline-keyboard row in source order; a nested row groups one or more buttons horizontally. The parser imposes no artificial per-row width cap; empty rows, malformed cells, unknown/trailing CML escapes, a fourth unescaped CML separator, empty enabled-cell prompts or three-atom styles, invalid disabled flags, empty one-atom cells, unknown selected styles, and deeper nesting are rejected atomically. Multi-atom cells may omit the label; four-atom cells may additionally omit the selected style, and disabled cells may omit the prompt. Generated surfaces default to five columns and expand to six through eight only for short position-bearing labels. Repeated singular comments remain valid.
 - 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 its configured selection style without changing agent-authored text or emoji. Set `selected_style` to `primary` (blue), `success` (green), or `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.
+- Standalone column-zero fences opened by exactly three backticks and `telegram_button` use the same singleton/matrix JSON/CML grammar. Complete valid blocks become native `<tg-button-row>` elements in `InputRichMessage.markdown`, at their original positions. Each row supports at most eight buttons and must fit a Rich Message chunk; validation precedes callback registration for the entire block. Labels are escaped, prompts never enter the native markup, and disabled cells have no callback. Missing closures, trailing payload garbage, and invalid blocks produce no controls. Other language names and enclosing code examples stay literal. Draft previews withhold complete and unfinished action fences without registering actions. HTML compatibility projects fenced rows into the bottom keyboard before comment-authored footer rows; source ordering within each group is retained.
+- In-body controls share prompt/app dispatch, TTL, generation/revision checks, and sent-message target ownership with footer controls. Their acknowledgement is the selection feedback; `selected_style` does not recolor the Rich body. No callback-triggered body rewrite is introduced, preventing a stale click from overwriting newer app output. The operator confirmed the post-reload current-client smoke: singleton CML and mixed JSON/CML in-body rows, their ordinary prompt callbacks, a labeled disabled control, and the separate footer callback work as intended. Client type was not recorded. The operator also confirmed that HTML mode projects the in-body groups into the bottom keyboard as intended. Second-client coverage, follower routing, blank cells, and app-method dispatch/revision rejection remain live-gated. Bot API evidence: `InputRichBlockButtons` / Rich Markdown `tg-button-row` and `RichMessageButton` use ordinary `callback_data` and support disabled controls.
+- After Telegram accepts a generated footer 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` to `primary` (blue), `success` (green), or `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 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)`.
@@ -176,7 +178,7 @@ The extension injects prompt guidance by context:
 - For Telegram-originated turns, the compact note routes the agent to `telegram-bridge`, which owns voice/button/direct-delivery/Threaded Mode/formatting/debug guidance.
 - For Telegram-originated turns, write the full technical answer as normal Markdown.
 - Add `telegram_voice` with positional CML by default or JSON when multiline content, named fields, or escaping requires it. A companion summary is optional, no specific summary format is required.
-- Add `telegram_button` with a JSON object, JSON matrix, or positional CML. Prefer one matrix for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` is optional. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
+- Add `telegram_button` with a JSON object, JSON matrix, or positional CML. Use a hidden comment for footer placement or a standalone triple-backtick `telegram_button` block for placement between paragraphs. Prefer one matrix for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` and boolean `disabled` are optional. Keep at least one useful enabled action on an interactive surface. 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.
 - 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.
 

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

@@ -68,7 +68,7 @@ Every assistant-authored HTML comment is transport-private on Telegram: previews
 - `telegram_message(text, chat_id?, thread_id?)` sends a direct Telegram Markdown message when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. During an active Telegram turn, omitted targeting and an explicit target equal to that turn are rejected so the ordinary final-reply path remains the sole current-target response; an explicit different chat/thread target remains allowed for requested cross-target delivery. Outside active turns, paired/default local/TUI delivery remains unchanged. Top-level `telegram_button` comments inside `text` are parsed with the same planner used for normal replies and attached to that message; buttons are never standalone Telegram messages.
 - The bundled `telegram-bridge` Skill owns action syntax, target routing, Threaded Mode, formatting, Generative App operation, and profile-specific debugging guidance. The regular prompt routes applicable turns to that Skill. `telegram_attach`, `telegram_bind`, and `telegram_message` remain registered but are model-active only while this instance owns direct transport or holds a live follower registration; disconnect/loss suppresses their schemas and prompt metadata, and recovery restores only the operator's previously active pi-telegram subset.
 - `telegram_voice` hidden comments request Telegram-native voice delivery through `{text}`, `{text|lang}`, `{text|lang|rate}`, or a JSON object. JSON is the fallback for multiline content, named fields, or escaping; equivalent `text` or `value` supplies the spoken payload, with explicit `text` taking precedence.
-- `telegram_button` hidden comments create inline buttons whose taps enqueue prompts. One marker accepts a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row; separators are optional and one trailing comma is tolerated at matrix, row, and JSON-object boundaries. Top-level cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}`, `{label|prompt}`, prompt-only `{|prompt}`, or the corresponding three-atom form with `selected_style`; an omitted label uses the existing prompt-as-label fallback, and the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. Use top-level column-zero comments outside code, quotes, lists, and indented examples; do not emit standalone button actions.
+- `telegram_button` hidden comments create footer buttons; standalone column-zero triple-backtick `telegram_button` blocks create button rows between paragraphs in Native Rich Markdown. Both accept the same singleton or mixed JSON/CML matrix and share prompt/app routing. Native rows allow at most eight buttons and must fit one Rich Message chunk; invalid or incomplete blocks register nothing. Drafts hide action fences. HTML compatibility projects fenced controls into the footer. In-body clicks acknowledge without recoloring the Rich body; selected-style highlighting remains footer-only. One marker accepts a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row; separators are optional and one trailing comma is tolerated at matrix, row, and JSON-object boundaries. Top-level cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}`, `{label|prompt}`, prompt-only `{|prompt}`, or the corresponding three-atom form with `selected_style`; an omitted label uses the existing prompt-as-label fallback, and the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. A fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling; an omitted fourth position stays enabled, and the third atom may be empty in this form (`{|Next||1}`). JSON uses boolean `disabled`. Disabled cells need no prompt or selected style: `{Next|||1}` is label-only and `{|||1}` is blank (JSON `{"label":"Next","disabled":true}` and `{"disabled":true}`). The Telegram renderer supplies a non-breaking space only when the label is empty. Disabled cells stay visible but carry `disabled: {}` instead of callback data and register no prompt or bound action; invalid disabled values reject the candidate matrix. It trims atom boundaries and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. Use top-level column-zero action wrappers, outside quotes, lists, or enclosing code examples. Ordinary code fences and larger outer fences preserve literal examples; bare JSON/CML in prose never activates.
 
 Prompt guidance is context-aware: local/TUI prompts see only explicit direct-delivery guidance, while Telegram-originated turns receive the full action-comment syntax and phone-width output contract.
 

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

@@ -245,7 +245,10 @@ export default function (pi: Pi.ExtensionAPI) {
     Config.createTelegramProactivePushChatIdGetter(proactivePushTargetGetter);
   const buttonActionStore = Outbound.createTelegramButtonActionStore();
   const planGenerativeAppOutput =
-    Outbound.createTelegramOutboundReplyPlanner(buttonActionStore);
+    Outbound.createTelegramOutboundReplyPlanner(
+      buttonActionStore,
+      configControls.getAssistantRenderingMode,
+    );
   const pendingModelSwitchStore =
     Model.createPendingModelSwitchStore<
       Model.ScopedTelegramModel<ActivePiModel>
@@ -400,6 +403,15 @@ export default function (pi: Pi.ExtensionAPI) {
     TelegramApi.createDefaultTelegramBridgeApiRuntime({
       getBotToken: configStore.getBotToken,
       recordRuntimeEvent,
+      captureRequestErrorHandler(body) {
+        return Sync.captureTelegramStaleTargetRequestRecovery(body, {
+          ...staleTopicApiErrorRecoveryDeps,
+          getCurrentLeaderEpoch,
+          getSessionGeneration: telegramSessionContextStore.getGeneration,
+          getProfileName: configStore.getActiveProfileName,
+          onRecovered: runtimeDiagnostics.scheduleSnapshotPersist,
+        });
+      },
     });
   const telegramBusFollowerClients =
     BusFollower.createTelegramBusFollowerClientRuntime<

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

@@ -518,7 +518,10 @@ export function registerTelegramCommandsAndTools({
   GenerativeApps.registerTelegramBindTool(pi, {
     agentDir,
     getActiveTurn: activeTurnRuntime.get,
-    planOutput: OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
+    planOutput: OutboundHandlers.createTelegramOutboundReplyPlanner(
+      buttonActionStore,
+      Config.createTelegramConfigControls(configStore).getAssistantRenderingMode,
+    ),
     sendMarkdownReply,
     recordRuntimeEvent,
   });
@@ -538,7 +541,10 @@ export function registerTelegramCommandsAndTools({
     routeAgentMessage,
     canSendDirect,
     planMessage:
-      OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
+      OutboundHandlers.createTelegramOutboundReplyPlanner(
+        buttonActionStore,
+        Config.createTelegramConfigControls(configStore).getAssistantRenderingMode,
+      ),
     sendMarkdownMessage: (chatId, markdown, options) =>
       sendMarkdownReply(chatId, undefined, markdown, options),
     recordRuntimeEvent,
@@ -854,7 +860,10 @@ export function registerTelegramLifecycleRuntimeHooks({
     });
   };
   const outboundReplyPlanner =
-    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
+    OutboundHandlers.createTelegramOutboundReplyPlanner(
+      buttonActionStore,
+      getAssistantRenderingMode,
+    );
   const voiceReplySenderDeps = {
     execCommand: CommandTemplates.execCommandTemplate,
     sendMultipart: callMultipart,

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

@@ -390,9 +390,8 @@ export interface TelegramBusFollowerTargetReplacementHandlerDeps<TContext> {
   >;
   registrationState: Pick<
     TelegramBusFollowerRegistrationState,
-    "getTarget" | "setRegistered"
-  > &
-    Partial<Pick<TelegramBusFollowerRegistrationState, "getGeneration">>;
+    "getTarget" | "setRegistered" | "getGeneration"
+  >;
   instanceId: string;
   getManualFollowerProfileKey: () => string;
   manualFollowerOwnerId: string;
@@ -471,6 +470,7 @@ export interface TelegramBusForwardedUpdateReceiverRuntimeDeps<TContext> {
       target: TelegramTarget & { threadId: number };
       oldTarget?: TelegramTarget & { threadId: number };
       reason: "thread-restore";
+      registrationGeneration: string;
     },
     ctx: TContext,
   ) => Promise<void> | void;
@@ -569,26 +569,35 @@ export function createTelegramBusFollowerTargetReplacementHandler<TContext>(
 > {
   const getNowMs = deps.getNowMs ?? Date.now;
   return async (input, ctx) => {
+    const assertCurrent = (expectedTarget = input.oldTarget): void => {
+      const target = deps.registrationState.getTarget();
+      if (!input.registrationGeneration ||
+        deps.registrationState.getGeneration() !== input.registrationGeneration ||
+        !input.oldTarget || !expectedTarget || target?.chatId !== expectedTarget.chatId ||
+        target.threadId !== expectedTarget.threadId ||
+        input.target.chatId !== input.oldTarget.chatId ||
+        input.target.threadId === input.oldTarget.threadId) {
+        throw new Error("Stale Telegram follower target replacement authority.");
+      }
+    };
+    assertCurrent();
     await deps.topicTargetStore.load();
+    assertCurrent();
     const nowMs = getNowMs();
     const currentRecord = Threads.findCurrentTelegramInstanceThreadRecord({
       records: deps.topicTargetStore.list(),
       instanceId: deps.instanceId,
-      preferredTarget: input.oldTarget ?? deps.registrationState.getTarget(),
+      preferredTarget: input.oldTarget,
     });
-    if (input.oldTarget) {
-      deps.topicTargetStore.markStaleByTarget(
-        input.oldTarget,
-        "deleted",
-        "Follower thread was replaced by thread restore.",
-      );
-    } else if (currentRecord) {
-      deps.topicTargetStore.markStaleByTarget(
-        currentRecord.target,
-        "deleted",
-        "Follower thread was replaced by thread restore.",
-      );
+    if (currentRecord && (currentRecord.target.chatId !== input.oldTarget!.chatId ||
+      currentRecord.target.threadId !== input.oldTarget!.threadId)) {
+      throw new Error("Stale Telegram follower binding replacement target.");
     }
+    deps.topicTargetStore.markStaleByTarget(
+      input.oldTarget!,
+      "deleted",
+      "Follower thread was replaced by thread restore.",
+    );
     const profileKey =
       currentRecord?.profileKey ?? deps.getManualFollowerProfileKey();
     deps.topicTargetStore.upsert({
@@ -612,15 +621,16 @@ export function createTelegramBusFollowerTargetReplacementHandler<TContext>(
     deps.registrationState.setRegistered(true, input.target, {
       slot: currentRecord?.slot,
       threadName: currentRecord?.threadName,
-      generation: deps.registrationState.getGeneration?.(),
+      generation: input.registrationGeneration,
     });
+    await deps.topicTargetStore.persist();
+    assertCurrent(input.target);
     deps.setSyncState(
       Sync.markTelegramSyncSliceFresh(deps.getSyncState(), "target-bindings", {
         nowMs,
         action: "follower-thread-restore",
       }),
     );
-    await deps.topicTargetStore.persist();
     deps.updateStatus(ctx);
     deps.recordRuntimeEvent?.(
       "bus",
@@ -1992,6 +2002,7 @@ export function createTelegramBusForwardedUpdateReceiverRuntime<TContext>(
               target: envelope.target,
               ...(envelope.oldTarget ? { oldTarget: envelope.oldTarget } : {}),
               reason: envelope.reason,
+              registrationGeneration,
             },
             ctx,
           );

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

@@ -135,6 +135,7 @@ export interface TelegramBusFollowerTargetProvisionerDeps {
 export interface TelegramBusFollowerDisconnectHandlerDeps {
   topicTargetStore: Pick<
     Threads.TelegramTopicTargetStore,
+    | "list"
     | "markStaleByTarget"
     | "persist"
     | "upsertPendingCleanup"
@@ -726,6 +727,7 @@ export function createTelegramBusFollowerTargetProvisioner(
               ],
             }),
             {
+              isCleanupTargetProtected: Threads.createTelegramCleanupTargetProtection(deps.topicTargetStore),
               callApi: deps.callApi,
               markStaleByTarget(target, syncStatus, lastSyncError) {
                 return deps.topicTargetStore.markStaleByTarget(
@@ -805,16 +807,21 @@ function createTelegramBusFollowerCleanupHandler(
       target: { chatId: target.chatId, threadId: target.threadId },
       requestedAtMs: (deps.getNowMs ?? Date.now)(),
     };
+    const departingRecord = deps.topicTargetStore.list().find((record) => record.instanceId === follower.instanceId &&
+      record.target.chatId === target.chatId && record.target.threadId === target.threadId);
+    const isCleanupTargetProtected = Threads.createTelegramCleanupTargetProtection(deps.topicTargetStore, departingRecord);
     deps.topicTargetStore.upsertPendingCleanup(intent);
     await deps.topicTargetStore.persist();
+    const cleanupPlan = ThreadReconciler.planThreadReconciliation({
+      nowMs: (deps.getNowMs ?? Date.now)(),
+      currentLeaderEpoch: leaderEpoch,
+      records: [],
+      pendingCleanups: [intent],
+    });
     const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
-      ThreadReconciler.planThreadReconciliation({
-        nowMs: (deps.getNowMs ?? Date.now)(),
-        currentLeaderEpoch: leaderEpoch,
-        records: [],
-        pendingCleanups: [intent],
-      }),
+      cleanupPlan,
       {
+        isCleanupTargetProtected,
         callApi: deps.callApi,
         markStaleByTarget: deps.topicTargetStore.markStaleByTarget,
         removeCleanupIntentById: deps.topicTargetStore.removePendingCleanup,
@@ -823,6 +830,7 @@ function createTelegramBusFollowerCleanupHandler(
         recordRuntimeEvent: deps.recordRuntimeEvent,
       },
     );
+    if (cleanupPlan.actions.some((action) => isCleanupTargetProtected(action.target, action))) return;
     if (cleanup.incompleteActions?.length) {
       throw new Error(
         "Telegram follower thread deletion was not confirmed; reconnect the leader to retry cleanup.",
@@ -916,6 +924,7 @@ export function createTelegramBusLeaderTargetProvisioner<TContext>(
     });
     deps.recordThreadReconciliationPlan?.(pendingCleanupPlan);
     const cleanupPorts = {
+      isCleanupTargetProtected: Threads.createTelegramCleanupTargetProtection(deps.topicTargetStore),
       callApi: deps.callApi,
       markStaleByTarget: deps.topicTargetStore.markStaleByTarget,
       removeCleanupIntentById: deps.topicTargetStore.removePendingCleanup,

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

@@ -1450,18 +1450,25 @@ export function createTelegramBusFollowerThreadRestoreHandler(
   return async ({ record, target, oldTarget }) => {
     if (!record.instanceId) return false;
     const follower = deps.followerRegistry.get(record.instanceId);
-    if (!follower) return false;
+    if (!follower?.registrationGeneration || !oldTarget ||
+      follower.target?.chatId !== oldTarget.chatId ||
+      follower.target.threadId !== oldTarget.threadId ||
+      target.chatId !== oldTarget.chatId || target.threadId === oldTarget.threadId) return false;
     const replaced = await deps.followerTargetController.replaceTarget({
       follower,
       target,
       oldTarget,
       reason: "thread-restore",
     });
-    if (!replaced) return false;
+    const current = deps.followerRegistry.get(record.instanceId);
+    if (!replaced || !current ||
+      current.registrationGeneration !== follower.registrationGeneration ||
+      current.target?.chatId !== oldTarget.chatId ||
+      current.target.threadId !== oldTarget.threadId) return false;
     deps.followerRegistry.register({
-      ...follower,
+      ...current,
       target,
-      connectedAtMs: follower.connectedAtMs,
+      connectedAtMs: current.connectedAtMs,
     });
     deps.onRestored?.();
     return true;

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

@@ -9,11 +9,13 @@ export type TelegramInlineKeyboardButtonStyle =
   | "success"
   | "primary";
 
-export interface TelegramInlineKeyboardButton {
+export type TelegramInlineKeyboardButton = {
   text: string;
-  callback_data: string;
   style?: TelegramInlineKeyboardButtonStyle;
-}
+} & (
+  | { callback_data: string; disabled?: never }
+  | { disabled: Record<string, never>; callback_data?: never }
+);
 
 export interface TelegramInlineKeyboardMarkup {
   inline_keyboard: TelegramInlineKeyboardButton[][];

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

@@ -12,6 +12,8 @@ import type {
 } from "./keyboard.ts";
 import {
   parseTelegramActionPayloadRows,
+  parseTelegramButtonPayloadRows,
+  replaceTelegramButtonFences,
   replaceTopLevelHtmlComments,
 } from "./outbound-markup.ts";
 import {
@@ -34,6 +36,7 @@ export interface TelegramOutboundButtonAction {
   prompt: string;
   binding?: TelegramOutboundButtonBinding;
   selectedStyle?: TelegramInlineKeyboardButtonStyle;
+  disabled?: true;
 }
 
 export interface TelegramOutboundButtonStoredAction extends TelegramOutboundButtonAction {
@@ -115,6 +118,12 @@ function parseTelegramButtonAction(
   const explicitLabel = getTelegramButtonString(payload, "label");
   const explicitPrompt = getTelegramButtonString(payload, "prompt");
   const label = explicitLabel ?? value ?? explicitPrompt;
+  if (payload.disabled !== undefined && typeof payload.disabled !== "boolean") {
+    return undefined;
+  }
+  if (payload.disabled === true) {
+    return { text: label ?? "", prompt: "", disabled: true };
+  }
   const prompt = explicitPrompt ?? value ?? explicitLabel;
   if (!label || !prompt) return undefined;
   const selectedStyle = payload.selected_style;
@@ -159,6 +168,7 @@ export function createTelegramButtonActionStore(
       return {
         text: action.text,
         prompt: action.prompt,
+        ...(action.disabled ? { disabled: true as const } : {}),
         ...(action.binding ? { binding: action.binding } : {}),
         ...(action.selectedStyle
           ? { selectedStyle: action.selectedStyle }
@@ -171,33 +181,75 @@ export function createTelegramButtonActionStore(
 const DEFAULT_TELEGRAM_BUTTON_REPLY_MARKDOWN =
   "☑️ **Choose an option:**";
 
+function escapeTelegramRichButtonText(text: string): string {
+  return text.replace(/[&<>"'`\\*_\[\]{}$~\r\n]/g, (character) =>
+    `&#${character.charCodeAt(0)};`,
+  );
+}
+
+function renderTelegramRichButtonRow(
+  row: TelegramOutboundButtonMarkup["inline_keyboard"][number],
+): string {
+  return `<tg-button-row>${row.map((button) => {
+    const attributes = button.disabled
+      ? 'type="disabled"'
+      : `type="callback_data" data="${escapeTelegramRichButtonText(button.callback_data)}"`;
+    return `<tg-button ${attributes}>${escapeTelegramRichButtonText(button.text)}</tg-button>`;
+  }).join("")}</tg-button-row>`;
+}
+
 export function planTelegramButtonReply(
   markdown: string,
   deps: {
     registerAction: (action: TelegramOutboundButtonAction) => string;
     binding?: TelegramOutboundButtonBinding;
+    rendering?: "rich" | "html";
   },
 ): TelegramButtonReplyPlan {
   const keyboard: TelegramOutboundButtonMarkup["inline_keyboard"] = [];
-  const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
+  const buildRows = (
+    payloadRows: Record<string, unknown>[][],
+    rich: boolean,
+  ): TelegramOutboundButtonMarkup["inline_keyboard"] | undefined => {
+    const actions = payloadRows.map((row) => row.map(parseTelegramButtonAction));
+    if (actions.some((row) => row.some((action) => !action))) return undefined;
+    if (rich && actions.some((row) => {
+      const projected = row.map((action) => action!.disabled
+        ? { text: action!.text || "\u00a0", disabled: {} }
+        : { text: action!.text, callback_data: "x".repeat(64) });
+      return row.length > 8 || renderTelegramRichButtonRow(projected).length > 32768;
+    })) return undefined;
+    return actions.map((row) => row.map((action) => action!.disabled
+      ? { text: action!.text || "\u00a0", disabled: {} }
+      : {
+          text: action!.text,
+          callback_data: deps.registerAction({
+            ...action!,
+            ...(deps.binding ? { binding: deps.binding } : {}),
+          }),
+        }));
+  };
+  const withRichButtons = replaceTelegramButtonFences(markdown, (payload, closed) => {
+    if (!closed) return "";
+    const payloadRows = parseTelegramButtonPayloadRows(payload);
+    if (!payloadRows) return "";
+    const rich = deps.rendering !== "html";
+    const rows = buildRows(payloadRows, rich);
+    if (!rows) return "";
+    if (!rich) {
+      keyboard.push(...rows);
+      return "";
+    }
+    return `\n${rows.map(renderTelegramRichButtonRow).join("\n\n")}\n`;
+  });
+  const stripped = replaceTopLevelHtmlComments(withRichButtons, (comment) => {
     const command = "telegram_button";
     const normalizedContent = comment.content.replace(/^\s+/, "").replace(/^!/, "");
     if (!normalizedContent.startsWith(command)) return comment.raw;
     const payloadRows = parseTelegramActionPayloadRows(comment, command);
     if (!payloadRows) return "";
-    const actionRows = payloadRows.map((payloadRow) =>
-      payloadRow.map(parseTelegramButtonAction),
-    );
-    if (actionRows.some((row) => row.some((action) => !action))) return "";
-    for (const actionRow of actionRows) {
-      keyboard.push(actionRow.map((action) => ({
-        text: action!.text,
-        callback_data: deps.registerAction({
-          ...action!,
-          ...(deps.binding ? { binding: deps.binding } : {}),
-        }),
-      })));
-    }
+    const rows = buildRows(payloadRows, false);
+    if (rows) keyboard.push(...rows);
     return "";
   });
   const visibleMarkdown = normalizeMarkdownAfterButtonExtraction(stripped);
@@ -254,7 +306,7 @@ export function markTelegramButtonSelected(
   let matched = false;
   const inlineKeyboard = replyMarkup.inline_keyboard.map((row) =>
     row.map((button) => {
-      if (button.callback_data !== callbackData) return { ...button };
+      if (button.disabled || button.callback_data !== callbackData) return { ...button };
       matched = true;
       return { ...button, style: selectedStyle };
     }),
@@ -277,6 +329,11 @@ export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
     return false;
   }
 
+  if (action.disabled) {
+    await deps.answerCallbackQuery(query.id, "Button action unavailable.");
+    return true;
+  }
+
   const chatId = query.message?.chat?.id;
   const messageId = query.message?.message_id;
   if (typeof chatId !== "number" || typeof messageId !== "number") {

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

@@ -90,6 +90,50 @@ export function collectTopLevelHtmlComments(markdown: string): {
   return { comments };
 }
 
+export function replaceTelegramButtonFences(
+  markdown: string,
+  replace: (payload: string, closed: boolean) => string,
+): string {
+  let result = "";
+  let copied = 0;
+  let offset = 0;
+  let fence: TelegramTopLevelFenceState | undefined;
+  let actionStart: number | undefined;
+  let contentStart = 0;
+  while (offset < markdown.length) {
+    const end = getMarkdownLineEnd(markdown, offset);
+    const line = getMarkdownLineText(markdown, offset, end);
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) {
+        if (actionStart !== undefined) {
+          result += markdown.slice(copied, actionStart);
+          result += replace(markdown.slice(contentStart, offset), true) + "\n";
+          copied = end;
+          actionStart = undefined;
+        }
+        fence = undefined;
+      }
+    } else if (line.includes("<!--")) {
+      const close = markdown.indexOf("-->", offset + line.indexOf("<!--") + 4);
+      if (close < 0) break;
+      offset = getMarkdownLineEnd(markdown, close + 3);
+      continue;
+    } else {
+      fence = getTopLevelOpeningFence(line);
+      if (fence && /^```telegram_button[ \t]*$/.test(line)) {
+        actionStart = offset;
+        contentStart = end;
+      }
+    }
+    offset = end;
+  }
+  if (actionStart !== undefined) {
+    result += markdown.slice(copied, actionStart);
+    return result + replace(markdown.slice(contentStart), false);
+  }
+  return result + markdown.slice(copied);
+}
+
 export function replaceTopLevelHtmlComments(
   markdown: string,
   replacer: (comment: TelegramTopLevelHtmlComment) => string,
@@ -275,17 +319,26 @@ type TelegramCompactActionPayloadParser = (
 function parseTelegramButtonCompactActionPayload(
   atoms: readonly string[],
 ): Record<string, unknown> | undefined {
-  const [label, prompt, selectedStyle] = atoms;
+  const [label, prompt, selectedStyle, disabled] = atoms;
   if (atoms.length === 1) return label ? { value: label } : undefined;
-  if (!prompt) return undefined;
+  const isDisabled = disabled === "1" || disabled === "true";
+  if (!prompt && !(atoms.length === 4 && isDisabled)) return undefined;
   const action = label ? { label, prompt } : { prompt };
   if (atoms.length === 2) return action;
   if (
     selectedStyle !== "primary" &&
     selectedStyle !== "success" &&
-    selectedStyle !== "danger"
+    selectedStyle !== "danger" &&
+    !(atoms.length === 4 && selectedStyle === "")
   ) return undefined;
-  return { ...action, selected_style: selectedStyle };
+  if (atoms.length === 4 && !isDisabled && disabled !== "0" && disabled !== "false") {
+    return undefined;
+  }
+  return {
+    ...action,
+    ...(selectedStyle ? { selected_style: selectedStyle } : {}),
+    ...(atoms.length === 4 ? { disabled: isDisabled } : {}),
+  };
 }
 
 function parseTelegramVoiceCompactActionPayload(
@@ -303,7 +356,7 @@ function parseTelegramVoiceCompactActionPayload(
 function parseTelegramAdaptiveActionPayloadRows(
   source: string,
   parseCompactPayload: TelegramCompactActionPayloadParser,
-  options: { allowTrailing?: boolean } = {},
+  options: { allowTrailing?: boolean; maxCompactAtoms?: number } = {},
 ): { rows: Record<string, unknown>[][]; end: number } | undefined {
   let offset = 0;
   const isStructuralWhitespace = (character: string | undefined): boolean =>
@@ -343,7 +396,7 @@ function parseTelegramAdaptiveActionPayloadRows(
         continue;
       }
       if (character === "|") {
-        if (atomSources.length >= 3) return undefined;
+        if (atomSources.length >= (options.maxCompactAtoms ?? 3)) return undefined;
         atomSources.push([]);
         offset += 1;
         continue;
@@ -509,6 +562,16 @@ function isPlausibleTelegramMatrixStart(
   );
 }
 
+export function parseTelegramButtonPayloadRows(
+  source: string,
+): Record<string, unknown>[][] | undefined {
+  return parseTelegramAdaptiveActionPayloadRows(
+    source.trim(),
+    parseTelegramButtonCompactActionPayload,
+    { maxCompactAtoms: 4 },
+  )?.rows;
+}
+
 export function parseTelegramActionPayloadRows(
   comment: TelegramTopLevelHtmlComment,
   command: string,
@@ -533,7 +596,7 @@ export function parseTelegramActionPayloadRows(
     const parsed = parseTelegramAdaptiveActionPayloadRows(
       content.slice(offset),
       parseTelegramButtonCompactActionPayload,
-      { allowTrailing: true },
+      { allowTrailing: true, maxCompactAtoms: 4 },
     );
     if (parsed) return parsed.rows;
     const end = findTelegramStructuredPayloadEnd(content, offset);
@@ -546,8 +609,15 @@ export function parseTelegramActionPayloadRows(
     "prompt",
     "value",
     "selected_style",
+    "disabled",
   ]);
-  return attributes ? [[attributes]] : undefined;
+  if (!attributes) return undefined;
+  return [[{
+    ...attributes,
+    ...(attributes.disabled === "true" || attributes.disabled === "false"
+      ? { disabled: attributes.disabled === "true" }
+      : {}),
+  }]];
 }
 
 export function normalizeMarkdownAfterVoiceExtraction(
@@ -589,7 +659,9 @@ function stripTelegramHtmlCommentBlocks(markdown: string): string {
 }
 
 export function stripTelegramCommentMarkupForPreview(markdown: string): string {
-  const withoutClosedBlocks = stripTelegramHtmlCommentBlocks(markdown);
+  const withoutClosedBlocks = stripTelegramHtmlCommentBlocks(
+    replaceTelegramButtonFences(markdown, () => ""),
+  );
   const openBlockIndex =
     findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
   const previewMarkdown =

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

@@ -835,6 +835,7 @@ export {
 
 export function createTelegramOutboundReplyPlanner(
   store: Pick<TelegramButtonActionStore, "register">,
+  getRenderingMode: () => "rich" | "html" = () => "rich",
 ): (
   markdown: string,
   options?: { binding?: TelegramOutboundButtonBinding },
@@ -842,6 +843,7 @@ export function createTelegramOutboundReplyPlanner(
   return (markdown, options) => {
     const buttonReply = planTelegramButtonReply(markdown, {
       registerAction: store.register,
+      rendering: getRenderingMode(),
       ...(options?.binding ? { binding: options.binding } : {}),
     });
 

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

@@ -532,7 +532,7 @@ function splitTelegramNativeMarkdownCountedBlocks(block: string): string[] {
 function countTelegramNativeMarkdownBlocks(block: string): number {
   if (/^ {0,3}(`{3,}|~{3,})/.test(block)) return 1;
   const lines = block.split("\n").filter((line) => line.trim().length > 0);
-  if (lines.some((line) => /^\s*([-*+] |\d+\. |>|\|)/.test(line))) {
+  if (lines.some((line) => /^\s*([-*+] |\d+\. |>|\||<tg-button-row>)/.test(line))) {
     return Math.max(1, lines.length);
   }
   return 1;