@llblab/pi-telegram 0.36.8 → 0.36.10

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.36.10: Transport-Fenced Typing Hotfix
+
+- `Typing Authority Fence`: Starts and continues Telegram typing activity only while the Pi instance has direct ownership or a live follower registration, stopping quietly when authority disappears so classic takeover cannot re-arm a stale loop or flood diagnostics with expected follower-registration errors.
+
+## 0.36.9: Telegram Status And Generated Controls Hotfix
+
+- `Classic Takeover Status`: Keeps a classic-mode client visibly `disconnected` after another Pi instance takes Telegram ownership, preventing stale transport-side activity errors from overriding the authoritative connection state.
+- `Generated Button Surfaces`: Makes vertical full-width controls the phone-readable default, earns multi-column rows only for compact labels or emoji-only spatial controls, encourages concise semantic labels, and requires safe 2–6 button controls whenever a Telegram reply asks a bounded blocking confirmation or choice instead of leaving an avoidable prose-only feedback step.
+
 ## 0.36.8: Durable Journal Recovery
 
 - `Durable Journal Recovery`: Restricts age cleanup to UUID-prefixed downloads, repairs missing or revisionless snapshots from validated segment evidence, and otherwise quarantines the snapshot plus segments before publishing a fresh journal, keeping `/telegram-connect` operational with informational recovery evidence instead of manual JSON repair.

package/index.ts

