@llblab/pi-kit 0.14.1 → 0.16.0

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

@@ -77,6 +77,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getCommands,
     getThinkingLevel,
     sendUserMessage,
+    registerCommand,
     setActiveTools,
     setModel,
     setThinkingLevel,
@@ -237,6 +238,26 @@ export default function (pi: Pi.ExtensionAPI) {
     canReset: lockRuntime.owns,
     commitReset: lockRuntime.commitIfOwned,
   });
+  const sessionActionAssembly = Commands.createTelegramSessionActionAssembly({
+    registerCommand,
+    sendUserMessage,
+    store: threadStore,
+    getProfileName: configStore.getActiveProfileName,
+    ownsPersistence: lockRuntime.owns,
+    async sendResult(target, html) {
+      const delivery = await Delivery.sendTelegramView(
+        { text: html, parseMode: "html", replyMarkup: { inline_keyboard: [] } },
+        { scope: { kind: "target", target } },
+      );
+      return delivery.ok ? { ok: true } : { ok: false,
+        retryable: delivery.reason === "runtime-unavailable" ||
+          delivery.reason === "target-unavailable" ||
+          delivery.reason === "transport-retryable" };
+    },
+    handoffTtlMs: Threads.TELEGRAM_LEADER_SESSION_HANDOFF_TTL_MS,
+    recordRuntimeEvent,
+  });
+  const sessionActionsRuntime = sessionActionAssembly.action;
   const lockOwnershipGuard =
     Locks.createTelegramLockOwnershipGuard(lockRuntime);
   const getCurrentLeaderEpoch = lockRuntime.getOwnedLeaderEpoch;
@@ -851,6 +872,24 @@ export default function (pi: Pi.ExtensionAPI) {
     updateStatusMessage: menuActions.updateStatusMessage,
     updateStatus,
   });
