@llblab/pi-telegram 0.45.11 → 0.47.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 {
@@ -293,6 +294,7 @@ export interface TelegramBusFollowerRegistrationRuntimeDeps<
   getNowMs?: () => number;
   getPid?: () => number;
   getProcessBirthId?: () => string;
+  getSessionId?: (ctx: TContext) => string | undefined;
   getSessionGeneration?: () => number;
   timeoutMs?: number;
   registrationTimeoutMs?: number;
@@ -374,6 +376,7 @@ export function createTelegramBusFollowerPromotionHandler<
   topicTargetStore: Threads.TelegramTopicTargetStore;
   instanceId: string;
   getActiveProfileName: () => string | undefined;
+  getSessionId?: (ctx: TContext) => string | undefined;
   startLeader: (
     ctx: TContext,
     election: TelegramBusFollowerElection,
@@ -400,6 +403,7 @@ export function createTelegramBusFollowerPromotionHandler<
             store: input.topicTargetStore,
             instanceId: input.instanceId,
             cwd: ctx.cwd,
+            sessionId: input.getSessionId?.(ctx),
             telegramProfile: input.getActiveProfileName(),
             target: binding.target,
             slot: binding.slot,
@@ -1771,6 +1775,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
             ? { slot: deps.registrationState?.getSlot() ?? lastKnownSlot }
             : {}),
           cwd: ctx.cwd,
+          sessionId: deps.getSessionId?.(ctx),
           pid: getPid(),
           processBirthId: deps.getProcessBirthId?.(),
           sessionGeneration: deps.getSessionGeneration?.(),
@@ -1910,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";
@@ -113,6 +115,7 @@ export interface TelegramBusLeaderTargetProvisionerDeps<TContext> {
   getAllowedUserId: () => number | undefined;
   instanceId: string;
   getCwd?: (ctx: TContext) => string | undefined;
+  getSessionId?: (ctx: TContext) => string | undefined;
   getTelegramProfile?: () => string | undefined;
   shouldForceFreshUnnamed?: () => boolean;
   getRequestedThreadName?: () => string | undefined;
@@ -234,6 +237,7 @@ export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
   getAllowedUserId: () => number | undefined;
   instanceId: string;
   getCwd?: (ctx: TContext) => string | undefined;
+  getSessionId?: (ctx: TContext) => string | undefined;
   getTelegramProfile?: () => string | undefined;
   shouldForceFreshUnnamed?: () => boolean;
   getRequestedThreadName?: () => string | undefined;
@@ -307,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,
@@ -325,6 +336,9 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
               bindings: deps.topicTargetStore.listWorkspaceBindings(),
               binding,
               mode: deps.getThreadDisplayMode!(),
+              liveBindingKeys: captureLiveBindingKeys(
+                deps.topicTargetStore.listWorkspaceBindings(),
+              ),
             });
           },
         }
@@ -337,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;
@@ -390,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();
@@ -413,6 +431,7 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
     ...provisionerPorts,
     instanceId: deps.instanceId,
     getCwd: deps.getCwd,
+    getSessionId: deps.getSessionId,
     getTelegramProfile: deps.getTelegramProfile,
     shouldForceFreshUnnamed: deps.shouldForceFreshUnnamed,
     getRequestedThreadName: deps.getRequestedThreadName,
@@ -594,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(),
@@ -689,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}`,
@@ -908,6 +933,7 @@ export function createTelegramBusFollowerTargetProvisioner(
           {
             existingBindingOnly:
               options?.existingWorkspaceBindingOnly === true,
+            sessionId: registration.sessionId,
             onCapacityUnavailable() {
               capacityUnavailable = true;
             },
@@ -925,6 +951,7 @@ export function createTelegramBusFollowerTargetProvisioner(
       ? deps.topicTargetStore.getWorkspaceBinding(
           workspaceIdentity.cwd,
           workspaceIdentity.instanceSlot,
+          workspaceIdentity.sessionId,
         )
       : undefined;
     const provision = Threads.createTelegramTopicTargetProvisioner({
@@ -1567,6 +1594,7 @@ export function createTelegramBusLeaderTargetProvisioner<TContext>(
         getAllowedUserId: deps.getAllowedUserId,
         instanceId: deps.instanceId,
         cwd: normalizedCwd,
+        sessionId: deps.getSessionId?.(ctx),
         telegramProfile: deps.getTelegramProfile?.(),
         forceFreshUnnamed: deps.shouldForceFreshUnnamed?.(),
         requestedThreadName: deps.getRequestedThreadName?.(),
@@ -2101,6 +2129,8 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
           );
         if (
           !compatibility.compatible || !displayCompatible() ||
+          (envelope.registration.cwd !== undefined &&
+            envelope.registration.sessionId === undefined) ||
           (restoringWorkspace && !supportsWorkspaceAutoConnect)
         ) {
           return {
@@ -2110,7 +2140,11 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
             protocol: deps.protocolIdentity,
             error: { code: "incompatible-protocol" as const },
             message: `Incompatible Telegram bus protocol: ${
-              compatibility.reason ?? "missing-capability"
+              compatibility.reason ??
+                (envelope.registration.cwd !== undefined &&
+                  envelope.registration.sessionId === undefined
+                  ? "missing-session-identity"
+                  : "missing-capability")
             }.`,
           };
         }
@@ -2231,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

@@ -220,7 +220,7 @@ export function createTelegramBusAuthSecret(): string {
   return randomBytes(32).toString("base64url");
 }
 
-export const TELEGRAM_BUS_PROTOCOL_VERSION = 1 as const;
+export const TELEGRAM_BUS_PROTOCOL_VERSION = 2 as const;
 export const TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION =
   "durable-follower-admission-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF =
@@ -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;
 
@@ -369,6 +371,7 @@ export interface TelegramBusInstanceRegistration {
   threadName?: string;
   slot?: string;
   cwd?: string;
+  sessionId?: string;
   pid?: number;
   target?: TelegramTarget;
   busSocketPath?: string;
@@ -1026,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 };
       }
@@ -2991,6 +2995,12 @@ function parseRegistration(
     registration.slot = value.slot;
   }
   if (typeof value.cwd === "string") registration.cwd = value.cwd;
+  if (value.sessionId !== undefined) {
+    if (typeof value.sessionId !== "string" || !value.sessionId ||
+        value.sessionId !== value.sessionId.trim() ||
+        Buffer.byteLength(value.sessionId, "utf8") > 256) return undefined;
+    registration.sessionId = value.sessionId;
+  }
   if (typeof value.pid === "number") registration.pid = value.pid;
   if (typeof value.busSocketPath === "string") {
     registration.busSocketPath = value.busSocketPath;

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,