@llblab/pi-telegram 0.55.0 → 0.56.0

package/lib/bus-leader.ts

@@ -23,6 +23,7 @@ import {
   TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
   TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION,
   TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF,
+  hasTelegramBusSteerQueueHandoffCapability,
   TELEGRAM_BUS_CAPABILITY_SELECTED_MENU_DELIVERY,
   TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
   TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
@@ -3273,6 +3274,10 @@ export function createTelegramBusLeaderEnvelopeHandler(
         "Telegram queue handoff capability was not negotiated.",
       );
     }
+    if (envelope.payload.queueLane === "steer" &&
+        ![deps.protocolIdentity, donor.protocol, recipient?.protocol].every(hasTelegramBusSteerQueueHandoffCapability)) {
+      return rejectTelegramBusRequest(envelope.requestId, "Steer queue handoff capability was not negotiated.");
+    }
     if (
       !recipient?.registrationGeneration ||
       envelope.recipientRegistrationGeneration !==
@@ -4477,6 +4482,10 @@ export function createTelegramBusLeaderRuntime<TContext>(
         "Telegram queue handoff capability was not negotiated.",
       );
     }
+    if (input.payload.queueLane === "steer" &&
+        ![deps.protocolIdentity, recipient?.protocol].every(hasTelegramBusSteerQueueHandoffCapability)) {
+      return rejectTelegramBusRequest(input.requestId, "Steer queue handoff capability was not negotiated.");
+    }
     if (
       !recipient?.registrationGeneration ||
       input.recipientRegistrationGeneration !== recipient.registrationGeneration

package/lib/bus.ts

@@ -142,6 +142,8 @@ export const TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION =
   "durable-follower-admission-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF =
   "queue-handoff-v1" as const;
+/** Unspent Steer lane codec; independent from baseline receipt handoff support. */
+export const TELEGRAM_BUS_CAPABILITY_QUEUE_STEER = "queue-steer-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_INPUT_CUSTODY_REFERENCE =
   "input-custody-reference-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME =
@@ -461,6 +463,11 @@ export function hasTelegramBusCapability(
   return identity?.capabilities.includes(capability) ?? false;
 }
 
+export function hasTelegramBusSteerQueueHandoffCapability(identity: TelegramBusProtocolIdentity | undefined): boolean {
+  return hasTelegramBusCapability(identity, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF) &&
+    hasTelegramBusCapability(identity, TELEGRAM_BUS_CAPABILITY_QUEUE_STEER);
+}
+
 export function getTelegramInputCustodyPeerReadiness(
   followers: readonly Pick<
     TelegramBusFollowerView,
@@ -1926,6 +1933,8 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
     message: TMessage;
     ownership: TelegramBusForwardOwnership;
     ctx: TContext;
+    /** Process-local source/recipient lifetime; never part of the wire envelope. */
+    assertAuthority?: () => void;
   }) => Promise<TelegramBusForeignUpdateSettlement>;
   forwardEditedMessage: (input: {
     message: TMessage;
@@ -2057,6 +2066,7 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
   const send = async (
     envelope: TelegramBusDurableForwardEnvelope,
     ownership: TelegramBusForwardOwnership,
+    assertAuthority?: () => void,
   ): Promise<TelegramBusForeignUpdateSettlement> => {
     if (
       deps.validateForwardOwnership &&
@@ -2078,10 +2088,15 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
         socketPath,
         envelope,
         timeoutMs: deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CONTROL_TIMEOUT_MS,
-        retry: getTelegramBusTransportRetryPolicy({
+        retry: assertAuthority ? { attempts: 1, delayMs: 0 } : getTelegramBusTransportRetryPolicy({
           endpoint: socketPath,
           operation: "operation",
         }),
+        ...(assertAuthority || deps.validateForwardOwnership ? { assertAuthority() {
+          assertAuthority?.();
+          if (deps.validateForwardOwnership && !deps.validateForwardOwnership(ownership))
+            throw new Error("Telegram follower forwarding ownership changed.");
+        } } : {}),
       });
     } catch (error) {
       return reject({
@@ -2178,6 +2193,7 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
       base: ForwardBase,
       sentAtMs: number,
     ) => TelegramBusDurableForwardEnvelope,
+    assertAuthority?: () => void,
   ): Promise<TelegramBusForeignUpdateSettlement> => {
     const prepared = prepare(kind, value, ownership);
     if ("settlement" in prepared) return Promise.resolve(prepared.settlement);
@@ -2192,6 +2208,7 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
         ? { kind: "leader.wakeInputCustody", ...base, sentAtMs: getNowMs() }
         : build(base, getNowMs()),
       ownership,
+      assertAuthority,
     );
   };
   return {
@@ -2214,7 +2231,7 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
           sentAtMs,
         }),
       ),
-    forwardMessage: ({ message, ownership }) =>
+    forwardMessage: ({ message, ownership, assertAuthority }) =>
       forward("leader.forwardMessage", message, ownership, (base, sentAtMs) => {
         const forwardCommentBatchPosition =
           deps.getForwardCommentBatchPosition?.(message);
@@ -2227,7 +2244,7 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
             : {}),
           sentAtMs,
         };
-      }),
+      }, assertAuthority),
     forwardEditedMessage: ({ message, ownership }) =>
       forward(
         "leader.forwardEditedMessage",

package/lib/extension.ts

@@ -64,6 +64,7 @@ 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_WORKSPACE_FOLLOWER_AUTO_CONNECT,
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
     Bus.TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
@@ -717,7 +718,6 @@ export default function (pi: Pi.ExtensionAPI) {
     },
     getQueuedItems: telegramQueueStore.getQueuedItems,
     getQueuedItemCount: Queue.countExecutableTelegramQueueItems,
-    formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
     getRecentRuntimeEvents: runtimeEvents.getEvents,
     getRuntimeLockState: lockRuntime.getStatusLabel,
     ...threadStatusProjectionRuntime,
@@ -1026,6 +1026,7 @@ export default function (pi: Pi.ExtensionAPI) {
     requestNextDispatchAnnouncement,
     cancelNextDispatchAnnouncement,
     watchdog: queueDispatchWatchdogRuntime,
+    onTurnEnd: onSteerTurnEnd,
   } = Bindings.createTelegramQueueBindingRuntime({
     store: telegramQueueStore,
     queue,
@@ -1037,6 +1038,8 @@ export default function (pi: Pi.ExtensionAPI) {
     promptDispatch: promptDispatchRuntime,
     isIdle,
     hasPendingMessages,
+    isContextCurrent: telegramSessionContextStore.isCurrent,
+    isContextAborted: Pi.isExtensionContextAbortRequested,
     updateStatus,
     sendTextReply,
     sendUserMessage,
@@ -1123,6 +1126,7 @@ export default function (pi: Pi.ExtensionAPI) {
 
   // --- Queue And Settings Menus ---
   const queueMenuRuntime = MenuQueue.createTelegramQueueMenuRuntime({
+    hasPendingDispatch: lifecycle.hasDispatchPending,
     telegramQueueStore,
     queueMutationRuntime,
     sendInteractiveMessage,
@@ -2331,6 +2335,14 @@ export default function (pi: Pi.ExtensionAPI) {
     });
   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,
@@ -3046,6 +3058,7 @@ export default function (pi: Pi.ExtensionAPI) {
     sendMarkdownReply,
     sendTextReply,
     dispatchNextQueuedTelegramTurn,
+    onSteerTurnEnd,
     onPromptHandedOff(turn, ctx) {
       updateAdmissionRuntimeBinding
         .getSettlement()

package/lib/lifecycle.ts

@@ -26,6 +26,8 @@ import type {
   ToolExecutionEndEvent,
   ToolExecutionStartEvent,
   ToolExecutionUpdateEvent,
+  TurnEndEvent,
+  TurnEndEventResult,
   UIPromptEndEvent,
   UIPromptStartEvent,
 } from "./pi.ts";
@@ -100,6 +102,7 @@ export interface TelegramLifecycleRegistrationDeps {
     event: { model: TelegramLifecycleModel },
     ctx: ExtensionContext,
   ) => Promise<void> | void;
+  onTurnEnd?: (event: TurnEndEvent, ctx: ExtensionContext) => TurnEndEventResult | undefined;
   onAgentStart: (
     event: AgentStartEvent,
     ctx: ExtensionContext,
@@ -575,7 +578,6 @@ export function createTelegramBridgeSessionLifecycleAssembly<
 >(
   deps: TelegramBridgeSessionLifecycleAssemblyDeps<TQueueItem, TModel>,
 ): TelegramSessionLifecycleHooks {
-  const isSessionActive = deps.contextStore.isCurrent;
   const suspendForReplacement =
     BusFollower.createTelegramBusFollowerSessionReplacementSuspender({
       registrationState: deps.follower.registrationState,
@@ -583,32 +585,44 @@ export function createTelegramBridgeSessionLifecycleAssembly<
       suspendPolling: deps.follower.suspendPolling,
       recordRuntimeEvent: deps.follower.recordRuntimeEvent,
     });
-  let preserveTarget = true;
-  const queueLifecycle = Queue.createTelegramSessionLifecycleRuntime({
-    ...deps.queue,
-    isSessionActive,
-    stopPolling: () => suspendForReplacement(preserveTarget),
-    clearPendingMediaGroups: deps.services.suspendGroupedInput,
-  });
+  // A reused context can be current for a successor; inner awaits need this invocation's generation too.
+  const queueLifecycle = (ctx: ExtensionContext, generation: number, preserveTarget = true) =>
+    Queue.createTelegramSessionLifecycleRuntime({
+      ...deps.queue,
+      isSessionActive: () => deps.contextStore.isCurrent(ctx, generation),
+      stopPolling: () => suspendForReplacement(preserveTarget),
+      clearPendingMediaGroups: deps.services.suspendGroupedInput,
+    });
   const servicesLifecycle: TelegramSessionLifecycleHooks = {
     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)) return;
+      await queueLifecycle(ctx, generation).onSessionStart(event, ctx);
+      if (!isCurrent()) return;
       deps.services.resumeGroupedInput(ctx);
       await deps.services.delivery.onSessionStart();
-      if (!isSessionActive(ctx)) return;
+      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();
       const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
       if (!isCurrent()) return;
       deps.services.connection?.onSessionShutdown(event, ctx);
-      preserveTarget = event.reason !== "resume";
+      const preserveTarget = event.reason !== "resume";
       let preserveThread: (() => Promise<void>) | undefined;
       if (event.reason === "quit") {
         try {
@@ -625,7 +639,7 @@ export function createTelegramBridgeSessionLifecycleAssembly<
       if (!isCurrent()) 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();
       if (!isCurrent()) return;
@@ -638,23 +652,9 @@ export function createTelegramBridgeSessionLifecycleAssembly<
       }
     },
   };
-  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,
+    servicesLifecycle,
   );
 }
 
@@ -1042,6 +1042,12 @@ export function registerTelegramLifecycleHooks(
     if (!isActive(ctx)) 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;
     await deps.onToolExecutionStart(event, ctx);