@llblab/pi-telegram 0.46.0 → 0.47.0

package/lib/bus-follower.ts

@@ -43,6 +43,7 @@ import {
   type TelegramBusSocketPathSource,
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
   TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
+  TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
 } from "./bus.ts";
 import type { TelegramConfigStore, TelegramThreadDisplayMode } from "./config.ts";
 import {
@@ -1914,9 +1915,12 @@ export function createTelegramBusFollowerRegistrationRuntime<
       if (!socketPath || !generation || !deps.registrationState?.isRegistered()) {
         throw new Error("Telegram follower is not registered with the leader.");
       }
-      if (!hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE) ||
-          !hasTelegramBusCapability(deps.registrationState.getLeaderProtocol(), TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE)) {
-        throw new Error("The Telegram peers do not support Thread display settings. Update or restart both instances.");
+      const requiredCapability = mode === "directory-snake" || mode === "directory-title"
+        ? TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT
+        : TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE;
+      if (!hasTelegramBusCapability(deps.protocolIdentity, requiredCapability) ||
+          !hasTelegramBusCapability(deps.registrationState.getLeaderProtocol(), requiredCapability)) {
+        throw new Error("The Telegram peers do not support this Thread display setting. Update or restart both instances.");
       }
       const requestId = deps.createRequestId();
       const response = await sendTelegramBusLocalEnvelope({

package/lib/bus-leader.ts

@@ -9,6 +9,7 @@ import * as Sync from "./sync.ts";
 import {
   createTelegramThreadDisplayReconciler,
   resolveTelegramInitialWorkspaceDisplayName,
+  resolveTelegramLiveWorkspaceBindingKeys,
 } from "./thread-display.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
@@ -40,6 +41,7 @@ import {
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT,
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
   TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
+  TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
 } from "./bus.ts";
 import { getTelegramBusTransportRetryPolicy } from "./bus-transport.ts";
 import type { TelegramQueueHandoffPayload } from "./queue.ts";
@@ -309,6 +311,13 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
         });
       },
     }).run;
+  const captureLiveBindingKeys = (
+    bindings: readonly Threads.TelegramWorkspaceThreadBinding[],
+  ): ReadonlySet<string> => resolveTelegramLiveWorkspaceBindingKeys(
+    bindings,
+    deps.topicTargetStore.getActiveByInstanceId(deps.instanceId)?.target,
+    deps.runtime.followerRegistry.list(),
+  );
   const provisionerPorts = {
     getAllowedUserId: deps.getAllowedUserId,
     topicTargetStore: deps.topicTargetStore,
@@ -327,6 +336,9 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
               bindings: deps.topicTargetStore.listWorkspaceBindings(),
               binding,
               mode: deps.getThreadDisplayMode!(),
+              liveBindingKeys: captureLiveBindingKeys(
+                deps.topicTargetStore.listWorkspaceBindings(),
+              ),
             });
           },
         }
@@ -339,6 +351,7 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
     getMode: deps.getThreadDisplayMode,
     getProfileKey: () => deps.getTelegramProfile?.() ?? "default",
     getLeaderEpoch: () => deps.getCurrentLeaderEpoch?.(),
+    captureLiveBindingKeys,
     captureBindingAuthority(binding) {
       const matches = (target: TelegramTarget | undefined) =>
         target?.chatId === binding.target.chatId && target?.threadId === binding.target.threadId;
@@ -392,8 +405,11 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
           throw new Error("Telegram Thread display setting requires current leader authority.");
         }
         const assertDisplayPeers = () => {
+          const requiredCapability = mode === "directory-snake" || mode === "directory-title"
+            ? TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT
+            : TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE;
           if (mode !== "names" && deps.runtime.followerRegistry.list().some((follower) =>
-            !hasTelegramBusCapability(follower.protocol, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE),
+            !hasTelegramBusCapability(follower.protocol, requiredCapability),
           )) throw new Error("Update or restart all connected followers before changing Thread display mode.");
         };
         assertDisplayPeers();
@@ -597,14 +613,17 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
       );
       return binding?.displayTitle ?? binding?.threadName;
     },