@@ -465,6 +465,15 @@ export default function (pi: Pi.ExtensionAPI) {
       BusApi.createTelegramAggregateTypingActionSender(telegramApiRuntime),
     updateStatus,
     isContextActive: telegramSessionContextStore.isCurrent,
+    getTransportAuthority() {
+      if (ownsTelegramDirectDelivery()) {
+        const epoch = getCurrentLeaderEpoch();
+        return epoch === undefined ? undefined : `direct:${epoch}`;
+      }
+      if (!telegramBusFollowerRegistrationState.isRegistered()) return undefined;
+      const generation = telegramBusFollowerRegistrationState.getGeneration();
+      return generation ? `follower:${generation}` : undefined;
+    },
     recordRuntimeEvent,
   });
   const currentModelRuntime = Model.createCurrentModelRuntime({

package/lib/runtime.ts

@@ -320,6 +320,8 @@ export interface TelegramTypingLoopDeps {
     options?: { message_thread_id?: number },
   ) => Promise<unknown>;
   sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
+  shouldContinue?: () => boolean;
+  onStopped?: () => void;
 }
 
 export interface TelegramRuntimeEventRecorderPort {
@@ -365,6 +367,8 @@ export interface TelegramTypingLoopStarterDeps<
   sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   isContextActive?: (ctx: TContext) => boolean;
+  isTransportAvailable?: () => boolean;
+  getTransportAuthority?: () => string | number | undefined;
   intervalMs?: number;
 }
 
@@ -376,15 +380,33 @@ export function createTelegramTypingLoopStarter<TContext>(
   options?: { target?: TelegramTypingLoopTarget },
 ) => void {
   return (ctx, chatId, options) => {
+    const transportAuthority = deps.getTransportAuthority?.();
+    const hasTransport = (): boolean =>
+      deps.getTransportAuthority
+        ? transportAuthority !== undefined &&
+          Object.is(deps.getTransportAuthority(), transportAuthority)
+        : deps.isTransportAvailable?.() !== false;
+    if (!hasTransport()) return;
+    let active = true;
     deps.typing.start({
       chatId: chatId ?? deps.getDefaultChatId(),
       target: options?.target,
       intervalMs: deps.intervalMs ?? TELEGRAM_TYPING_ACTION_INTERVAL_MS,
       sendTypingAction: async (targetChatId, actionOptions) => {
+        if (!active) return;
+        if (!hasTransport()) {
+          deps.typing.stop();
+          return;
+        }
         try {
           await deps.sendTypingAction(targetChatId, actionOptions);
         } catch (error) {
           if (deps.isContextActive?.(ctx) === false) return;
+          if (!active) return;
+          if (!hasTransport()) {
+            deps.typing.stop();
+            return;
+          }
           const message =
             error instanceof Error ? error.message : String(error);
           updateTelegramRuntimeStatusSafely(deps.updateStatus, ctx, {
@@ -404,10 +426,20 @@ export function createTelegramTypingLoopStarter<TContext>(
       },
       sendAggregateTypingAction: deps.sendAggregateTypingAction
         ? async (targetChatId) => {
+            if (!active) return;
+            if (!hasTransport()) {
+              deps.typing.stop();
+              return;
+            }
             try {
               await deps.sendAggregateTypingAction?.(targetChatId);
             } catch (error) {
               if (deps.isContextActive?.(ctx) === false) return;
+              if (!active) return;
+              if (!hasTransport()) {
+                deps.typing.stop();
+                return;
+              }
               const message =
                 error instanceof Error ? error.message : String(error);
               updateTelegramRuntimeStatusSafely(deps.updateStatus, ctx, {
@@ -427,6 +459,10 @@ export function createTelegramTypingLoopStarter<TContext>(
             }
           }
         : undefined,
+      shouldContinue: hasTransport,
+      onStopped: () => {
+        active = false;
+      },
     });
   };
 }
@@ -442,7 +478,12 @@ export function startTelegramTypingLoop(
 ): boolean {
   if (deps.chatId === undefined || deps.chatId === 0) return false;
   const previousKey = state.typingLoopKey;
+  const previousDeps = state.typingLoopDeps;
   const nextKey = getTelegramTypingLoopKey(deps);
+  if (previousDeps && previousDeps !== deps) {
+    previousDeps.onStopped?.();
+    state.typingInFlight = undefined;
+  }
   state.typingLoopDeps = deps;
   state.typingLoopKey = nextKey;
   const sendTyping = (): void => {
@@ -450,10 +491,14 @@ export function startTelegramTypingLoop(
     if (
       !activeDeps ||
       activeDeps.chatId === undefined ||
-      activeDeps.chatId === 0 ||
-      state.typingInFlight
+      activeDeps.chatId === 0
     )
       return;
+    if (activeDeps.shouldContinue?.() === false) {
+      stopTelegramTypingLoop(state);
+      return;
+    }
+    if (state.typingInFlight) return;
     const targetChatId = activeDeps.chatId;
     const threadParams = getTelegramTypingLoopThreadParams(activeDeps.target);
     const typing = Promise.resolve()
@@ -486,9 +531,12 @@ export function stopTelegramTypingLoop(
 ): boolean {
   if (!state.typingInterval) return false;
   clearInterval(state.typingInterval);
+  const activeDeps = state.typingLoopDeps;
   state.typingInterval = undefined;
   state.typingLoopDeps = undefined;
   state.typingLoopKey = undefined;
+  state.typingInFlight = undefined;
+  activeDeps?.onStopped?.();
   return true;
 }
 
@@ -571,6 +619,8 @@ export interface TelegramPromptDispatchRuntimeDeps<
   sendAggregateTypingAction?: (chatId: number) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   isContextActive?: (ctx: TContext) => boolean;
+  isTransportAvailable?: () => boolean;
+  getTransportAuthority?: () => string | number | undefined;
   intervalMs?: number;
 }
 

package/lib/status.ts

@@ -871,9 +871,6 @@ export function buildTelegramStatusBarText(
   state: TelegramStatusBarState,
 ): string {
   const label = theme.fg("accent", getTelegramStatusBarLabel(state));
-  if (state.error) {
-    return `${label} ${theme.fg("error", "error")}`;
-  }
   const queued = state.queuedStatus
     ? theme.fg("success", state.queuedStatus)
     : "";
@@ -885,6 +882,9 @@ export function buildTelegramStatusBarText(
     return `${label} ${theme.fg("warning", "electing")}${queued}`;
   if (!state.pollingActive && state.busRole !== "follower")
     return `${theme.fg("accent", "telegram")} ${theme.fg("dim", "disconnected")}${queued}`;
+  if (state.error) {
+    return `${label} ${theme.fg("error", "error")}`;
+  }
   if (state.processing) {
     const processingStatus = state.queuedStatus
       ? "active"

package/package.json

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

package/skills/generated-control-surface/SKILL.md

@@ -54,9 +54,15 @@ Console programs are one capability source, not the defining boundary. Use the r
 
 ## Control Admission
 
-Buttons are optional, but bias toward offering them when they materially shorten a likely feedback loop. If the user can approve, reject, refine, prioritize, redirect, inspect, or choose a concrete next step faster by tapping than by composing a reply, proactively expose the smallest useful control set without waiting to be asked for buttons.
+Buttons are optional only when no candidate passes the admission test. Bias toward offering them whenever they materially shorten a likely feedback loop. If the user can approve, reject, refine, prioritize, redirect, inspect, or choose a concrete next step faster by tapping than by composing a reply, proactively expose the smallest useful control set without waiting to be asked for buttons.
 
-Zero buttons remains preferable when controls would only decorate the answer, restate visible prose, solicit generic “What next?” input, expose an unclear consequence, or save negligible effort. A button earns its place by reducing response effort, ambiguity, turnaround time, or supervision cost while preserving an ordinary typed reply as a first-class option.
+On a Telegram-originated turn, emitting controls is required when the response asks the user for one or more bounded confirmations or choices, the likely answers can be represented truthfully in 2–6 safe controls, and no secret-bearing or high-impact ambiguity blocks their formulation. This includes blocking questions such as confirming scope, version, workflow classification, approval, or the next release step. Ask in prose when explanation is necessary, but attach the controls in the same reply; the availability of free-form typing is not a reason to omit them. A high-impact operation still uses the required confirmation flow rather than a one-tap execution shortcut.
+
+Apply the same requirement at a workflow handoff even when the current user message itself was a complete correction or implementation command. Before concluding a Telegram reply, project the user's likely next intent from the active goal, recent trajectory, newly completed act, and available capabilities—not only from an explicitly pending question. Typical phase transitions include “prepare → release”, “inspect → approve”, “fix → rerun”, and “draft → send”. If one next action or a small alternative set is high-confidence, newly unblocked, truthfully expressible, and safe to request, emit 2–6 controls now instead of waiting for the user to restate the obvious next step. A narrowly completed subtask does not erase the parent intent or make the predictive handoff decorative.
+
+This is anticipatory interaction, not generic suggestion generation. Prefer controls that advance the user's demonstrated workflow over broad capability menus, speculative side quests, or “What next?” buttons. A predicted high-impact action is offered as an explicit self-contained request or confirmation, never silently executed. When confidence is low or materially different next intents compete, omit controls or expose only the smallest clarifying choice.
+
+Zero buttons remains preferable when controls would only decorate the answer, restate visible prose, solicit generic “What next?” input, expose an unclear consequence, save negligible effort, or when the user already issued a complete command and neither that command nor the inferred active workflow leaves a high-confidence immediate decision. A button earns its place by reducing response effort, ambiguity, turnaround time, or supervision cost while preserving an ordinary typed reply as a first-class option.
 
 For status requests, show a compact `Refresh` control and bounded inspect/drill-down controls only when work is active, blocked, stale-sensitive, or otherwise actionable. A completed static status needs no buttons. Do not add destructive shortcuts or actions whose target and consequence are not yet clear.
 
@@ -130,11 +136,11 @@ Use the transport's canonical prompt-button syntax. For pi-telegram, one top-lev
 
 Model the control surface as an ordered ragged sequence of independently sized rows, not as a rectangular matrix to fill. Rectangular grids are one specialization for genuinely spatial or coordinate-bearing state; most interfaces should vary row width according to hierarchy, grouping, label pressure, and action priority.
 
-- Put controls in one compact row only when they are genuine peers that answer the same local question or form one coherent toolbar/navigation group.
-- Use a singleton full-width row for a structurally independent, pinned, primary, summary, or high-consequence action when separation improves comprehension.
+- Default to one full-width button per row for non-spatial controls. Put controls in one compact row only when they are genuine peers that answer the same local question or form one coherent toolbar/navigation group **and** their rendered labels comfortably fit a narrow phone-width chat.
+- Use a singleton full-width row for a structurally independent, pinned, primary, summary, or high-consequence action, and whenever label length makes horizontal grouping cramped or ambiguous.
 - Vary row widths intentionally—for example `1 → 2 → 4 → 1 → 2`—and never pad a row with empty, duplicate, or no-op controls merely to produce uniform dimensions.
 - Preserve reading order across rows: orientation and structural navigation first, primary content or choices next, secondary controls afterward, and destructive actions visibly separated when present.
-- Use at most two columns when buttons carry words, phrases, icon-plus-text labels, or other text that must be read; move additional peer choices into more semantic rows rather than compressing four or more textual buttons across a phone-width line. Three through five columns are for short symbols, glyphs, coordinates, or compact codes whose position carries meaning. Six through eight may be used only for single-glyph or similarly minimal position-bearing labels whose grouping materially improves the interaction. Eight is the phone-width UX maximum: never generate a row of nine or more controls even though the parser has no artificial width cap. Never shorten necessary wording merely to increase row density; regroup or use full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose.
+- Treat two columns as an earned compact mode, not the default: a pair normally fits when each label is no more than one emoji plus roughly two average-length words. If either label has more words, unusually long words, qualifiers, or likely wrapping, place each button on its own row. Use at most two columns for readable text labels; move additional peer choices into more semantic rows rather than compressing textual buttons across a phone-width line. Three through five columns are for short symbols, glyphs, coordinates, or compact codes whose position carries meaning. Six through eight may be used only for single-glyph or similarly minimal position-bearing labels whose grouping materially improves the interaction; a row of emoji-only controls may therefore legitimately use up to eight columns. Eight is the phone-width UX maximum: never generate a row of nine or more controls even though the parser has no artificial width cap. Never shorten necessary wording merely to increase row density; regroup or use full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose.
 
 Treat vertical extent independently from horizontal density. A genuinely spatial surface may retain many rows—such as an `8×16` field—when vertical continuity, coordinates, and one-glance topology matter; do not paginate merely to make its height match its width. For non-spatial collections, however, a tall button wall should yield to semantic grouping, progressive disclosure, or pagination. Keep compact state and instructions above a tall surface, preserve stable coordinates across regeneration, and avoid repeating prose between rows.
 
@@ -181,7 +187,7 @@ Button prompts must:
 - Request fresh inspection when state may have changed.
 - Avoid embedding volatile output that should be rediscovered.
 
-Labels stay short, distinct, and scannable. Emoji are optional semantic markers; do not rely on color alone. If buttons are unavailable, render the same control surface as a numbered choice list.
+Labels stay short, distinct, and scannable. Prefer an explicit `label` over exposing a long prompt as button text. Emoji are explicitly allowed and encouraged when one consistent semantic marker improves scanning or expressiveness; keep their meaning consistent across sibling controls, avoid decorative noise, and do not rely on emoji or color alone. If buttons are unavailable, render the same control surface as a numbered choice list.
 
 ## Capability Adapters
 
@@ -230,6 +236,8 @@ Buttons may represent explicit alternatives without live system inspection. Stat
 
 Before sending a surface, verify:
 
+- If the reply asks a Telegram user for bounded confirmation or selection, qualifying controls are present; do not ship a prose-only blocking question merely because the answer is short.
+- If the completed act unblocks a high-confidence next intent inferred from the parent goal and workflow trajectory, qualifying handoff controls are present even when no explicit pending question exists and the latest user message was itself a complete command.
 - State and controls share one clear owner and target.
 - Live claims come from current evidence.
 - Complete versus filtered or adapted output is labeled honestly.