+  const threadDisplaySettingsRuntime =
+    ThreadDisplay.createTelegramThreadDisplaySettingsRuntime({
+      getTarget() {
+        return telegramBusFollowerRegistrationState.getTarget() ??
+          telegramBusLeaderState.getTarget();
+      },
+      getBinding(target) { return threadStore.getWorkspaceBindingByTarget(target); },
+      apply(mode) {
+        return ThreadDisplay.applyTelegramThreadDisplaySetting(mode, {
+          getProfileKey: configStore.getActiveProfileName,
+          ownsLeader() { return getCurrentLeaderEpoch() !== undefined; },
+          getLeaderSetter() { return telegramBusLeaderRuntime.setThreadDisplayMode; },
+          getFollowerSetter() { return telegramBusFollowerRegistration.setThreadDisplayMode; },
+          reloadConfig: configStore.load,
+        });
+      },
+      reset(target) { return telegramThreadDisplayNameResetBinding.reset(target); },
+    });
   const settingsMenuRuntime = MenuSettings.createTelegramSettingsMenuRuntime(
     {
       reloadConfig: configStore.load,
@@ -866,16 +905,10 @@ export default function (pi: Pi.ExtensionAPI) {
         return threadStore.getBotState().threadMode === "enabled"
           ? Config.resolveTelegramThreadDisplayMode(configStore.get()) : undefined;
       },
+      isThreadDisplayCustom: threadDisplaySettingsRuntime.isCustom,
       async setThreadDisplayMode(mode) {
-        try {
-          await ThreadDisplay.applyTelegramThreadDisplaySetting(mode, {
-            getProfileKey: configStore.getActiveProfileName,
-            ownsLeader() { return getCurrentLeaderEpoch() !== undefined; },
-            getLeaderSetter() { return telegramBusLeaderRuntime.setThreadDisplayMode; },
-            getFollowerSetter() { return telegramBusFollowerRegistration.setThreadDisplayMode; },
-            reloadConfig: configStore.load,
-          });
-        } catch (error) {
+        try { await threadDisplaySettingsRuntime.setMode(mode); }
+        catch (error) {
           recordRuntimeEvent("bus", error, { phase: "thread-display-setting" });
           throw error;
         }
@@ -959,6 +992,36 @@ export default function (pi: Pi.ExtensionAPI) {
     foreignOwnedUpdateForwarder,
     replaceFollowerThreadTarget: restoreFollowerThreadTarget,
     bridgeRuntime,
+    requestNewSession(source) {
+      const updateId = Updates.getTelegramUpdateExecutionFence(source)?.updateId;
+      if (updateId === undefined) {
+        throw new Error("Telegram session replacement requires durable update authority.");
+      }
+      const callbackMessage = source && typeof source === "object" && "message" in source
+        ? (source as { message?: unknown }).message
+        : source;
+      const messageTarget = callbackMessage as {
+        chat?: { id?: unknown };
+        message_id?: unknown;
+        message_thread_id?: unknown;
+      } | undefined;
+      const target = typeof messageTarget?.chat?.id === "number" &&
+          typeof messageTarget.message_id === "number"
+        ? {
+            chatId: messageTarget.chat.id,
+            messageId: messageTarget.message_id,
+            ...(typeof messageTarget.message_thread_id === "number"
+              ? { threadId: messageTarget.message_thread_id }
+              : {}),
+          }
+        : undefined;
+      if (!target) {
+        throw new Error("Telegram session replacement target is unavailable.");
+      }
+      if (!sessionActionsRuntime.scheduleAfterUpdate(updateId, target)) {
+        throw new Error("A Telegram session replacement is already pending.");
+      }
+    },
     activeTurnRuntime,
     mediaGroupRuntime,
     textGroupRuntime,
@@ -1066,6 +1129,7 @@ export default function (pi: Pi.ExtensionAPI) {
       dispatchNext: dispatchNextQueuedTelegramTurn,
       requestQueueHandoffReconciliation:
         queueHandoffReconciliationBinding.request,
+      afterUpdateCompleted: sessionActionsRuntime.onUpdateCompleted,
     },
     worker: {
       defaultHandle: inboundRouteRuntime.handleUpdate,
@@ -1638,6 +1702,7 @@ export default function (pi: Pi.ExtensionAPI) {
       }
     },
   }.reset);
+  sessionActionsRuntime.register();
   Bindings.registerTelegramCommandsAndTools({
     pi,
     agentDir: Paths.resolveAgentDir(),
@@ -1840,6 +1905,9 @@ export default function (pi: Pi.ExtensionAPI) {
     shutdownGenerativeAppLiveSurfaces: generativeAppLiveSurfaceBinding.shutdown,
     resolveAutomaticThreadCleanupEnabled:
       configControls.resolveAutomaticThreadCleanupEnabled,
+    onSessionStarted(_event, ctx) {
+      sessionActionAssembly.settlement.onSessionStart(ctx);
+    },
     buttonActionStore,
     callMultipart,
     sendChatAction,

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -23,6 +23,7 @@ export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 
 export interface TelegramSettingsStateDeps {
   getThreadDisplayMode?: () => TelegramThreadDisplayMode | undefined;
+  isThreadDisplayCustom?: () => boolean;
   areDraftPreviewsEnabled: () => boolean;
   getAssistantRenderingMode: () => TelegramAssistantRenderingMode;
   getActivityVerbosity: () => TelegramActivityVerbosity;
@@ -177,12 +178,15 @@ export function buildTelegramSettingsMenuText(): string {
 
 export function buildThreadDisplaySettingsText(
   mode: TelegramThreadDisplayMode,
+  custom = false,
 ): string {
   return [
-    `${THREAD_DISPLAY_SETTINGS_TITLE} <code>${threadDisplayModeLabel(mode)}</code>`,
+    `${THREAD_DISPLAY_SETTINGS_TITLE} <code>${custom ? "custom" : threadDisplayModeLabel(mode)}</code>`,
     "",
     "Choose how this bot profile labels Telegram tabs and Pi terminal status. Each slot is unique across this bot profile.",
     "",
+    "Set a manual name for the current Thread with /name <code>Name</code>.",
+    "",
     "<code>-</code> <code>letters</code> (default): show the unique slot, such as <b><i>A</i></b> or <b><i>B</i></b>.",
     "<code>-</code> <code>names</code>: show the generated dictionary name for the slot, such as <b><i>Anchor</i></b> or <b><i>Briar</i></b>.",
     "<code>-</code> <code>directory-title</code>: humanize the distinguishing directory path, such as <b><i>Api Tools</i></b> or <b><i>Frontend / Extensions A</i></b>.",
@@ -311,6 +315,7 @@ export function buildTelegramSettingsMenuReplyMarkup(
   automaticThreadCleanupEnabled = true,
   activityVerbosity: TelegramActivityVerbosity = "quiet",
   threadDisplayMode?: TelegramThreadDisplayMode,
+  threadDisplayCustom = false,
 ): TelegramSettingsMenuReplyMarkup {
   const hasRenderingMode =
     assistantRenderingModeOrVoiceReplyMode === "rich" ||
@@ -364,15 +369,17 @@ export function buildTelegramSettingsMenuReplyMarkup(
       text: `🕒 Time injection: ${getTelegramSettingsStateValueLabel(timeInjectionMode)}`,
       callback_data: "settings:open:time-injection",
     },
+  ];
+  if (threadDisplayMode) settingsButtons.push(
     {
       text: `🧹 Thread cleanup: ${automaticThreadCleanupEnabled ? "on" : "off"}`,
       callback_data: "settings:open:automatic-thread-cleanup",
     },
-  ];
-  if (threadDisplayMode) settingsButtons.push({
-    text: `🧵 Thread display: ${threadDisplayMode}`,
-    callback_data: "settings:open:thread-display",
-  });
+    {
+      text: `🧵 Thread display: ${threadDisplayCustom ? "custom" : threadDisplayMode}`,
+      callback_data: "settings:open:thread-display",
+    },
+  );
   if (sectionRegistry) {
     const extensionRows = getTelegramExtensionSettingsRows(sectionRegistry);
     settingsButtons.push(
@@ -406,6 +413,7 @@ export async function openTelegramSettingsMenu<
       deps.isAutomaticThreadCleanupEnabled(),
       deps.getActivityVerbosity(),
       deps.getThreadDisplayMode?.(),
+      deps.isThreadDisplayCustom?.() ?? false,
     ),
   );
   if (messageId === undefined) return;
@@ -424,11 +432,14 @@ function threadDisplayModeLabel(mode: TelegramThreadDisplayMode): string {
   }
 }
 
-export function buildThreadDisplaySettingsReplyMarkup(mode: TelegramThreadDisplayMode): TelegramSettingsMenuReplyMarkup {
+export function buildThreadDisplaySettingsReplyMarkup(
+  mode: TelegramThreadDisplayMode,
+  custom = false,
+): TelegramSettingsMenuReplyMarkup {
   return { inline_keyboard: [
     [{ text: "⬆️ Back", callback_data: "settings:list" }],
     ...(["letters", "names", "directory-title", "directory-snake"] as const).map((value) => [{
-      text: `${mode === value ? "🟢 " : ""}${threadDisplayModeLabel(value)}`,
+      text: `${!custom && mode === value ? "🟢 " : ""}${threadDisplayModeLabel(value)}`,
       callback_data: `settings:set:thread-display:${value}`,
     }]),
   ] };
@@ -565,6 +576,7 @@ export async function updateTelegramSettingsMenuMessage(
       deps.isAutomaticThreadCleanupEnabled(),
       deps.getActivityVerbosity(),
       deps.getThreadDisplayMode?.(),
+      deps.isThreadDisplayCustom?.() ?? false,
     ),
   );
 }
@@ -661,8 +673,8 @@ export async function handleTelegramSettingsMenuCallbackAction(
       return true;
     }
     await deps.updateSettingsMessage(
-      buildThreadDisplaySettingsText(mode),
-      buildThreadDisplaySettingsReplyMarkup(mode),
+      buildThreadDisplaySettingsText(mode, deps.isThreadDisplayCustom?.() ?? false),
+      buildThreadDisplaySettingsReplyMarkup(mode, deps.isThreadDisplayCustom?.() ?? false),
     );
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
@@ -877,6 +889,7 @@ export function createTelegramSettingsMenuRuntime<
           getTimeInjectionMode: deps.getTimeInjectionMode,
           isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
           getThreadDisplayMode: deps.getThreadDisplayMode,
+          isThreadDisplayCustom: deps.isThreadDisplayCustom,
           sendSettingsMenu: (state, text, replyMarkup) =>
             deps.sendInteractiveMessage(
               state.chatId,
@@ -901,6 +914,7 @@ export function createTelegramSettingsMenuRuntime<
           getTimeInjectionMode: deps.getTimeInjectionMode,
           isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
           getThreadDisplayMode: deps.getThreadDisplayMode,
+          isThreadDisplayCustom: deps.isThreadDisplayCustom,
           updateSettingsMessage: (text, replyMarkup) =>
             deps.editInteractiveMessage(
               state.chatId,
@@ -945,6 +959,7 @@ export function createTelegramSettingsMenuRuntime<
         getTimeInjectionMode: deps.getTimeInjectionMode,
         isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
         getThreadDisplayMode: deps.getThreadDisplayMode,
+        isThreadDisplayCustom: deps.isThreadDisplayCustom,
         setThreadDisplayMode: deps.setThreadDisplayMode,
         setDraftPreviewsEnabled: deps.setDraftPreviewsEnabled,
         setAssistantRenderingMode: deps.setAssistantRenderingMode,

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

@@ -138,6 +138,7 @@ export interface PiExtensionApiRuntimePorts {
   getActiveTools: ExtensionAPI["getActiveTools"];
   setActiveTools: ExtensionAPI["setActiveTools"];
   setModel: ExtensionAPI["setModel"];
+  registerCommand: ExtensionAPI["registerCommand"];
 }
 
 export function createExtensionApiRuntimePorts(
@@ -151,6 +152,7 @@ export function createExtensionApiRuntimePorts(
     | "getActiveTools"
     | "setActiveTools"
     | "setModel"
+    | "registerCommand"
   >,
 ): PiExtensionApiRuntimePorts {
   return {
@@ -163,6 +165,7 @@ export function createExtensionApiRuntimePorts(
     getActiveTools: () => api.getActiveTools(),
     setActiveTools: (names) => api.setActiveTools(names),
     setModel: (model) => api.setModel(model),
+    registerCommand: (name, options) => api.registerCommand(name, options),
   };
 }
 

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

@@ -1474,6 +1474,7 @@ export interface TelegramAgentEndAssistantResult {
   text?: string;
   stopReason?: string;
   errorMessage?: string;
+  recoveredFromEarlier?: boolean;
 }
 
 export interface TelegramAgentEndOutboundVoiceReply {
@@ -1592,6 +1593,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   extractAssistant: (
     messages: readonly TMessage[],
   ) => TelegramAgentEndAssistantResult;
+  isRecoveredAssistantAlreadyPublished?: (assistant: TelegramAgentEndAssistantResult) => boolean;
   getFoldQueuedPromptsIntoHistory: () => boolean;
   resetRuntimeState: () => void;
   isSessionActive?: (ctx: TContext) => boolean;
@@ -1736,7 +1738,11 @@ export function createTelegramAgentEndHook<
   ): Promise<void> => {
     if (deps.isSessionActive?.(ctx) === false) return;
     const turn = deps.getActiveTurn();
-    const assistant = assistantOverride ?? (turn ? deps.extractAssistant(event.messages) : {});
+    const extractedAssistant = assistantOverride ?? (turn ? deps.extractAssistant(event.messages) : {});
+    const assistant = extractedAssistant.recoveredFromEarlier &&
+        deps.isRecoveredAssistantAlreadyPublished?.(extractedAssistant)
+      ? { stopReason: extractedAssistant.stopReason }
+      : extractedAssistant;
     const hasPublication = !!assistant.text || assistant.stopReason === "error" || !!turn?.queuedAttachments.length;
     const reservation = turn && !turn.guestQueryId && hasPublication ? deps.reserveActiveTurnDelivery?.() : undefined;
     const scheduleDelivery = reservation?.schedule ?? deps.scheduleActiveTurnDelivery;

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

@@ -191,6 +191,7 @@ export function extractRunAssistantMessage(
   text?: string;
   stopReason?: string;
   errorMessage?: string;
+  recoveredFromEarlier?: boolean;
 } {
   const latest = extractLatestAssistantMessageText(messages);
   if (latest.text || latest.stopReason !== "stop") return latest;
@@ -213,6 +214,7 @@ export function extractRunAssistantMessage(
       stopReason: typeof rawStopReason === "string" ? rawStopReason : undefined,
       errorMessage:
         typeof rawErrorMessage === "string" ? rawErrorMessage : undefined,
+      recoveredFromEarlier: true,
     };
   }
   return latest;

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

@@ -698,6 +698,7 @@ export interface TelegramInboundRouteRuntimeDeps<
   ) => void;
   isIdle: (ctx: TContext) => boolean;
   hasPendingMessages: (ctx: TContext) => boolean;
+  requestNewSession?: (source: unknown) => void;
   compact: (
     ctx: TContext,
     callbacks: { onComplete: () => void; onError: (error: unknown) => void },
@@ -721,6 +722,7 @@ const TELEGRAM_OWNED_CALLBACK_PREFIXES = [
   "compact:",
   "menu:",
   "model:",
+  "new:",
   "queue:",
   "section:",
   "settings:",
@@ -1560,7 +1562,9 @@ export function createTelegramInboundRouteRuntime<
           await deps.callApi("editForumTopic", {
             chat_id: sourceTarget.chatId,
             message_thread_id: sourceTarget.threadId,
-            name: Threads.getTelegramTopicTitleForThreadName(threadName, slot),
+            name:
+              deps.getDisplayTitle?.(sourceTarget) ??
+              Threads.getTelegramTopicTitleForThreadName(threadName, slot),
           });
           assertExecutionCurrent();
         } catch (renameError) {
@@ -1717,7 +1721,9 @@ export function createTelegramInboundRouteRuntime<
           await deps.callApi("editForumTopic", {
             chat_id: sourceTarget.chatId,
             message_thread_id: sourceTarget.threadId,
-            name: Threads.getTelegramTopicTitleForThreadName(threadName, slot),
+            name:
+              deps.getDisplayTitle?.(sourceTarget) ??
+              Threads.getTelegramTopicTitleForThreadName(threadName, slot),
           });
           assertExecutionCurrent();
         } catch (renameError) {
@@ -1966,7 +1972,7 @@ export function createTelegramInboundRouteRuntime<
         await deps.editInteractiveMessage?.(
           chatId,
           dialogMessageId,
-          "<b>✖ Rename cancelled. Returning to normal agent mode.</b>",
+          "<b>✖ Rename cancelled.</b>",
           "html",
           { inline_keyboard: [] },
         );
@@ -2001,6 +2007,42 @@ export function createTelegramInboundRouteRuntime<
       }
       return;
     }
+    const handledByNew =
+      await Commands.handleTelegramNewConfirmationCallback(query, {
+        ctx,
+        answerCallbackQuery: deps.answerCallbackQuery,
+        editInteractiveMessage: deps.editInteractiveMessage ?? (async () => {}),
+        deleteMessage: deps.deleteMessage ?? (async () => {}),
+        runNew: async (newCtx) => {
+          await Commands.handleTelegramNewCommand({
+            isIdle: () => deps.isIdle(newCtx),
+            hasPendingMessages: () => deps.hasPendingMessages(newCtx),
+            hasActiveTelegramTurn: deps.activeTurnRuntime.has,
+            hasDispatchPending: deps.bridgeRuntime.lifecycle.hasDispatchPending,
+            hasQueuedTelegramItems: deps.telegramQueueStore.hasQueuedItems,
+            isCompactionInProgress:
+              deps.bridgeRuntime.lifecycle.isCompactionInProgress,
+            requestNewSession: deps.requestNewSession
+              ? () => deps.requestNewSession!(query)
+              : undefined,
+            sendTextReply: async (text) => {
+              const chatId = query.message?.chat?.id;
+              const messageId = query.message?.message_id;
+              if (typeof chatId !== "number" || typeof messageId !== "number") return;
+              await deps.editInteractiveMessage?.(
+                chatId,
+                messageId,
+                text,
+                "html",
+                { inline_keyboard: [] },
+              );
+            },
+            recordRuntimeEvent: deps.recordRuntimeEvent,
+          });
+        },
+      });
+    assertExecutionCurrent();
+    if (handledByNew) return;
     const handledByCompact =
       await Commands.handleTelegramCompactConfirmationCallback(query, {
         ctx,
@@ -2186,6 +2228,7 @@ export function createTelegramInboundRouteRuntime<
     stopTypingLoop: deps.stopTypingLoop,
     enqueueContinueTurn,
     compact: deps.compact,
+    requestNewSession: deps.requestNewSession,
     allocateItemOrder: deps.bridgeRuntime.queue.allocateItemOrder,
     allocateControlOrder: deps.bridgeRuntime.queue.allocateControlOrder,
     appendControlItem: deps.queueMutationRuntime.append,
@@ -2515,17 +2558,31 @@ export function createTelegramInboundRouteRuntime<
             dialogMessageId: candidate.dialogMessageId,
           });
         }
+        const replyText = result.ok && !result.message
+          ? Commands.formatTelegramAutomaticThreadDisplayNameRestoredHeading(
+            result.threadName ?? name,
+          )
+          : Commands.formatTelegramInformationHeading(
+            result.ok ? "✅" : "⚠️",
+            result.message ?? "Thread display name reset failed.",
+          );
+        if (result.ok) {
+          Updates.assertTelegramUpdateExecutionCurrent(message);
+          Updates.reportTelegramUpdateCompleted(message);
+          void deps.sendTextReply(
+            target.chatId,
+            message.message_id,
+            replyText,
+            { parseMode: "HTML", target },
+          ).catch((error) => deps.recordRuntimeEvent?.("telegram-command", error, {
+            command: "name", phase: "reset-result",
+          }));
+          return true;
+        }
         await deps.sendTextReply(
           target.chatId,
           message.message_id,
-          result.ok && !result.message
-            ? Commands.formatTelegramAutomaticThreadDisplayNameRestoredHeading(
-              result.threadName ?? name,
-            )
-            : Commands.formatTelegramInformationHeading(
-              result.ok ? "✅" : "⚠️",
-              result.message ?? "Thread display name reset failed.",
-            ),
+          replyText,
           { parseMode: "HTML", target },
         );
         return true;
@@ -2557,17 +2614,31 @@ export function createTelegramInboundRouteRuntime<
           dialogMessageId: candidate.dialogMessageId,
         });
       }
+      const replyText = result?.ok && !result.message
+        ? Commands.formatTelegramThreadDisplayNameSavedHeading(
+          result.threadName ?? consumed.name,
+        )
+        : Commands.formatTelegramInformationHeading(
+          result?.ok ? "✅" : "⚠️",
+          result?.message ?? "Thread display name update failed.",
+        );
+      if (result?.ok) {
+        Updates.assertTelegramUpdateExecutionCurrent(message);
+        Updates.reportTelegramUpdateCompleted(message);
+        void deps.sendTextReply(
+          target.chatId,
+          message.message_id,
+          replyText,
+          { parseMode: "HTML", target },
+        ).catch((error) => deps.recordRuntimeEvent?.("telegram-command", error, {
+          command: "name", phase: "rename-result",
+        }));
+        return true;
+      }
       await deps.sendTextReply(
         target.chatId,
         message.message_id,
-        result?.ok && !result.message
-          ? Commands.formatTelegramThreadDisplayNameSavedHeading(
-            result.threadName ?? consumed.name,
-          )
-          : Commands.formatTelegramInformationHeading(
-            result?.ok ? "✅" : "⚠️",
-            result?.message ?? "Thread display name update failed.",
-          ),
+        replyText,
         { parseMode: "HTML", target },
       );
       return true;

package/node_modules/@llblab/pi-telegram/lib/thread-display.ts

@@ -239,6 +239,36 @@ export interface TelegramThreadDisplayReconcilerDeps {
   ): Promise<TResponse>;
 }
 
+export function createTelegramThreadDisplaySettingsRuntime(deps: {
+  getTarget(): { chatId: number; threadId?: number } | undefined;
+  getBinding(target: { chatId: number; threadId?: number }):
+    { manualThreadName?: string } | undefined;
+  apply(mode: TelegramThreadDisplayMode): Promise<void>;
+  reset(target: { chatId: number; threadId?: number }):
+    Promise<{ ok: boolean; message?: string }>;
+}): {
+  isCustom(): boolean;
+  setMode(mode: TelegramThreadDisplayMode): Promise<void>;
+} {
+  return {
+    isCustom() {
+      const target = deps.getTarget();
+      return !!target && typeof deps.getBinding(target)?.manualThreadName === "string";
+    },
+    async setMode(mode) {
+      const target = deps.getTarget();
+      const hadManualName = !!target &&
+        typeof deps.getBinding(target)?.manualThreadName === "string";
+      await deps.apply(mode);
+      if (!hadManualName || !target) return;
+      const reset = await deps.reset(target);
+      if (!reset.ok) {
+        throw new Error(reset.message ?? "Telegram Thread display override reset failed.");
+      }
+    },
+  };
+}
+
 /** Caller owns triggering and reporting; no timer or background retry is created. */
 export function createTelegramThreadDisplayReconciler(
   deps: TelegramThreadDisplayReconcilerDeps,