@llblab/pi-telegram 0.46.0 → 0.48.0

package/lib/bindings.ts

@@ -10,6 +10,7 @@ import * as ChannelPosts from "./channel-posts.ts";
 import * as CommandTemplates from "./command-templates.ts";
 import * as Commands from "./commands.ts";
 import * as Config from "./config.ts";
+import * as Delivery from "./delivery.ts";
 import * as Keyboard from "./keyboard.ts";
 import * as Lifecycle from "./lifecycle.ts";
 import * as Locks from "./locks.ts";
@@ -176,14 +177,47 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
   };
 }
 
+export interface TelegramGenerativeAppLiveSurfaceBinding {
+  get: () =>
+    | GenerativeApps.GenerativeAppLiveSurfaceRuntime<GenerativeApps.TelegramBindLiveHandle>
+    | undefined;
+  set: (
+    runtime: GenerativeApps.GenerativeAppLiveSurfaceRuntime<GenerativeApps.TelegramBindLiveHandle>
+      | undefined,
+  ) => void;
+  shutdown: () => void;
+}
+
+export function createTelegramGenerativeAppLiveSurfaceBinding():
+TelegramGenerativeAppLiveSurfaceBinding {
+  let current:
+    | GenerativeApps.GenerativeAppLiveSurfaceRuntime<GenerativeApps.TelegramBindLiveHandle>
+    | undefined;
+  return {
+    get() { return current; },
+    set(runtime) {
+      current?.shutdown();
+      current = runtime;
+    },
+    shutdown() {
+      current?.shutdown();
+      current = undefined;
+    },
+  };
+}
+
 export function createTelegramGenerativeAppBoundButtonActionInvoker<
   TQuery extends {
-    message?: { chat?: { id?: number }; message_id?: number };
+    message?: { chat?: { id?: number }; message_id?: number; message_thread_id?: number };
   },
 >(deps: {
   agentDir: string;
   assertExecutionCurrent: (query: TQuery) => void;
   getExecutionFence: (query: TQuery) => GenerativeApps.GenerativeAppExecutionFence | undefined;
+  getActiveProfileName?: () => string | undefined;
+  getLiveSurfaceRuntime?: () =>
+    | GenerativeApps.GenerativeAppLiveSurfaceRuntime<GenerativeApps.TelegramBindLiveHandle>
+    | undefined;
   planOutput: ReturnType<typeof OutboundHandlers.createTelegramOutboundReplyPlanner>;
   sendMarkdownReply: (
     chatId: number,
@@ -205,10 +239,29 @@ export function createTelegramGenerativeAppBoundButtonActionInvoker<
 ) => Promise<false | "new" | "edit"> {
   return async (action, query) => {
     let boundAction: GenerativeApps.GenerativeAppBoundAction | undefined;
+    let handedOff:
+      | GenerativeApps.GenerativeAppLiveSurface<GenerativeApps.TelegramBindLiveHandle>
+      | undefined;
     try {
       boundAction = GenerativeApps.parseGenerativeAppBoundAction(action.prompt);
       if (!boundAction) return false;
       deps.assertExecutionCurrent(query);
+      const chatId = query.message?.chat?.id;
+      const messageId = query.message?.message_id;
+      if (typeof chatId !== "number" || typeof messageId !== "number") {
+        throw new Error("Generative App callback target is unavailable.");
+      }
+      const liveSurfaces = deps.getLiveSurfaceRuntime?.();
+      handedOff = liveSurfaces?.take(GenerativeApps.getTelegramBindLiveSurfaceKey(
+        boundAction.app,
+        deps.getActiveProfileName?.() ?? "default",
+        {
+          chatId,
+          ...(query.message?.message_thread_id !== undefined
+            ? { threadId: query.message.message_thread_id }
+            : {}),
+        },
+      ));
       const result = await GenerativeApps.invokeGenerativeApp({
         agentDir: deps.agentDir,
         ...(deps.getExecutionFence(query)
@@ -227,11 +280,6 @@ export function createTelegramGenerativeAppBoundButtonActionInvoker<
         app: boundAction.app,
       });
       deps.assertExecutionCurrent(query);
-      const chatId = query.message?.chat?.id;
-      const messageId = query.message?.message_id;
-      if (typeof chatId !== "number" || typeof messageId !== "number") {
-        throw new Error("Generative App callback target is unavailable.");
-      }
       const reply = deps.planOutput(result.output, {
         binding: {
           generation: result.generation,
@@ -239,6 +287,19 @@ export function createTelegramGenerativeAppBoundButtonActionInvoker<
           revision: result.revision,
         },
       });
+      if (handedOff && liveSurfaces) {
+        try {
+          await liveSurfaces.resume(handedOff, result);
+          deps.assertExecutionCurrent(query);
+          return "edit";
+        } catch (error) {
+          deps.recordRuntimeEvent("generative-app", error, {
+            phase: "bound-action-live-edit-fallback",
+            app: boundAction.app,
+            method: boundAction.method,
+          });
+        }
+      }
       if (result.viewMode === "edit" && deps.editInteractiveMessage) {
         let editFailed = false;
         try {
@@ -267,6 +328,7 @@ export function createTelegramGenerativeAppBoundButtonActionInvoker<
       deps.assertExecutionCurrent(query);
       return "new";
     } catch (error) {
+      if (handedOff) deps.getLiveSurfaceRuntime?.()?.open(handedOff);
       deps.recordRuntimeEvent("generative-app", error, {
         phase: "bound-action",
         ...(boundAction
@@ -534,6 +596,10 @@ interface TelegramCommandsAndToolsBindingDeps {
   resolveAgentTarget?: OutboundAttachments.TelegramOutboundMessageToolRegistrationDeps["resolveAgentTarget"];
   routeAgentMessage?: OutboundAttachments.TelegramOutboundMessageToolRegistrationDeps["routeAgentMessage"];
   canSendDirect: () => boolean;
+  setGenerativeAppLiveSurfaceRuntime?: (
+    runtime: GenerativeApps.GenerativeAppLiveSurfaceRuntime<GenerativeApps.TelegramBindLiveHandle>
+      | undefined,
+  ) => void;
   updateStatus: TelegramBridgeStatusUpdater;
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }
@@ -565,17 +631,31 @@ export function registerTelegramCommandsAndTools({
   resolveAgentTarget,
   routeAgentMessage,
   canSendDirect,
+  setGenerativeAppLiveSurfaceRuntime,
   recordRuntimeEvent,
   updateStatus,
 }: TelegramCommandsAndToolsBindingDeps): void {
   GenerativeApps.registerTelegramBindTool(pi, {
     agentDir,
+    getActiveProfileName: configStore.getActiveProfileName,
     getActiveTurn: activeTurnRuntime.get,
+    ...(setGenerativeAppLiveSurfaceRuntime
+      ? { setLiveSurfaceRuntime: setGenerativeAppLiveSurfaceRuntime }
+      : {}),
+    isDeliveryHandleCurrent: Delivery.isTelegramDeliveryHandleCurrent,
+    editView: (handle, view) => Delivery.editTelegramView(
+      handle as Delivery.TelegramDeliveryHandle,
+      view as Delivery.TelegramDeliveryView,
+    ),
     planOutput: OutboundHandlers.createTelegramOutboundReplyPlanner(
       buttonActionStore,
       Config.createTelegramConfigControls(configStore).getAssistantRenderingMode,
     ),
     sendMarkdownReply,
+    sendView: (view, options) => Delivery.sendTelegramView(
+      view as Delivery.TelegramDeliveryView,
+      options,
+    ),
     recordRuntimeEvent,
   });
   ChannelPosts.registerTelegramChannelPostMutationTool(pi, { mutate: mutateChannelPost });
@@ -782,6 +862,7 @@ interface TelegramLifecycleBindingDeps {
   deferredQueueDispatchRuntime: Queue.TelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>;
   modelContextAvailabilityRuntime: Prompts.TelegramModelContextAvailabilityRuntime;
   disconnectOnQuit?: () => Promise<unknown>;
+  shutdownGenerativeAppLiveSurfaces?: () => void;
   resolveAutomaticThreadCleanupEnabled?: () => boolean | Promise<boolean>;
   buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
   callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
@@ -871,6 +952,7 @@ export function registerTelegramLifecycleRuntimeHooks({
   deferredQueueDispatchRuntime,
   modelContextAvailabilityRuntime,
   disconnectOnQuit,
+  shutdownGenerativeAppLiveSurfaces,
   resolveAutomaticThreadCleanupEnabled,
   buttonActionStore,
   callMultipart,
@@ -1194,6 +1276,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     },
     async onSessionShutdown(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      shutdownGenerativeAppLiveSurfaces?.();
       agentLifecycleHooks.clearRetainedAgentEnd();
       activityRuntime.onSessionShutdown();
       activityVerbosityRuntime?.reset();

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 === "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", "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,
@@ -1803,6 +1808,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getDefaultChatId: proactivePushChatIdGetter,
     getDefaultTarget: proactivePushTargetGetter,
     ...agentMessageToolRoutingRuntime,
+    setGenerativeAppLiveSurfaceRuntime: generativeAppLiveSurfaceBinding.set,
     updateStatus,
     recordRuntimeEvent,
   });
@@ -1831,6 +1837,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deferredQueueDispatchRuntime,
     modelContextAvailabilityRuntime,
     disconnectOnQuit: cleanupTelegramThreadForSessionRestart,
+    shutdownGenerativeAppLiveSurfaces: generativeAppLiveSurfaceBinding.shutdown,
     resolveAutomaticThreadCleanupEnabled:
       configControls.resolveAutomaticThreadCleanupEnabled,
     buttonActionStore,