-    onFollowerDisconnected: (follower) => runWorkspaceOperation(
-      {
-        operationId: createTelegramWorkspaceAdmissionOperationId(),
-        operationKind: "workspace.disconnect-follower",
-        scopes: [{ kind: "profile" }],
-      },
-      () => disconnectFollower(follower),
-    ),
+    onFollowerDisconnected: async (follower) => {
+      await runWorkspaceOperation(
+        {
+          operationId: createTelegramWorkspaceAdmissionOperationId(),
+          operationKind: "workspace.disconnect-follower",
+          scopes: [{ kind: "profile" }],
+        },
+        () => disconnectFollower(follower),
+      );
+      scheduleDisplay();
+    },
     async renameFollowerThread(follower, threadName) {
       return runWorkspaceOperation({
         operationId: createTelegramWorkspaceAdmissionOperationId(),
@@ -692,14 +711,17 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
         });
       },
     ),
-    onFollowerConfirmedDead: (follower) => runWorkspaceOperation(
-      {
-        operationId: createTelegramWorkspaceAdmissionOperationId(),
-        operationKind: "workspace.cleanup-dead-follower",
-        scopes: [{ kind: "profile" }],
-      },
-      () => cleanupConfirmedDeadFollower(follower),
-    ),
+    onFollowerConfirmedDead: async (follower) => {
+      await runWorkspaceOperation(
+        {
+          operationId: createTelegramWorkspaceAdmissionOperationId(),
+          operationKind: "workspace.cleanup-dead-follower",
+          scopes: [{ kind: "profile" }],
+        },
+        () => cleanupConfirmedDeadFollower(follower),
+      );
+      scheduleDisplay();
+    },
     provisionFollowerTarget: (registration, options) => runWorkspaceOperation(
       {
         operationId: `follower-provision:${registration.instanceId}:${registration.registrationGeneration}`,
@@ -2243,9 +2265,12 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
         const current = () => epoch !== undefined && deps.getCurrentLeaderEpoch?.() === epoch &&
           deps.followerRegistry.get(envelope.instanceId)?.registrationGeneration === envelope.registrationGeneration;
         const follower = deps.followerRegistry.get(envelope.instanceId);
+        const requiredCapability = envelope.mode === "directory-snake" || envelope.mode === "directory-title"
+          ? TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT
+          : TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE;
         if (!current() || !follower?.registrationGeneration || !deps.applyThreadDisplayMode ||
-            !hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE) ||
-            !hasTelegramBusCapability(follower.protocol, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE)) {
+            !hasTelegramBusCapability(deps.protocolIdentity, requiredCapability) ||
+            !hasTelegramBusCapability(follower.protocol, requiredCapability)) {
           return { kind: "bus.ack", requestId: envelope.requestId, ok: false,
             message: "Thread display settings require current registration and compatible leader authority." };
         }

package/lib/bus.ts

@@ -230,6 +230,8 @@ export const TELEGRAM_BUS_CAPABILITY_INPUT_CUSTODY_REFERENCE =
 export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME =
   "workspace-thread-rename-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE = "thread-display-mode-v1" as const;
+export const TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT =
+  "directory-display-format-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT =
   "workspace-follower-auto-connect-v1" as const;
 
@@ -1027,7 +1029,8 @@ export function parseTelegramBusEnvelope(
     case "follower.setThreadDisplayMode":
       if (typeof value.instanceId === "string" &&
           typeof value.registrationGeneration === "string" &&
-          (value.mode === "letters" || value.mode === "names" || value.mode === "directories")) {
+          (value.mode === "letters" || value.mode === "names" || value.mode === "directories" ||
+      value.mode === "directory-snake" || value.mode === "directory-title")) {
         envelope = { kind, requestId, instanceId: value.instanceId,
           registrationGeneration: value.registrationGeneration, mode: value.mode };
       }

package/lib/commands.ts

@@ -1205,7 +1205,7 @@ export const TELEGRAM_APP_MENU_INTRO_HTML = [
   "<b>Pi Telegram</b>",
   "",
   `${formatTelegramCommandEmojiPrefix("start")}/start — Open menu / Pair bridge`,
-  `${formatTelegramCommandEmojiPrefix("name")}/name Name — Rename this thread`,
+  `${formatTelegramCommandEmojiPrefix("name")}/name — Rename this thread`,
   `${formatTelegramCommandEmojiPrefix("compact")}/compact — Compact current session`,
   `${formatTelegramCommandEmojiPrefix("next")}/next — Force next turn`,
   `${formatTelegramCommandEmojiPrefix("continue")}/continue — Queue continue prompt`,
@@ -1246,7 +1246,7 @@ function buildTelegramAppMenuIntroHtml(): string {
     "<b>Pi Telegram</b>",
     "",
     `${formatTelegramCommandEmojiPrefix("start")}/start — Open menu / Pair bridge`,
-    `${formatTelegramCommandEmojiPrefix("name")}/name Name — Rename this thread`,
+    `${formatTelegramCommandEmojiPrefix("name")}/name — Rename this thread`,
     `${formatTelegramCommandEmojiPrefix("compact")}/compact — Compact current session`,
     ...extensionLines,
     `${formatTelegramCommandEmojiPrefix("next")}/next — Force next turn`,

package/lib/config.ts

@@ -136,16 +136,23 @@ export interface ResolvedTelegramTimeConfig {
   timezone: string;
 }
 
-export type TelegramThreadDisplayMode = "letters" | "names" | "directories";
+export type TelegramThreadDisplayMode =
+  | "letters"
+  | "names"
+  | "directories"
+  | "directory-snake"
+  | "directory-title";
+
+const TELEGRAM_THREAD_DISPLAY_MODES: readonly TelegramThreadDisplayMode[] = [
+  "letters", "names", "directories", "directory-snake", "directory-title",
+];
 
 export function resolveTelegramThreadDisplayMode(
   config: Pick<TelegramConfig, "threadDisplayMode">,
 ): TelegramThreadDisplayMode {
-  return config.threadDisplayMode === "names"
-    ? "names"
-    : config.threadDisplayMode === "directories"
-      ? "directories"
-      : "letters";
+  return TELEGRAM_THREAD_DISPLAY_MODES.includes(config.threadDisplayMode as TelegramThreadDisplayMode)
+    ? config.threadDisplayMode as TelegramThreadDisplayMode
+    : "letters";
 }
 
 export async function setTelegramThreadDisplayMode(
@@ -153,7 +160,7 @@ export async function setTelegramThreadDisplayMode(
   mode: TelegramThreadDisplayMode,
   isCurrent: () => boolean,
 ): Promise<void> {
-  if (!["letters", "names", "directories"].includes(mode)) {
+  if (!TELEGRAM_THREAD_DISPLAY_MODES.includes(mode)) {
     throw new Error("Invalid Telegram Thread display mode.");
   }
   const profile = store.getActiveProfileName();

package/lib/delivery.ts

@@ -18,7 +18,10 @@ import {
   type TelegramTarget,
 } from "./target.ts";
 import {
+  getTelegramApiRetryAfterMs,
+  isRetryableTelegramApiError,
   isTelegramApiCommitUnknownError,
+  isTelegramMessageUnavailableError,
   type TelegramBridgeApiRuntime,
 } from "./telegram-api.ts";
 
@@ -60,6 +63,9 @@ export type TelegramDeliveryFailureReason =
   | "stale-handle"
   | "invalid-view"
   | "commit-unknown"
+  | "message-unavailable"
+  | "rate-limited"
+  | "transport-retryable"
   | "transport-failed";
 
 export type TelegramDeliveryResult<T> =
@@ -68,6 +74,8 @@ export type TelegramDeliveryResult<T> =
       ok: false;
       reason: TelegramDeliveryFailureReason;
       message: string;
+      /** Exact Telegram flood-control delay when supplied by the API. */
+      retryAfterMs?: number;
       /** Successfully materialized state that callers may edit or delete to recover. */
       partial?: T;
     };
@@ -246,10 +254,26 @@ function failure<T>(
   reason: TelegramDeliveryFailureReason,
   message: string,
   partial?: T,
+  retryAfterMs?: number,
 ): TelegramDeliveryResult<T> {
+  const retry = retryAfterMs === undefined ? {} : { retryAfterMs };
   return partial === undefined
-    ? { ok: false, reason, message }
-    : { ok: false, reason, message, partial };
+    ? { ok: false, reason, message, ...retry }
+    : { ok: false, reason, message, partial, ...retry };
+}
+
+export function classifyTelegramDeliveryTransportError(error: unknown): {
+  reason: Extract<TelegramDeliveryFailureReason,
+    "commit-unknown" | "message-unavailable" | "rate-limited" |
+    "transport-retryable" | "transport-failed">;
+  retryAfterMs?: number;
+} {
+  if (isTelegramApiCommitUnknownError(error)) return { reason: "commit-unknown" };
+  if (isTelegramMessageUnavailableError(error)) return { reason: "message-unavailable" };
+  const retryAfterMs = getTelegramApiRetryAfterMs(error);
+  if (retryAfterMs !== undefined) return { reason: "rate-limited", retryAfterMs };
+  if (isRetryableTelegramApiError(error)) return { reason: "transport-retryable" };
+  return { reason: "transport-failed" };
 }
 
 /** @internal */
@@ -479,14 +503,14 @@ export function createTelegramDeliveryRuntime(
     if (error instanceof TelegramDeliveryTransportGenerationError) {
       return inactive();
     }
+    const classified = classifyTelegramDeliveryTransportError(error);
     return failure(
-      isTelegramApiCommitUnknownError(error)
-        ? "commit-unknown"
-        : "transport-failed",
-      isTelegramApiCommitUnknownError(error)
+      classified.reason,
+      classified.reason === "commit-unknown"
         ? `Telegram delivery ${operation} may have committed before transport failed.`
         : `Telegram delivery ${operation} failed.`,
       partial,
+      classified.retryAfterMs,
     );
   };
   const createHandle = (
@@ -837,6 +861,14 @@ export function clearTelegramDeliveryRuntime(): void {
   registry.runtime = undefined;
 }
 
+/** @internal */
+export function isTelegramDeliveryHandleCurrent(
+  handle: TelegramDeliveryHandle,
+): boolean {
+  const runtime = getTelegramDeliveryRuntimeRegistry().runtime;
+  return runtime !== undefined && runtime.generation === handle.generation;
+}
+
 export async function sendTelegramView(
   view: TelegramDeliveryView,
   options: SendTelegramViewOptions,

package/lib/extension.ts

@@ -64,6 +64,7 @@ const telegramBusProtocolIdentity =
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT,
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
     Bus.TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
+    Bus.TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
   ]);
 
 // --- Extension Runtime ---
@@ -672,11 +673,15 @@ export default function (pi: Pi.ExtensionAPI) {
       getHandlers: configStore.getOutboundHandlers,
       recordRuntimeEvent,
     });
+  const generativeAppLiveSurfaceBinding =
+    Bindings.createTelegramGenerativeAppLiveSurfaceBinding();
   const invokeGenerativeAppBoundButtonAction =
     Bindings.createTelegramGenerativeAppBoundButtonActionInvoker({
       agentDir: Paths.resolveAgentDir(),
       assertExecutionCurrent: Updates.assertTelegramUpdateExecutionCurrent,
       getExecutionFence: Updates.getTelegramUpdateExecutionFence,
+      getActiveProfileName: configStore.getActiveProfileName,
+      getLiveSurfaceRuntime: generativeAppLiveSurfaceBinding.get,
       planOutput: planGenerativeAppOutput,
       sendMarkdownReply,
       editInteractiveMessage,
@@ -861,6 +866,18 @@ export default function (pi: Pi.ExtensionAPI) {
         return threadStore.getBotState().threadMode === "enabled"
           ? Config.resolveTelegramThreadDisplayMode(configStore.get()) : undefined;
       },
+      getThreadDisplayPreview(mode) {
+        const bindings = threadStore.listWorkspaceBindings();
+        return [...ThreadDisplay.resolveTelegramWorkspaceDisplayNames(
+          bindings,
+          mode,
+          ThreadDisplay.resolveTelegramLiveWorkspaceBindingKeys(
+            bindings,
+            threadStore.getActiveByInstanceId(telegramInstanceId)?.target,
+            telegramBusFollowerRegistry.list(),
+          ),
+        ).values()];
+      },
       async setThreadDisplayMode(mode) {
         try {
           await ThreadDisplay.applyTelegramThreadDisplaySetting(mode, {
@@ -1803,6 +1820,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getDefaultChatId: proactivePushChatIdGetter,
     getDefaultTarget: proactivePushTargetGetter,
     ...agentMessageToolRoutingRuntime,
+    setGenerativeAppLiveSurfaceRuntime: generativeAppLiveSurfaceBinding.set,
     updateStatus,
     recordRuntimeEvent,
   });
@@ -1831,6 +1849,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deferredQueueDispatchRuntime,
     modelContextAvailabilityRuntime,
     disconnectOnQuit: cleanupTelegramThreadForSessionRestart,
+    shutdownGenerativeAppLiveSurfaces: generativeAppLiveSurfaceBinding.shutdown,
     resolveAutomaticThreadCleanupEnabled:
       configControls.resolveAutomaticThreadCleanupEnabled,
     buttonActionStore,