@llblab/pi-telegram 0.55.1 → 0.56.1

package/dist/lib/bus.js

@@ -50,6 +50,9 @@ export function createTelegramBusAuthSecret() {
 const TELEGRAM_BUS_PROTOCOL_VERSION = 3;
 export const TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION = "durable-follower-admission-v1";
 export const TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF = "queue-handoff-v1";
+/** Unspent Steer lane codec; independent from baseline receipt handoff support. */
+export const TELEGRAM_BUS_CAPABILITY_QUEUE_STEER = "queue-steer-v1";
+export const TELEGRAM_BUS_CAPABILITY_CONNECT_RECOVERY = "explicit-connect-recovery-v1";
 export const TELEGRAM_BUS_CAPABILITY_INPUT_CUSTODY_REFERENCE = "input-custody-reference-v1";
 export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME = "workspace-thread-rename-v1";
 export const TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE = "thread-display-mode-v1";
@@ -77,6 +80,13 @@ export const TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES = [
     TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_COMMAND_SET,
     TELEGRAM_BUS_CAPABILITY_SELECTED_MENU_DELIVERY,
 ];
+/** Start/help are restricted menu aliases, negotiated separately from the original held-command set. */
+export const TELEGRAM_BUS_CAPABILITY_HELD_MENU_ALIASES = "held-menu-aliases-v1";
+export function getTelegramBusHeldCommandCapabilities(name) {
+    return name === "start" || name === "help"
+        ? [...TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES, TELEGRAM_BUS_CAPABILITY_HELD_MENU_ALIASES]
+        : TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES;
+}
 function parseSelectedCommandInput(value) {
     if (!isRecord(value) ||
         !hasOnlyWireKeys(value, ["name", "target"]) ||
@@ -173,6 +183,10 @@ export function createTelegramCurrentBusProtocolIdentity(capabilities = []) {
 export function hasTelegramBusCapability(identity, capability) {
     return identity?.capabilities.includes(capability) ?? false;
 }
+export function hasTelegramBusSteerQueueHandoffCapability(identity) {
+    return hasTelegramBusCapability(identity, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF) &&
+        hasTelegramBusCapability(identity, TELEGRAM_BUS_CAPABILITY_QUEUE_STEER);
+}
 export function getTelegramInputCustodyPeerReadiness(followers) {
     return followers.map((follower) => {
         if (!follower.registrationGeneration || !follower.protocol)
@@ -1310,12 +1324,7 @@ export function createTelegramBusLiveRebindController(deps) {
                 : []),
             ...(settling || held ? [TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_SETTLE] : []),
             ...(observingHeld ? [TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND_EXECUTION] : []),
-            ...(held
-                ? [
-                    TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_COMMAND_SET,
-                    TELEGRAM_BUS_CAPABILITY_SELECTED_MENU_DELIVERY,
-                ]
-                : []),
+            ...(held ? getTelegramBusHeldCommandCapabilities(held.name) : []),
         ];
         const follower = deps.getFollower(expected.instanceId), secret = deps.getAuthSecret();
         if (!isCurrent() ||
@@ -2138,8 +2147,13 @@ async function handleTelegramBusSocketLine(line, socket, handleEnvelope, recordT
     }
 }
 function parseRegisterEnvelope(value, requestId, kind) {
+    if (value.recoverConnection !== undefined &&
+        (kind !== "follower.register" || value.recoverConnection !== true))
+        return undefined;
     const registration = parseRegistration(value.registration);
-    return registration ? { kind, requestId, registration } : undefined;
+    return registration ? { kind, requestId, registration,
+        ...(kind === "follower.register" && value.recoverConnection === true ? { recoverConnection: true } : {}),
+    } : undefined;
 }
 function parseFollowerPresenceEnvelope(value, requestId, kind) {
     return typeof value.instanceId === "string" &&

package/dist/lib/commands.d.ts

@@ -13,7 +13,7 @@ import { type TelegramBridgeStatusLineOptions } from "./status.ts";
 import { type TelegramApiCallOptions } from "./telegram-api.ts";
 import type { TelegramSessionReplacementIntent } from "./threads.ts";
 import { type TelegramDeferredSourceEvidence, type TelegramLiveSourceCompletionReadiness, type TelegramQueueAdmissionReceiptLike } from "./updates.ts";
-export type TelegramHeldCommandName = "status" | "abort" | "stop" | "next" | "continue";
+export type TelegramHeldCommandName = "status" | "start" | "help" | "abort" | "stop" | "next" | "continue";
 /** Commands-owned no-fold admission over the ordinary recipient queue; source reporting stays separate from removal. */
 export interface TelegramHeldTurnAdmission {
     assertCurrent(): void;

package/dist/lib/commands.js

@@ -1446,35 +1446,40 @@ export function createTelegramCommandHandler(deps) {
             },
         };
     };
-    const heldPlans = {
-        status: {
-            completion: "before-effect",
-            effect: "showStatus",
-            prepare(ctx, effects) {
-                const scopedStatus = effects?.showStatus;
-                const captured = {
-                    ...deps,
-                    showStatus: scopedStatus
-                        ? (message, context, options) => {
-                            const address = getTelegramCommandMessageTarget(message);
-                            return scopedStatus.call(effects, address.chatId, address.replyToMessageId, context, address.threadId, options);
-                        }
-                        : deps.showStatus,
-                };
-                return {
-                    captured,
-                    portsCurrent: () => !effects || effects.showStatus === scopedStatus,
-                    async run({ message, command, assertRecipient }) {
-                        const recipientOptions = { assertAuthority: assertRecipient };
-                        return handleTelegramCommandRuntime(command.name, message, ctx, {
-                            ...captured,
-                            assertExecutionCurrent: assertRecipient,
-                            showStatus: (value, context) => captured.showStatus(value, context, recipientOptions),
-                        }, command.args);
-                    },
-                };
-            },
+    // Held followers are already paired and bound. Start/help open the same restricted menu as status;
+    // they cannot pair an operator, bootstrap another Thread or invoke unrestricted Bot API effects.
+    const heldMenuPlan = {
+        completion: "before-effect",
+        effect: "showStatus",
+        prepare(ctx, effects) {
+            const scopedStatus = effects?.showStatus;
+            const captured = {
+                ...deps,
+                showStatus: scopedStatus
+                    ? (message, context, options) => {
+                        const address = getTelegramCommandMessageTarget(message);
+                        return scopedStatus.call(effects, address.chatId, address.replyToMessageId, context, address.threadId, options);
+                    }
+                    : deps.showStatus,
+            };
+            return {
+                captured,
+                portsCurrent: () => !effects || effects.showStatus === scopedStatus,
+                async run({ message, command, assertRecipient }) {
+                    const recipientOptions = { assertAuthority: assertRecipient };
+                    return handleTelegramCommandRuntime("status", message, ctx, {
+                        ...captured,
+                        assertExecutionCurrent: assertRecipient,
+                        showStatus: (value, context) => captured.showStatus(value, context, recipientOptions),
+                    }, command.args);
+                },
+            };
         },
+    };
+    const heldPlans = {
+        status: heldMenuPlan,
+        start: heldMenuPlan,
+        help: heldMenuPlan,
         abort: {
             completion: "after-semantics",
             effect: "sendTextReply",

package/dist/lib/extension.js

@@ -59,6 +59,9 @@ import * as WorkspaceRetirement from "./workspace-retirement.js";
 const telegramBusProtocolIdentity = Bus.createTelegramCurrentBusProtocolIdentity([
     Bus.TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION,
     Bus.TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF,
+    Bus.TELEGRAM_BUS_CAPABILITY_QUEUE_STEER,
+    Bus.TELEGRAM_BUS_CAPABILITY_CONNECT_RECOVERY,
+    Bus.TELEGRAM_BUS_CAPABILITY_HELD_MENU_ALIASES,
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT,
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
     Bus.TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
@@ -557,7 +560,6 @@ export default function (pi) {
         },
         getQueuedItems: telegramQueueStore.getQueuedItems,
         getQueuedItemCount: Queue.countExecutableTelegramQueueItems,
-        formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
         getRecentRuntimeEvents: runtimeEvents.getEvents,
         getRuntimeLockState: lockRuntime.getStatusLabel,
         ...threadStatusProjectionRuntime,
@@ -796,7 +798,7 @@ export default function (pi) {
             editMessageText: editTelegramMessageText,
         },
     });
-    const { mutation: queueMutationRuntime, dispatchNext: dispatchNextQueuedTelegramTurn, requestNextDispatchAnnouncement, cancelNextDispatchAnnouncement, watchdog: queueDispatchWatchdogRuntime, } = Bindings.createTelegramQueueBindingRuntime({
+    const { mutation: queueMutationRuntime, dispatchNext: dispatchNextQueuedTelegramTurn, requestNextDispatchAnnouncement, cancelNextDispatchAnnouncement, watchdog: queueDispatchWatchdogRuntime, onTurnEnd: onSteerTurnEnd, } = Bindings.createTelegramQueueBindingRuntime({
         store: telegramQueueStore,
         queue,
         lifecycle,
@@ -807,6 +809,8 @@ export default function (pi) {
         promptDispatch: promptDispatchRuntime,
         isIdle,
         hasPendingMessages,
+        isContextCurrent: telegramSessionContextStore.isCurrent,
+        isContextAborted: Pi.isExtensionContextAbortRequested,
         updateStatus,
         sendTextReply,
         sendUserMessage,
@@ -881,6 +885,7 @@ export default function (pi) {
     });
     // --- Queue And Settings Menus ---
     const queueMenuRuntime = MenuQueue.createTelegramQueueMenuRuntime({
+        hasPendingDispatch: lifecycle.hasDispatchPending,
         telegramQueueStore,
         queueMutationRuntime,
         sendInteractiveMessage,
@@ -973,7 +978,7 @@ export default function (pi) {
         isSelectedCommandAvailable(follower, name) {
             return (Bus.hasTelegramBusSharedCapabilities(telegramBusProtocolIdentity, follower.protocol, [
                 ...Bus.TELEGRAM_BUS_LIVE_REBIND_CAPABILITIES,
-                ...Bus.TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES,
+                ...Bus.getTelegramBusHeldCommandCapabilities(name),
             ]) &&
                 typeof selectedMenuDelivery === "function" &&
                 typeof inboundRouteRuntime.prepareHeldCommand === "function" &&
@@ -1222,6 +1227,7 @@ export default function (pi) {
         threadStore,
         runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
         liveRebindCleanupSchedule: Routing.TELEGRAM_LIVE_REBIND_CLEANUP_SCHEDULE,
+        liveRebindCommandCompletionTimeoutMs: 8_000,
         updateStatus,
         isContextActive: telegramSessionContextStore.isCurrent,
         dispatchNextQueuedTelegramTurn,
@@ -1858,6 +1864,14 @@ export default function (pi) {
         recordRuntimeEvent,
     });
     queueHandoffReconciliationBinding.set(Updates.createTelegramQueueHandoffReconciliationRuntimeAssembly({
+        hasPendingDispatch: lifecycle.hasDispatchPending,
+        canHandoffSteerWithRecipient(recipient) {
+            const live = telegramBusFollowerRegistry.get(recipient.instanceId);
+            return live?.registrationGeneration === recipient.registrationGeneration &&
+                [telegramBusProtocolIdentity, live?.protocol,
+                    ...(telegramBusFollowerRegistrationState.isRegistered() ? [telegramBusFollowerRegistrationState.getLeaderProtocol()] : [])]
+                    .every(Bus.hasTelegramBusSteerQueueHandoffCapability);
+        },
         ownsDirect: lockRuntime.owns,
         isFollowerRegistered: telegramBusFollowerRegistrationState.isRegistered,
         isBusEnabled: isTelegramBusRuntimeEnabled,
@@ -2461,6 +2475,7 @@ export default function (pi) {
         sendMarkdownReply,
         sendTextReply,
         dispatchNextQueuedTelegramTurn,
+        onSteerTurnEnd,
         onPromptHandedOff(turn, ctx) {
             updateAdmissionRuntimeBinding
                 .getSettlement()

package/dist/lib/lifecycle.d.ts

@@ -5,7 +5,7 @@
  * Transport authority, durable bindings, and queue custody remain with their owners.
  */
 import * as BusFollower from "./bus-follower.ts";
-import type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AssistantMessageEvent, BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, InputEvent, MessageEndEvent, SessionBeforeCompactEvent, SessionCompactEvent, SessionCompactFailedEvent, SessionShutdownEvent, SessionStartEvent, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, UIPromptEndEvent, UIPromptStartEvent } from "./pi.ts";
+import type { AgentEndEvent, AgentSettledEvent, AgentStartEvent, AssistantMessageEvent, BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, InputEvent, MessageEndEvent, SessionBeforeCompactEvent, SessionCompactEvent, SessionCompactFailedEvent, SessionShutdownEvent, SessionStartEvent, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, TurnEndEvent, TurnEndEventResult, UIPromptEndEvent, UIPromptStartEvent } from "./pi.ts";
 import * as Machine from "./machine.ts";
 import * as Queue from "./queue.ts";
 export declare function createAgentStartDedupHook(inner: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>, resetReplyDedup: () => void, schedulePublication?: (task: () => Promise<void>) => void): (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>;
@@ -30,6 +30,7 @@ export interface TelegramLifecycleRegistrationDeps {
     onModelSelect: (event: {
         model: TelegramLifecycleModel;
     }, ctx: ExtensionContext) => Promise<void> | void;
+    onTurnEnd?: (event: TurnEndEvent, ctx: ExtensionContext) => TurnEndEventResult | undefined;
     onAgentStart: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>;
     onToolExecutionStart: (event: ToolExecutionStartEvent, ctx: ExtensionContext) => Promise<void> | void;
     onToolExecutionUpdate?: (event: ToolExecutionUpdateEvent, ctx: ExtensionContext) => Promise<void> | void;

package/dist/lib/lifecycle.js

@@ -265,36 +265,47 @@ export function createTelegramBridgeSessionLifecycleDeps(ports) {
     };
 }
 export function createTelegramBridgeSessionLifecycleAssembly(deps) {
-    const isSessionActive = deps.contextStore.isCurrent;
     const suspendForReplacement = BusFollower.createTelegramBusFollowerSessionReplacementSuspender({
         registrationState: deps.follower.registrationState,
         instanceId: deps.follower.instanceId,
         suspendPolling: deps.follower.suspendPolling,
         recordRuntimeEvent: deps.follower.recordRuntimeEvent,
     });
-    let preserveTarget = true;
-    const queueLifecycle = Queue.createTelegramSessionLifecycleRuntime({
+    // A reused context can be current for a successor; inner awaits need this invocation's generation too.
+    const queueLifecycle = (ctx, generation, preserveTarget = true) => Queue.createTelegramSessionLifecycleRuntime({
         ...deps.queue,
-        isSessionActive,
+        isSessionActive: () => deps.contextStore.isCurrent(ctx, generation),
         stopPolling: () => suspendForReplacement(preserveTarget),
         clearPendingMediaGroups: deps.services.suspendGroupedInput,
     });
     const servicesLifecycle = {
         async onSessionStart(event, ctx) {
+            const generation = deps.contextStore.getGeneration();
+            const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
             const resumeConnection = deps.services.connection?.prepare(event, ctx);
-            await queueLifecycle.onSessionStart(event, ctx);
-            if (!isSessionActive(ctx))
+            await queueLifecycle(ctx, generation).onSessionStart(event, ctx);
+            if (!isCurrent())
                 return;
             deps.services.resumeGroupedInput(ctx);
             await deps.services.delivery.onSessionStart();
-            if (!isSessionActive(ctx))
+            if (!isCurrent())
                 return;
             if (resumeConnection)
                 resumeConnection();
             else
                 await deps.services.polling.onSessionStart(event, ctx);
+            if (!isCurrent())
+                return;
             deps.services.capabilityMonitor.start(ctx);
             deps.services.queueWatchdog.start(ctx);
+            await BusFollower.createTelegramBusFollowerSessionRefreshHook({
+                registrationState: deps.follower.registrationState,
+                registrationRuntime: deps.follower.registrationRuntime,
+                getLeaderState: deps.follower.getLeaderState,
+                isSessionActive: isCurrent,
+                updateStatus: deps.follower.updateStatus,
+                recordRuntimeEvent: deps.follower.recordRuntimeEvent,
+            })(event, ctx);
         },
         async onSessionShutdown(event, ctx) {
             const generation = deps.contextStore.getGeneration();
@@ -302,7 +313,7 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
             if (!isCurrent())
                 return;
             deps.services.connection?.onSessionShutdown(event, ctx);
-            preserveTarget = event.reason !== "resume";
+            const preserveTarget = event.reason !== "resume";
             let preserveThread;
             if (event.reason === "quit") {
                 try {
@@ -321,7 +332,7 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
                 return;
             deps.services.queueWatchdog.stop();
             deps.services.capabilityMonitor.stop();
-            await queueLifecycle.onSessionShutdown(event, ctx);
+            await queueLifecycle(ctx, generation, preserveTarget).onSessionShutdown(event, ctx);
             if (!isCurrent())
                 return;
             await deps.services.inboundWorker.onSessionShutdown();
@@ -337,17 +348,7 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
             }
         },
     };
-    const followerLifecycle = appendTelegramLifecycleHooks(servicesLifecycle, {
-        onSessionStart: BusFollower.createTelegramBusFollowerSessionRefreshHook({
-            registrationState: deps.follower.registrationState,
-            registrationRuntime: deps.follower.registrationRuntime,
-            getLeaderState: deps.follower.getLeaderState,
-            isSessionActive,
-            updateStatus: deps.follower.updateStatus,
-            recordRuntimeEvent: deps.follower.recordRuntimeEvent,
-        }),
-    }, isSessionActive);
-    return createTelegramSessionGenerationFence(deps.contextStore, followerLifecycle);
+    return createTelegramSessionGenerationFence(deps.contextStore, servicesLifecycle);
 }
 function unrefTelegramLifecycleTimer(timer) {
     if (!timer || typeof timer !== "object")
@@ -605,6 +606,13 @@ export function registerTelegramLifecycleHooks(pi, deps) {
             return;
         await deps.onAgentStart(event, ctx);
     });
+    if (deps.onTurnEnd) {
+        pi.on("turn_end", (event, ctx) => {
+            if (!isActive(ctx))
+                return;
+            return deps.onTurnEnd?.(event, ctx);
+        });
+    }
     pi.on("tool_execution_start", async (event, ctx) => {
         if (!isActive(ctx))
             return;

package/dist/lib/locks.d.ts

@@ -259,7 +259,9 @@ export interface TelegramLockedPollingRuntime<TContext extends TelegramLockConte
     captureTransportAuthority: (ctx: TContext) => (() => boolean) | undefined;
     onPersistentConflict: (ctx: TContext, count: number) => Promise<void>;
     onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
-    registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
+    registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry, options?: {
+        recoverConnection?: boolean;
+    }) => boolean | undefined | Promise<boolean | undefined>;
     restoreFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     stopFollowerRegistration?: () => void;
 }
@@ -274,7 +276,9 @@ interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext>
     formatStartBlockedMessage?: (ctx: TContext) => string;
     startPolling: (ctx: TContext, options?: TelegramLockedPollingStartOptions) => void | Promise<void>;
     stopPolling: () => Promise<void>;
-    registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
+    registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry, options?: {
+        recoverConnection?: boolean;
+    }) => boolean | undefined | Promise<boolean | undefined>;
     restoreFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     stopFollowerRegistration?: () => void;
     /** Threaded Mode takeover evidence after failed follower registration; replaces the retired file heartbeat. */

package/dist/lib/locks.js

@@ -1625,7 +1625,7 @@ export function createTelegramLockedPollingRuntime(deps) {
                 if (deps.registerFollowerWithOwner) {
                     let failureMessage;
                     try {
-                        const registered = await deps.registerFollowerWithOwner(ctx, acquired.lock);
+                        const registered = await deps.registerFollowerWithOwner(ctx, acquired.lock, options.forceFreshLeaderThread ? { recoverConnection: true } : undefined);
                         if (!isCurrent())
                             return cancelled;
                         if (registered) {
@@ -1838,8 +1838,8 @@ export function createTelegramLockedPollingRuntime(deps) {
             sessionAutoStartRun = run;
         },
         registerFollowerWithOwner: deps.registerFollowerWithOwner
-            ? async (ctx, owner) => {
-                const registered = await deps.registerFollowerWithOwner?.(ctx, owner);
+            ? async (ctx, owner, options) => {
+                const registered = await deps.registerFollowerWithOwner?.(ctx, owner, options);
                 if (registered)
                     deps.updateStatus(ctx);
                 return registered === true;

package/dist/lib/menu-queue.d.ts

@@ -24,6 +24,7 @@ interface TelegramQueueMenuRuntime<Context> {
     handleCallbackQuery: (query: TelegramQueueMenuCallbackQuery, ctx: Context) => Promise<boolean>;
 }
 export declare function createTelegramQueueMenuRuntime<Context, TModel extends MenuModel = MenuModel>(deps: {
+    hasPendingDispatch?: () => boolean;
     telegramQueueStore: Queue.TelegramQueueStateStore<Context>;
     queueMutationRuntime: Queue.TelegramQueueMutationController<Context>;
     sendInteractiveMessage: TelegramMenuMessageRuntimeDeps["sendInteractiveMessage"];