@llblab/pi-kit 0.15.0 → 0.16.0

package/node_modules/@llblab/pi-telegram/dist/lib/commands.js

@@ -1,7 +1,7 @@
 /**
  * Telegram command routing helpers
  * Zones: telegram controls, pi agent commands, queue controls
- * Owns Telegram slash-command normalization, bot command metadata, and pi-side command registration behind runtime ports
+ * Owns Telegram slash-command normalization, bot command metadata, pi-side command registration, and command-initiated session replacement orchestration behind runtime ports
  */
 import { pairTelegramUserIfNeeded, TELEGRAM_DEFAULT_PROFILE_NAME, } from "./config.js";
 import { escapeHtml } from "./rendering.js";
@@ -89,6 +89,7 @@ export const TELEGRAM_COMMAND_EMOJI = {
     abort: "⏹️",
     stop: "🟥",
     name: "🏷️",
+    new: "🆕",
 };
 export function getTelegramCommandEmoji(command) {
     return TELEGRAM_COMMAND_EMOJI[command];
@@ -133,22 +134,22 @@ export const TELEGRAM_BUILTIN_BOT_COMMANDS = [
         command: "start",
         description: formatTelegramBotCommandDescription("start", "Open menu / Pair bridge"),
     },
-    {
-        command: "name",
-        description: formatTelegramBotCommandDescription("name", "Rename this thread"),
-    },
     {
         command: "compact",
         description: formatTelegramBotCommandDescription("compact", "Compact current session"),
     },
     {
-        command: "next",
-        description: formatTelegramBotCommandDescription("next", "Force next turn"),
+        command: "new",
+        description: formatTelegramBotCommandDescription("new", "Start a new session"),
     },
     {
         command: "continue",
         description: formatTelegramBotCommandDescription("continue", "Queue continue prompt"),
     },
+    {
+        command: "next",
+        description: formatTelegramBotCommandDescription("next", "Force next turn"),
+    },
     {
         command: "abort",
         description: formatTelegramBotCommandDescription("abort", "Abort Pi"),
@@ -179,15 +180,15 @@ export async function registerTelegramBotCommands(deps) {
         await deps.setMyCommands(TELEGRAM_BOT_COMMANDS);
         return;
     }
-    const compactCommandIndex = TELEGRAM_BOT_COMMANDS.findIndex((command) => command.command === "compact");
-    if (compactCommandIndex === -1) {
+    const nextCommandIndex = TELEGRAM_BOT_COMMANDS.findIndex((command) => command.command === "next");
+    if (nextCommandIndex === -1) {
         await deps.setMyCommands([...TELEGRAM_BOT_COMMANDS, ...extensionCommands]);
         return;
     }
     await deps.setMyCommands([
-        ...TELEGRAM_BOT_COMMANDS.slice(0, compactCommandIndex + 1),
+        ...TELEGRAM_BOT_COMMANDS.slice(0, nextCommandIndex + 1),
         ...extensionCommands,
-        ...TELEGRAM_BOT_COMMANDS.slice(compactCommandIndex + 1),
+        ...TELEGRAM_BOT_COMMANDS.slice(nextCommandIndex + 1),
     ]);
 }
 export function createTelegramBotCommandRegistrar(deps) {
@@ -412,6 +413,7 @@ export function registerTelegramBridgeCommands(pi, deps) {
 export const TELEGRAM_RESERVED_COMMAND_NAMES = [
     "stop",
     "name",
+    "new",
     "abort",
     "next",
     "continue",
@@ -529,10 +531,10 @@ export const TELEGRAM_APP_MENU_INTRO_HTML = [
     "<b>Pi Telegram</b>",
     "",
     `${formatTelegramCommandEmojiPrefix("start")}/start — Open menu / Pair bridge`,
-    `${formatTelegramCommandEmojiPrefix("name")}/name — Rename this thread`,
     `${formatTelegramCommandEmojiPrefix("compact")}/compact — Compact current session`,
-    `${formatTelegramCommandEmojiPrefix("next")}/next — Force next turn`,
+    `${formatTelegramCommandEmojiPrefix("new")}/new — Start a new session`,
     `${formatTelegramCommandEmojiPrefix("continue")}/continue — Queue continue prompt`,
+    `${formatTelegramCommandEmojiPrefix("next")}/next — Force next turn`,
     `${formatTelegramCommandEmojiPrefix("abort")}/abort — Abort Pi`,
     `${formatTelegramCommandEmojiPrefix("stop")}/stop — Abort Pi & Clear queue`,
 ].join("\n");
@@ -567,11 +569,11 @@ function buildTelegramAppMenuIntroHtml() {
         "<b>Pi Telegram</b>",
         "",
         `${formatTelegramCommandEmojiPrefix("start")}/start — Open menu / Pair bridge`,
-        `${formatTelegramCommandEmojiPrefix("name")}/name — Rename this thread`,
         `${formatTelegramCommandEmojiPrefix("compact")}/compact — Compact current session`,
-        ...extensionLines,
-        `${formatTelegramCommandEmojiPrefix("next")}/next — Force next turn`,
+        `${formatTelegramCommandEmojiPrefix("new")}/new — Start a new session`,
         `${formatTelegramCommandEmojiPrefix("continue")}/continue — Queue continue prompt`,
+        `${formatTelegramCommandEmojiPrefix("next")}/next — Force next turn`,
+        ...extensionLines,
         `${formatTelegramCommandEmojiPrefix("abort")}/abort — Abort Pi`,
         `${formatTelegramCommandEmojiPrefix("stop")}/stop — Abort Pi & Clear queue`,
     ].join("\n");
@@ -623,6 +625,7 @@ export function parseTelegramCommand(text) {
 export const TELEGRAM_COMMAND_ACTIONS = {
     stop: { kind: "stop", executionMode: "immediate" },
     name: { kind: "name", executionMode: "immediate" },
+    new: { kind: "new", executionMode: "immediate" },
     abort: { kind: "abort", executionMode: "immediate" },
     next: { kind: "next", executionMode: "immediate" },
     continue: { kind: "continue", executionMode: "immediate" },
@@ -709,6 +712,43 @@ function dispatchNextQueuedTelegramTurnAfterCompact(deps) {
     }
     deps.dispatchNextQueuedTelegramTurn();
 }
+export function buildTelegramNewConfirmationReplyMarkup() {
+    return {
+        inline_keyboard: [
+            [
+                { text: "🆕 Yes, start new", callback_data: "new:confirm" },
+                { text: "❌ No", callback_data: "new:cancel" },
+            ],
+        ],
+    };
+}
+export function getTelegramNewConfirmationHtml() {
+    return "<b>Start a new session?</b>";
+}
+export async function openTelegramNewConfirmation(target, deps) {
+    await deps.sendInteractiveMessage(target.chatId, getTelegramNewConfirmationHtml(), "html", buildTelegramNewConfirmationReplyMarkup(), target.threadId !== undefined
+        ? { target: { chatId: target.chatId, threadId: target.threadId } }
+        : undefined);
+}
+export async function handleTelegramNewConfirmationCallback(query, deps) {
+    if (query.data !== "new:confirm" && query.data !== "new:cancel")
+        return false;
+    const chatId = query.message?.chat?.id;
+    const messageId = query.message?.message_id;
+    if (typeof chatId !== "number" || typeof messageId !== "number") {
+        await deps.answerCallbackQuery(query.id, "⌛ Interactive message expired.");
+        return true;
+    }
+    if (query.data === "new:cancel") {
+        await deps.editInteractiveMessage(chatId, messageId, "<b>🚫 New session cancelled.</b>", "html", { inline_keyboard: [] });
+        await deps.answerCallbackQuery(query.id);
+        return true;
+    }
+    await deps.answerCallbackQuery(query.id);
+    await deps.deleteMessage(chatId, messageId);
+    await deps.runNew(deps.ctx);
+    return true;
+}
 export function buildTelegramCompactConfirmationReplyMarkup() {
     return {
         inline_keyboard: [
@@ -749,6 +789,22 @@ export async function handleTelegramCompactConfirmationCallback(query, deps) {
     await deps.runCompact(deps.ctx, chatId, messageId, typeof threadId === "number" ? { chatId, threadId } : { chatId });
     return true;
 }
+export async function handleTelegramNewCommand(deps) {
+    if (!deps.isIdle() ||
+        deps.hasPendingMessages() ||
+        deps.hasActiveTelegramTurn() ||
+        deps.hasDispatchPending() ||
+        deps.hasQueuedTelegramItems() ||
+        deps.isCompactionInProgress()) {
+        await deps.sendTextReply(formatTelegramInformationHeading("⏳", "Cannot start a new session while Pi or the Telegram queue is busy. Wait for queued turns to finish or send /abort first."), { parseMode: "HTML" });
+        return;
+    }
+    if (!deps.requestNewSession) {
+        await deps.sendTextReply(formatTelegramInformationHeading("🚫", "Session replacement is unavailable in this Pi runtime."), { parseMode: "HTML" });
+        return;
+    }
+    deps.requestNewSession();
+}
 export async function handleTelegramCompactCommand(deps) {
     if (!deps.isIdle() ||
         deps.hasPendingMessages() ||
@@ -830,6 +886,9 @@ export async function executeTelegramCommandAction(action, message, ctx, deps, c
         case "name":
             await deps.handleName(message, ctx, commandArgs);
             return true;
+        case "new":
+            await deps.handleNew(message, ctx);
+            return true;
         case "abort":
             await deps.handleAbort(message, ctx);
             return true;
@@ -900,6 +959,7 @@ export function createTelegramCommandHandlerTargetRuntime(deps) {
         stopTypingLoop: deps.stopTypingLoop,
         enqueueContinueTurn: deps.enqueueContinueTurn,
         compact: deps.compact,
+        requestNewSession: deps.requestNewSession,
         sendInteractiveMessage: deps.sendInteractiveMessage,
         enqueueControlItem: commandTargetRuntime.enqueueControlItem,
         showStatus: commandTargetRuntime.showStatus,
@@ -1075,6 +1135,25 @@ async function handleTelegramCommandRuntime(commandName, message, ctx, deps, com
         handleQueue: async (nextMessage, commandCtx) => {
             scheduleTelegramCommandEffect(commandCtx, "queue", "menu-render", deps, () => deps.openQueueMenu(nextMessage, commandCtx), assertExecutionCurrentFor(nextMessage));
         },
+        handleNew: async (nextMessage, commandCtx) => {
+            if (deps.sendInteractiveMessage) {
+                await openTelegramNewConfirmation(getTelegramCommandMessageTarget(nextMessage), { sendInteractiveMessage: deps.sendInteractiveMessage });
+                return;
+            }
+            await handleTelegramNewCommand({
+                isIdle: () => deps.isIdle(commandCtx),
+                hasPendingMessages: () => deps.hasPendingMessages(commandCtx),
+                hasActiveTelegramTurn: deps.hasActiveTelegramTurn,
+                hasDispatchPending: deps.hasDispatchPending,
+                hasQueuedTelegramItems: deps.hasQueuedTelegramItems,
+                isCompactionInProgress: deps.isCompactionInProgress,
+                requestNewSession: deps.requestNewSession
+                    ? () => deps.requestNewSession(nextMessage)
+                    : undefined,
+                sendTextReply: sendReplyFor(nextMessage),
+                recordRuntimeEvent: deps.recordRuntimeEvent,
+            });
+        },
         handleCompact: async (nextMessage, commandCtx) => {
             if (deps.sendInteractiveMessage) {
                 await openTelegramCompactConfirmation(getTelegramCommandMessageTarget(nextMessage), { sendInteractiveMessage: deps.sendInteractiveMessage });
@@ -1153,3 +1232,205 @@ async function handleTelegramCommandRuntime(commandName, message, ctx, deps, com
         },
     }, commandArgs);
 }
+export const TELEGRAM_SESSION_ACTION_COMMAND_NAME = "telegram-session-action";
+export const TELEGRAM_SESSION_ACTION_COMMAND_DESCRIPTION = "(internal) replace the current Pi session after Telegram settlement";
+export function delayTelegramSessionAction(delayMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+export async function settleTelegramSessionReplacement(deps) {
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+    while (deps.isCurrent?.() !== false) {
+        const intent = await deps.getIntent();
+        if (!intent || intent.sourceSessionId === deps.sessionId)
+            return "none";
+        if (intent.profileName !== deps.profileName || intent.cwd !== deps.cwd)
+            return "stale";
+        if (now() >= intent.expiresAtMs)
+            return "expired";
+        if (!deps.hasSuccessorContinuity(intent)) {
+            await sleep(100);
+            continue;
+        }
+        if (!await deps.clearIntent(intent))
+            return "failed";
+        do {
+            const delivered = await deps.editSuccess(intent);
+            if (delivered.ok)
+                return "settled";
+            if (!delivered.retryable)
+                return "failed";
+            await sleep(100);
+        } while (deps.isCurrent?.() !== false && now() < intent.expiresAtMs);
+        return "failed";
+    }
+    return "stale";
+}
+export function createTelegramSessionReplacementSettlementRuntime(deps) {
+    let generation = 0;
+    return {
+        onSessionStart(ctx) {
+            const currentGeneration = ++generation;
+            const resolved = deps.resolve(ctx);
+            if (!resolved)
+                return;
+            void settleTelegramSessionReplacement({
+                ...resolved,
+                isCurrent: () => currentGeneration === generation &&
+                    resolved.isCurrent?.() !== false,
+            }).then(deps.onResult, deps.onError);
+        },
+    };
+}
+export function createTelegramSessionActionAssembly(deps) {
+    const now = deps.now ?? Date.now;
+    const report = (error) => deps.recordRuntimeEvent?.("new-session", error);
+    const sendTerminalResult = async (target, result) => {
+        const text = result === "success" ? "<b>🆕 New session started.</b>"
+            : result === "cancelled" ? "<b>🚫 New session cancelled.</b>"
+                : "<b>⚠️ New session failed.</b>";
+        const deadline = now() + 10_000;
+        do {
+            const delivery = await deps.sendResult(target, text);
+            if (delivery.ok)
+                return;
+            if (!delivery.retryable)
+                break;
+            await delayTelegramSessionAction(100);
+        } while (now() < deadline);
+        report(new Error("Telegram new-session result delivery failed."));
+    };
+    const action = createTelegramSessionActionRuntime({
+        registerCommand: deps.registerCommand,
+        sendUserMessage: deps.sendUserMessage,
+        notifyResult(target, result) { return sendTerminalResult(target, result); },
+        async prepareReplacement(ctx, updateId, target) {
+            await deps.store.load();
+            const sessionId = ctx.sessionManager.getSessionId();
+            const binding = typeof target.threadId === "number"
+                ? deps.store.getWorkspaceBindingByTarget(target)
+                : undefined;
+            if (typeof target.threadId === "number" &&
+                (!binding || binding.cwd !== ctx.cwd || binding.sessionId !== sessionId)) {
+                throw new Error("Telegram session replacement binding is unavailable.");
+            }
+            const createdAtMs = now();
+            if (!await deps.store.commitSessionReplacementIntent({
+                continuity: binding ? "workspace-thread" : "classic-chat",
+                cwd: binding?.cwd ?? ctx.cwd,
+                profileName: deps.getProfileName() ?? "default",
+                sourceSessionId: sessionId,
+                sourceUpdateId: updateId,
+                target: binding ? { ...binding.target } : { chatId: target.chatId },
+                messageId: target.messageId,
+                ...(binding?.slot ? { slot: binding.slot } : {}),
+                ...(binding?.manualThreadName ?? binding?.threadName
+                    ? { threadName: binding.manualThreadName ?? binding.threadName } : {}),
+                createdAtMs,
+                expiresAtMs: createdAtMs + deps.handoffTtlMs,
+            }, deps.ownsPersistence)) {
+                throw new Error("Telegram session replacement intent was not persisted.");
+            }
+        },
+        recordRuntimeEvent: deps.recordRuntimeEvent,
+    });
+    const settlement = createTelegramSessionReplacementSettlementRuntime({
+        resolve(ctx) {
+            const sessionId = ctx.sessionManager?.getSessionId?.();
+            if (!sessionId)
+                return undefined;
+            return {
+                async getIntent() { await deps.store.refresh?.(); return deps.store.getSessionReplacementIntent(); },
+                hasSuccessorContinuity(intent) {
+                    return intent.continuity === "classic-chat" ||
+                        deps.store.getWorkspaceBindingByTarget(intent.target, sessionId)?.cwd === intent.cwd;
+                },
+                editSuccess(intent) { return deps.sendResult(intent.target, "<b>🆕 New session started.</b>"); },
+                clearIntent(intent) { return deps.store.removeSessionReplacementIntent(intent, deps.ownsPersistence); },
+                profileName: deps.getProfileName() ?? "default",
+                cwd: ctx.cwd,
+                sessionId,
+            };
+        },
+        onResult(result) {
+            if (result === "expired" || result === "failed") {
+                report(new Error(`Telegram session replacement successor settlement ${result}.`));
+            }
+        },
+        onError: report,
+    });
+    return { action, settlement };
+}
+export function createTelegramSessionActionRuntime(deps) {
+    let pendingUpdateId;
+    let pendingTarget;
+    let commandPending = false;
+    let commandUpdateId;
+    let registered = false;
+    const reportFailure = (error) => {
+        try {
+            deps.recordRuntimeEvent?.("new-session", error);
+        }
+        catch {
+            // Diagnostics cannot make a completed durable update retryable.
+        }
+    };
+    return {
+        register() {
+            if (registered)
+                return;
+            registered = true;
+            deps.registerCommand(TELEGRAM_SESSION_ACTION_COMMAND_NAME, {
+                description: TELEGRAM_SESSION_ACTION_COMMAND_DESCRIPTION,
+                handler: async (_args, ctx) => {
+                    if (!commandPending)
+                        return;
+                    commandPending = false;
+                    const target = pendingTarget;
+                    const updateId = commandUpdateId;
+                    pendingTarget = undefined;
+                    commandUpdateId = undefined;
+                    if (!target || updateId === undefined)
+                        return;
+                    try {
+                        await deps.prepareReplacement?.(ctx, updateId, target);
+                        const result = await ctx.newSession();
+                        if (result.cancelled)
+                            await deps.notifyResult(target, "cancelled");
+                    }
+                    catch (error) {
+                        reportFailure(error);
+                        await deps.notifyResult(target, "failure");
+                    }
+                },
+            });
+        },
+        scheduleAfterUpdate(updateId, target) {
+            if (pendingUpdateId !== undefined || commandPending)
+                return false;
+            pendingUpdateId = updateId;
+            pendingTarget = { ...target };
+            return true;
+        },
+        onUpdateCompleted(updateId) {
+            if (pendingUpdateId !== updateId)
+                return;
+            pendingUpdateId = undefined;
+            commandUpdateId = updateId;
+            commandPending = true;
+            void Promise.resolve()
+                .then(() => deps.sendUserMessage(`/${TELEGRAM_SESSION_ACTION_COMMAND_NAME}`, {
+                expandPromptTemplates: true,
+            }))
+                .catch((error) => {
+                commandPending = false;
+                commandUpdateId = undefined;
+                pendingTarget = undefined;
+                reportFailure(error);
+            });
+        },
+        hasPending() {
+            return pendingUpdateId !== undefined || commandPending;
+        },
+    };
+}

package/node_modules/@llblab/pi-telegram/dist/lib/delivery.d.ts

@@ -156,6 +156,8 @@ export declare function clearTelegramDeliveryRuntime(): void;
 /** @internal */
 export declare function isTelegramDeliveryHandleCurrent(handle: TelegramDeliveryHandle): boolean;
 export declare function sendTelegramView(view: TelegramDeliveryView, options: SendTelegramViewOptions): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
+/** @internal Edit an exact Telegram message through the currently bound runtime generation. */
+export declare function editTelegramTargetView(target: TelegramDeliveryTarget, messageId: number, view: TelegramDeliveryView): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
 export declare function editTelegramView(handle: TelegramDeliveryHandle, view: TelegramDeliveryView): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
 export declare function deleteTelegramView(handle: TelegramDeliveryHandle): Promise<TelegramDeliveryResult<void>>;
 export declare function sendTelegramChatAction(action: TelegramDeliveryChatAction, options: {

package/node_modules/@llblab/pi-telegram/dist/lib/delivery.js

@@ -518,6 +518,17 @@ export async function sendTelegramView(view, options) {
         return invalid;
     return runDeliveryOperation((runtime) => runtime.sendView(view, options));
 }
+/** @internal Edit an exact Telegram message through the currently bound runtime generation. */
+export async function editTelegramTargetView(target, messageId, view) {
+    const invalid = validateView(view);
+    if (invalid)
+        return invalid;
+    return runDeliveryOperation((runtime) => runtime.editView({
+        target: { ...target },
+        messageIds: [messageId],
+        generation: runtime.generation,
+    }, view));
+}
 export async function editTelegramView(handle, view) {
     const invalid = validateView(view);
     if (invalid)

package/node_modules/@llblab/pi-telegram/dist/lib/extension.js

@@ -65,7 +65,7 @@ const telegramBusProtocolIdentity = Bus.createTelegramCurrentBusProtocolIdentity
 export default function (pi) {
     Skills.registerTelegramSkillDiscovery(pi);
     const piRuntime = Pi.createExtensionApiRuntimePorts(pi);
-    const { getActiveTools, getCommands, getThinkingLevel, sendUserMessage, setActiveTools, setModel, setThinkingLevel, } = piRuntime;
+    const { getActiveTools, getCommands, getThinkingLevel, sendUserMessage, registerCommand, setActiveTools, setModel, setThinkingLevel, } = piRuntime;
     const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
     const runtimeDiagnostics = Logging.createTelegramRuntimeDiagnosticsRuntime();
     const runtimeEvents = runtimeDiagnostics.events;
@@ -185,6 +185,23 @@ export default function (pi) {
         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;
     const telegramSessionContextStore = Lifecycle.createTelegramSessionContextStore({
@@ -673,6 +690,23 @@ export default function (pi) {
         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,
         getModelMenuState: getQueueMenuState,
@@ -687,15 +721,10 @@ export default function (pi) {
             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,
-                });
+                await threadDisplaySettingsRuntime.setMode(mode);
             }
             catch (error) {
                 recordRuntimeEvent("bus", error, { phase: "thread-display-setting" });
@@ -767,6 +796,32 @@ export default function (pi) {
         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.message
+                : source;
+            const messageTarget = callbackMessage;
+            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,
@@ -856,6 +911,7 @@ export default function (pi) {
             isContextCurrent: telegramSessionContextStore.isCurrent,
             dispatchNext: dispatchNextQueuedTelegramTurn,
             requestQueueHandoffReconciliation: queueHandoffReconciliationBinding.request,
+            afterUpdateCompleted: sessionActionsRuntime.onUpdateCompleted,
         },
         worker: {
             defaultHandle: inboundRouteRuntime.handleUpdate,
@@ -1366,6 +1422,7 @@ export default function (pi) {
             }
         },
     }.reset);
+    sessionActionsRuntime.register();
     Bindings.registerTelegramCommandsAndTools({
         pi,
         agentDir: Paths.resolveAgentDir(),
@@ -1566,6 +1623,9 @@ export default function (pi) {
         disconnectOnQuit: cleanupTelegramThreadForSessionRestart,
         shutdownGenerativeAppLiveSurfaces: generativeAppLiveSurfaceBinding.shutdown,
         resolveAutomaticThreadCleanupEnabled: configControls.resolveAutomaticThreadCleanupEnabled,
+        onSessionStarted(_event, ctx) {
+            sessionActionAssembly.settlement.onSessionStart(ctx);
+        },
         buttonActionStore,
         callMultipart,
         sendChatAction,

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

@@ -12,6 +12,7 @@ import type { TelegramVoiceReplyMode } from "./voice.ts";
 export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 export interface TelegramSettingsStateDeps {
     getThreadDisplayMode?: () => TelegramThreadDisplayMode | undefined;
+    isThreadDisplayCustom?: () => boolean;
     areDraftPreviewsEnabled: () => boolean;
     getAssistantRenderingMode: () => TelegramAssistantRenderingMode;
     getActivityVerbosity: () => TelegramActivityVerbosity;
@@ -86,7 +87,7 @@ export declare const TIME_INJECTION_MODE_SETTINGS_TITLE = "<b>\uD83D\uDD52 Time
 export declare const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>\uD83D\uDC44 Voice reply mode:</b>";
 export declare const THREAD_DISPLAY_SETTINGS_TITLE = "<b>\uD83E\uDDF5 Thread display:</b>";
 export declare function buildTelegramSettingsMenuText(): string;
-export declare function buildThreadDisplaySettingsText(mode: TelegramThreadDisplayMode): string;
+export declare function buildThreadDisplaySettingsText(mode: TelegramThreadDisplayMode, custom?: boolean): string;
 export declare function buildAutomaticThreadCleanupSettingsText(enabled: boolean): string;
 export declare function buildInactiveThreadReviewText(count: number): string;
 export declare function buildInactiveThreadReviewReplyMarkup(operationId?: string, canCleanInactiveThreads?: boolean): TelegramSettingsMenuReplyMarkup;
@@ -95,9 +96,9 @@ export declare function buildAssistantRenderingSettingsText(mode: TelegramAssist
 export declare function buildActivityVerbositySettingsText(verbosity: TelegramActivityVerbosity): string;
 export declare function buildVoiceReplyModeSettingsText(mode: TelegramVoiceReplyMode, configured?: boolean): string;
 export declare function buildTimeInjectionModeSettingsText(mode: TelegramTimeMode): string;
-export declare function buildTelegramSettingsMenuReplyMarkup(draftPreviewsEnabled: boolean, assistantRenderingModeOrVoiceReplyMode: TelegramAssistantRenderingMode | TelegramVoiceReplyMode, voiceReplyModeOrTimeInjectionMode: TelegramVoiceReplyMode | TelegramTimeMode, timeInjectionModeOrSectionRegistry?: TelegramTimeMode | TelegramSectionRegistry, sectionRegistryOrVoiceReplyModeConfigured?: TelegramSectionRegistry | boolean, voiceReplyModeConfigured?: boolean, automaticThreadCleanupEnabled?: boolean, activityVerbosity?: TelegramActivityVerbosity, threadDisplayMode?: TelegramThreadDisplayMode): TelegramSettingsMenuReplyMarkup;
+export declare function buildTelegramSettingsMenuReplyMarkup(draftPreviewsEnabled: boolean, assistantRenderingModeOrVoiceReplyMode: TelegramAssistantRenderingMode | TelegramVoiceReplyMode, voiceReplyModeOrTimeInjectionMode: TelegramVoiceReplyMode | TelegramTimeMode, timeInjectionModeOrSectionRegistry?: TelegramTimeMode | TelegramSectionRegistry, sectionRegistryOrVoiceReplyModeConfigured?: TelegramSectionRegistry | boolean, voiceReplyModeConfigured?: boolean, automaticThreadCleanupEnabled?: boolean, activityVerbosity?: TelegramActivityVerbosity, threadDisplayMode?: TelegramThreadDisplayMode, threadDisplayCustom?: boolean): TelegramSettingsMenuReplyMarkup;
 export declare function openTelegramSettingsMenu<TModel extends MenuModel = MenuModel>(deps: TelegramSettingsMenuOpenDeps<TModel>, sectionRegistry?: TelegramSectionRegistry): Promise<void>;
-export declare function buildThreadDisplaySettingsReplyMarkup(mode: TelegramThreadDisplayMode): TelegramSettingsMenuReplyMarkup;
+export declare function buildThreadDisplaySettingsReplyMarkup(mode: TelegramThreadDisplayMode, custom?: boolean): TelegramSettingsMenuReplyMarkup;
 export declare function buildAutomaticThreadCleanupSettingsReplyMarkup(enabled: boolean, canReviewInactiveThreads?: boolean): TelegramSettingsMenuReplyMarkup;
 export declare function buildDraftPreviewsSettingsReplyMarkup(enabled: boolean): TelegramSettingsMenuReplyMarkup;
 export declare function buildAssistantRenderingSettingsReplyMarkup(mode: TelegramAssistantRenderingMode): TelegramSettingsMenuReplyMarkup;