@llblab/pi-telegram 0.54.4 → 0.55.0

package/lib/extension.ts

@@ -70,6 +70,8 @@ const telegramBusProtocolIdentity =
     Bus.TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
     Bus.TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE,
+    Bus.TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND,
+    Bus.TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND_EXECUTION,
     Bus.TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_SAVE,
     Bus.TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_APPLY,
     Bus.TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_SETTLE,
@@ -389,10 +391,6 @@ export default function (pi: Pi.ExtensionAPI) {
     buttonActionStore,
     configControls.getAssistantRenderingMode,
   );
-  const pendingModelSwitchStore =
-    Model.createPendingModelSwitchStore<
-      Model.ScopedTelegramModel<ActivePiModel>
-    >();
   const modelMenuRuntime = Menu.createTelegramModelMenuRuntime<ActivePiModel>();
   const sectionRegistry = Sections.createAndBindTelegramSectionRegistry();
 
@@ -424,8 +422,25 @@ export default function (pi: Pi.ExtensionAPI) {
     rawTelegramQueueStore,
     telegramTransportStampRuntime.getStamp,
   );
+  const captureCleanupDrain = Lifecycle.createTelegramSessionDrainObserver({
+    context: telegramSessionContextStore,
+    captureAuthority() {
+      const epoch = getCurrentLeaderEpoch();
+      return epoch === undefined ? undefined : {
+        epoch, operator: configStore.getAllowedUserId(), stamp: telegramTransportStampRuntime.getStamp(),
+      };
+    },
+    isAuthorityActive(authority) {
+      return getCurrentLeaderEpoch() === authority.epoch &&
+        configStore.getAllowedUserId() === authority.operator &&
+        telegramTransportStampRuntime.isActive(authority.stamp);
+    },
+    onDrained(ctx) { inboundRouteRuntime.onDeliverySettled(ctx); },
+  });
   const telegramApiTargetActivityRuntime =
-    TelegramApi.createTelegramApiTargetActivityRuntime();
+    TelegramApi.createTelegramApiTargetActivityRuntime({
+      captureDrain: captureCleanupDrain,
+    });
   // Retirement protection and dead-owner reclamation must inspect the same journal sources.
   const workspaceRetirementJournalPorts = {
     getActiveTurnTarget: activeTurnRuntime.getTarget,
@@ -696,7 +711,10 @@ export default function (pi: Pi.ExtensionAPI) {
     hasDispatchPending: lifecycle.hasDispatchPending,
     isCompactionInProgress: lifecycle.isCompactionInProgress,
     getActiveToolExecutions: lifecycle.getActiveToolExecutions,
-    hasPendingModelSwitch: pendingModelSwitchStore.has,
+    // Status is composed before the model-switch controller; it reads the controller's state when it renders.
+    hasPendingModelSwitch() {
+      return modelSwitchController.hasPendingSwitch();
+    },
     getQueuedItems: telegramQueueStore.getQueuedItems,
     getQueuedItemCount: Queue.countExecutableTelegramQueueItems,
     formatQueuedStatus: Queue.formatQueuedTelegramItemsStatus,
@@ -739,6 +757,11 @@ export default function (pi: Pi.ExtensionAPI) {
   const directTelegramApiRuntime =
     TelegramApi.createDefaultTelegramBridgeApiRuntime({
       getBotToken: configStore.getBotToken,
+      isThreadedMode() {
+        return threadStore.getBotState().threadMode === "enabled" ||
+          telegramBusFollowerRegistrationState.getTarget()?.threadId !== undefined ||
+          telegramBusLeaderState.getTarget()?.threadId !== undefined;
+      },
       getBotScope() {
         const config = configStore.get();
         return (
@@ -837,9 +860,13 @@ export default function (pi: Pi.ExtensionAPI) {
     lifecycle,
     typing,
     getDefaultChatId: proactivePushChatIdGetter,
+    isThreadedMode() {
+      return deliveryTargetPolicyRuntime.getTargetPolicyView().threaded === true;
+    },
     sendTypingAction,
     updateStatus,
     isContextActive: telegramSessionContextStore.isCurrent,
+    getSessionGeneration: telegramSessionContextStore.getGeneration,
     getTransportAuthority() {
       if (ownsTelegramDirectDelivery()) {
         const epoch = getCurrentLeaderEpoch();
@@ -875,6 +902,11 @@ export default function (pi: Pi.ExtensionAPI) {
   const deliveryTargetPolicyRuntime =
     Delivery.createTelegramDeliveryTargetPolicyRuntime({
       ownsDirect: lockRuntime.owns,
+      isThreadedMode() {
+        return threadStore.getBotState().threadMode === "enabled" ||
+          telegramBusFollowerRegistrationState.getTarget()?.threadId !== undefined ||
+          telegramBusLeaderState.getTarget()?.threadId !== undefined;
+      },
       isFollowerRegistered: telegramBusFollowerRegistrationState.isRegistered,
       getAllowedChatId: configStore.getAllowedUserId,
       getFollowerTarget: telegramBusFollowerRegistrationState.getTarget,
@@ -888,6 +920,7 @@ export default function (pi: Pi.ExtensionAPI) {
   const deliveryLifecycleRuntime =
     Delivery.createTelegramBridgeDeliveryLifecycleHooks({
       generationSeed: deliveryGenerationSeed,
+      captureDrain: captureCleanupDrain,
       getTargetPolicyView: deliveryTargetPolicyRuntime.getTargetPolicyView,
       getTransportStamp: telegramTransportStampRuntime.getStamp,
       isTransportStampActive: telegramTransportStampRuntime.isActive,
@@ -948,6 +981,7 @@ export default function (pi: Pi.ExtensionAPI) {
     publicationRuntime,
   } = Bindings.createTelegramActivityBindingRuntime({
     generation: deliveryGenerationSeed,
+    captureDrain: captureCleanupDrain,
     assistantOutput: {
       prepareTelegramPreview: previewRuntime.preparePublication,
       authority: {
@@ -1029,8 +1063,6 @@ export default function (pi: Pi.ExtensionAPI) {
   const modelSwitchController =
     Model.createTelegramModelSwitchControllerRuntime({
       isIdle,
-      getPendingModelSwitch: pendingModelSwitchStore.get,
-      setPendingModelSwitch: pendingModelSwitchStore.set,
       getActiveTurn: activeTurnRuntime.get,
       getAbortHandler: abort.getHandler,
       hasAbortHandler: abort.hasHandler,
@@ -1258,7 +1290,7 @@ export default function (pi: Pi.ExtensionAPI) {
     lifecycle: bridgeRuntime.lifecycle,
     isIdle,
     hasPendingMessages,
-    hasPendingControl: pendingModelSwitchStore.has,
+    hasPendingControl: modelSwitchController.hasPendingSwitch,
     publication: publicationRuntime,
     activity: activityRuntime,
     delivery: deliveryLifecycleRuntime,
@@ -1436,6 +1468,14 @@ export default function (pi: Pi.ExtensionAPI) {
         )
       );
     },
+    canUsePreDispatchRebind(recipient) {
+      return lockRuntime.owns() && telegramBusFollowerRegistry.list().every(function (follower) {
+        return Bus.hasTelegramBusCapability(follower.protocol, Bus.TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND);
+      }) && (recipient?.kind !== "follower" || Bus.hasTelegramBusCapability(
+        telegramBusFollowerRegistry.get(recipient.instanceId)?.protocol,
+        Bus.TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND_EXECUTION,
+      ));
+    },
     hasWorkspaceLiveRebindAuthority() {
       return (
         lockRuntime.owns() &&
@@ -2193,6 +2233,7 @@ export default function (pi: Pi.ExtensionAPI) {
         followerRegistry: telegramBusFollowerRegistry,
         authSecret: telegramBusAuthSecret,
         protocolIdentity: telegramBusProtocolIdentity,
+        requiresPreDispatchRebindReader() { return threadStore.hasPreDispatchRebindEvidence(); },
         selectedMenuDelivery,
         startPolling: pollingAdmissionRuntime.start,
         stopPolling: pollingAdmissionRuntime.stop,
@@ -3029,6 +3070,7 @@ export default function (pi: Pi.ExtensionAPI) {
     isSessionContextActive(ctx) {
       return telegramSessionContextStore.isCurrent(ctx);
     },
+    getSessionGeneration: telegramSessionContextStore.getGeneration,
     isTurnTransportActive(turn) {
       return telegramTransportStampRuntime.isActive(turn.transportStamp);
     },

package/lib/lifecycle.ts

@@ -29,6 +29,7 @@ import type {
   UIPromptEndEvent,
   UIPromptStartEvent,
 } from "./pi.ts";
+import * as Machine from "./machine.ts";
 import * as Queue from "./queue.ts";
 import { formatTelegramConnectionFailure } from "./status.ts";
 import * as TextGroups from "./text-groups.ts";
@@ -411,6 +412,30 @@ export function createTelegramSessionContextStore<TContext>(
   };
 }
 
+/** Capture drain hints at work admission; late completion never borrows a replacement session or transport. */
+export function createTelegramSessionDrainObserver<TContext, TAuthority>(deps: {
+  context: Pick<TelegramSessionContextStore<TContext>, "get" | "getGeneration" | "isCurrent">;
+  captureAuthority: () => TAuthority | undefined;
+  isAuthorityActive: (authority: TAuthority) => boolean;
+  onDrained: (ctx: TContext) => void;
+}): () => (() => void) | undefined {
+  return () => {
+    try {
+      const ctx = deps.context.get(), generation = deps.context.getGeneration(), authority = deps.captureAuthority();
+      if (ctx === undefined || authority === undefined) return undefined;
+      return () => {
+        queueMicrotask(() => {
+          try {
+            if (!deps.context.isCurrent(ctx, generation) || !deps.isAuthorityActive(authority)) return;
+            const emitted: unknown = deps.onDrained(ctx);
+            if (emitted) void Promise.resolve(emitted).catch(() => undefined);
+          } catch { /* A drain hint is observational, not execution authority. */ }
+        });
+      };
+    } catch { return undefined; }
+  };
+}
+
 export function createTelegramSessionGenerationFence(
   store: TelegramSessionContextStore<ExtensionContext>,
   hooks: TelegramSessionLifecycleHooks,
@@ -670,6 +695,121 @@ export interface TelegramCompactionObserverRuntime<TContext> {
   onSessionShutdown: () => void;
 }
 
+/** The whole compaction-observer state; only `transitionTelegramCompactionObserver` produces a new one. */
+export interface TelegramCompactionObserverState {
+  /** The fallback timer's observation; a timer from any other one is inert. */
+  readonly observation: number | null;
+  /** The typing loop is the observer's to stop; a loop the agent already ran is never stopped by compaction. */
+  readonly typingOwned: boolean;
+  readonly nextObservation: number;
+}
+
+export type TelegramCompactionObserverEvent =
+  | { type: "beforeCompact" }
+  /** The outcome of the observer's own typing start, reported back by the shell. */
+  | { type: "typingStarted"; started: boolean }
+  | { type: "compacted" }
+  | { type: "compactFailed" }
+  | { type: "timerFired"; observation: number; contextActive: boolean }
+  | { type: "shutdown" };
+
+export type TelegramCompactionObserverEffect =
+  | { type: "setInProgress"; inProgress: boolean }
+  | { type: "startTyping" }
+  | { type: "stopTyping" }
+  | { type: "updateStatus" }
+  | { type: "armTimer"; observation: number }
+  | { type: "cancelTimer" }
+  | { type: "recordTimeout" }
+  | { type: "abandoned" }
+  | { type: "requestDispatch" };
+
+export function createTelegramCompactionObserverState(): TelegramCompactionObserverState {
+  return { observation: null, typingOwned: false, nextObservation: 0 };
+}
+
+/**
+ * Pure compaction-observer transition. A completion or failure always releases presence; the timeout releases only its
+ * own observation. Typing ownership is sticky: a repeated start while the observer's own loop runs reports `false`
+ * from the shared loop, and must not hand that loop to nobody.
+ */
+export function transitionTelegramCompactionObserver(
+  state: TelegramCompactionObserverState,
+  event: TelegramCompactionObserverEvent,
+): Machine.TelegramMachineStep<
+  TelegramCompactionObserverState,
+  TelegramCompactionObserverEffect
+> {
+  const cancel: TelegramCompactionObserverEffect[] =
+    state.observation === null ? [] : [{ type: "cancelTimer" }];
+  const release = (
+    ...tail: TelegramCompactionObserverEffect[]
+  ): TelegramCompactionObserverEffect[] => [
+    { type: "setInProgress", inProgress: false },
+    ...(state.typingOwned ? [{ type: "stopTyping" } as const] : []),
+    { type: "updateStatus" },
+    ...tail,
+  ];
+  switch (event.type) {
+    case "beforeCompact": {
+      const observation = state.nextObservation + 1;
+      return {
+        state: { ...state, observation, nextObservation: observation },
+        effects: [
+          { type: "setInProgress", inProgress: true },
+          { type: "startTyping" },
+          { type: "updateStatus" },
+          ...cancel,
+          { type: "armTimer", observation },
+        ],
+      };
+    }
+    case "typingStarted":
+      return {
+        state: { ...state, typingOwned: state.typingOwned || event.started },
+        effects: [],
+      };
+    case "compacted":
+      return {
+        state: { ...state, observation: null, typingOwned: false },
+        effects: [...cancel, ...release({ type: "requestDispatch" })],
+      };
+    case "compactFailed":
+      return {
+        state: { ...state, observation: null, typingOwned: false },
+        effects: [
+          ...cancel,
+          ...release({ type: "abandoned" }, { type: "requestDispatch" }),
+        ],
+      };
+    case "timerFired":
+      if (state.observation !== event.observation)
+        return { state, effects: [] };
+      // A replaced context consumes its observation without releasing the replacement's presence.
+      if (!event.contextActive)
+        return { state: { ...state, observation: null }, effects: [] };
+      return {
+        state: { ...state, observation: null, typingOwned: false },
+        effects: release(
+          { type: "recordTimeout" },
+          { type: "requestDispatch" },
+        ),
+      };
+    case "shutdown":
+      return {
+        state: { ...state, observation: null, typingOwned: false },
+        effects: [
+          ...cancel,
+          ...(state.typingOwned ? [{ type: "stopTyping" } as const] : []),
+        ],
+      };
+  }
+}
+
+/**
+ * The shell around `transitionTelegramCompactionObserver`: it fences inactive contexts, runs effects with the calling
+ * context, reports the typing start back and owns the fallback timer, which keeps the context it was armed under.
+ */
 export function createTelegramCompactionObserverRuntime<TContext>(
   deps: TelegramCompactionObserverRuntimeDeps<TContext>,
 ): TelegramCompactionObserverRuntime<TContext> {
@@ -677,74 +817,105 @@ export function createTelegramCompactionObserverRuntime<TContext>(
   const setTimer = deps.setTimer ?? setTimeout;
   const clearTimer = deps.clearTimer ?? clearTimeout;
   let fallbackTimer: TelegramLifecycleTimer | undefined;
-  let observationGeneration = 0;
-  let typingStartedByObserver = false;
-  const clearFallbackTimer = (): void => {
-    observationGeneration += 1;
-    if (!fallbackTimer) return;
-    clearTimer(fallbackTimer);
-    fallbackTimer = undefined;
-  };
-  // Stop only a typing loop this observer started; a pre-existing agent-owned loop is preserved.
-  const releaseCompactionPresence = (ctx: TContext): void => {
-    deps.setCompactionInProgress(false);
-    if (typingStartedByObserver) deps.stopTypingLoop?.();
-    typingStartedByObserver = false;
-    deps.updateStatus(ctx);
-  };
-  const requestDispatch = (): void => {
-    deps.requestDeferredDispatchNextQueuedTelegramTurn(
-      deps.dispatchNextQueuedTelegramTurn,
-    );
+  // The context of the event being dispatched; effects run synchronously inside that dispatch.
+  let call: TContext | undefined;
+  const machine = Machine.createTelegramMachineRunner<
+    TelegramCompactionObserverState,
+    TelegramCompactionObserverEvent,
+    TelegramCompactionObserverEffect
+  >({
+    initial: createTelegramCompactionObserverState(),
+    transition: transitionTelegramCompactionObserver,
+    run(effect) {
+      const ctx = call as TContext;
+      switch (effect.type) {
+        case "setInProgress":
+          deps.setCompactionInProgress(effect.inProgress);
+          return;
+        case "startTyping": {
+          const result = deps.startTypingLoop?.(ctx);
+          machine.dispatch({
+            type: "typingStarted",
+            started: !!deps.startTypingLoop && result !== false,
+          });
+          return;
+        }
+        case "stopTyping":
+          deps.stopTypingLoop?.();
+          return;
+        case "updateStatus":
+          deps.updateStatus(ctx);
+          return;
+        case "armTimer": {
+          const armedCtx = ctx;
+          fallbackTimer = setTimer(() => {
+            fallbackTimer = undefined;
+            dispatchFor(armedCtx, {
+              type: "timerFired",
+              observation: effect.observation,
+              contextActive:
+                !deps.isContextActive || deps.isContextActive(armedCtx),
+            });
+          }, timeoutMs);
+          unrefTelegramLifecycleTimer(fallbackTimer);
+          return;
+        }
+        case "cancelTimer":
+          if (fallbackTimer !== undefined) clearTimer(fallbackTimer);
+          fallbackTimer = undefined;
+          return;
+        case "recordTimeout":
+          deps.recordRuntimeEvent?.(
+            "compact",
+            new Error("Compaction observer timed out"),
+          );
+          return;
+        case "abandoned":
+          deps.onCompactionAbandoned?.();
+          return;
+        case "requestDispatch":
+          // Observer expiry releases local presence, not Pi's eventual terminal result.
+          deps.requestDeferredDispatchNextQueuedTelegramTurn(
+            deps.dispatchNextQueuedTelegramTurn,
+          );
+          return;
+      }
+    },
+  });
+  const dispatchFor = (
+    ctx: TContext | undefined,
+    event: TelegramCompactionObserverEvent,
+  ): void => {
+    const previous = call;
+    call = ctx;
+    try {
+      machine.dispatch(event);
+    } finally {
+      call = previous;
+    }
   };
+  const isActive = (ctx: TContext): boolean =>
+    !deps.isContextActive || deps.isContextActive(ctx);
   return {
     onSessionBeforeCompact: (_event, ctx) => {
-      if (deps.isContextActive && !deps.isContextActive(ctx)) return;
-      deps.setCompactionInProgress(true);
-      const typingStartResult = deps.startTypingLoop?.(ctx);
-      typingStartedByObserver =
-        !!deps.startTypingLoop && typingStartResult !== false;
-      deps.updateStatus(ctx);
-      clearFallbackTimer();
-      const admittedGeneration = observationGeneration;
-      fallbackTimer = setTimer(() => {
-        if (observationGeneration !== admittedGeneration) return;
-        observationGeneration += 1;
-        fallbackTimer = undefined;
-        if (deps.isContextActive && !deps.isContextActive(ctx)) return;
-        releaseCompactionPresence(ctx);
-        deps.recordRuntimeEvent?.(
-          "compact",
-          new Error("Compaction observer timed out"),
-        );
-        // Observer expiry releases local presence, not Pi's eventual terminal result.
-        requestDispatch();
-      }, timeoutMs);
-      unrefTelegramLifecycleTimer(fallbackTimer);
+      if (isActive(ctx)) dispatchFor(ctx, { type: "beforeCompact" });
     },
     onSessionCompact: (_event, ctx) => {
-      if (deps.isContextActive && !deps.isContextActive(ctx)) return;
-      clearFallbackTimer();
-      releaseCompactionPresence(ctx);
-      requestDispatch();
+      if (isActive(ctx)) dispatchFor(ctx, { type: "compacted" });
     },
     onSessionCompactFailed: (_event, ctx) => {
-      if (deps.isContextActive && !deps.isContextActive(ctx)) return;
-      clearFallbackTimer();
-      releaseCompactionPresence(ctx);
-      deps.onCompactionAbandoned?.();
-      requestDispatch();
+      if (isActive(ctx)) dispatchFor(ctx, { type: "compactFailed" });
     },
     onSessionShutdown: () => {
-      clearFallbackTimer();
-      if (typingStartedByObserver) deps.stopTypingLoop?.();
-      typingStartedByObserver = false;
+      dispatchFor(undefined, { type: "shutdown" });
     },
   };
 }
 
 export interface TelegramMessageActivityTypingDeps<TContext> {
   hasActiveTurn: () => boolean;
+  isContextActive?: (ctx: TContext) => boolean;
+  getSessionGeneration?: () => number;
   startTypingLoop: (ctx: TContext) => void;
   onMessageStart: TelegramLifecycleRegistrationDeps["onMessageStart"];
   onMessageUpdate: TelegramLifecycleRegistrationDeps["onMessageUpdate"];
@@ -773,13 +944,16 @@ export function createTelegramMessageActivityTypingHooks<
     inner: (event: TEvent, ctx: ExtensionContext) => Promise<void>,
   ): Promise<void> => {
     const typedCtx = ctx as TContext;
-    ensureTyping(typedCtx);
+    const generation = deps.getSessionGeneration?.();
+    const isCurrent = () => deps.isContextActive?.(typedCtx) !== false &&
+      (!deps.getSessionGeneration || Object.is(deps.getSessionGeneration(), generation));
+    if (isCurrent()) ensureTyping(typedCtx);
     try {
       await inner(event, ctx);
     } catch (error) {
       deps.recordRuntimeEvent?.("message-activity", error, { phase });
     } finally {
-      ensureTyping(typedCtx);
+      if (isCurrent()) ensureTyping(typedCtx);
     }
   };
   return {

package/lib/machine.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure state-machine runner
+ * Zones: shared utils
+ * Owns committing a pure transition's next state, running the effects it returns and waking state waiters
+ * Knows nothing about the machines it drives: their state, events, effects, timers and transports stay with each domain
+ */
+
+/** One transition result: the next state plus effects as data. A machine may add fields, such as a call result. */
+export interface TelegramMachineStep<State, Effect> {
+  state: State;
+  effects: readonly Effect[];
+}
+
+export interface TelegramMachineRunner<State, Event, Step> {
+  readonly state: State;
+  /** Commits the next state, runs its effects (which may dispatch again), wakes waiters and returns the step. */
+  dispatch(event: Event): Step;
+  /** Resolves once `ready` holds for the committed state, checking now and after every later dispatch. */
+  waitFor(ready: (state: State) => boolean): Promise<void>;
+}
+
+export function createTelegramMachineRunner<
+  State,
+  Event,
+  Effect,
+  Step extends TelegramMachineStep<State, Effect> = TelegramMachineStep<
+    State,
+    Effect
+  >,
+>(options: {
+  initial: State;
+  transition: (state: State, event: Event) => Step;
+  run: (effect: Effect) => void;
+}): TelegramMachineRunner<State, Event, Step> {
+  let state = options.initial;
+  const waiters = new Set<() => void>();
+  return {
+    get state(): State {
+      return state;
+    },
+    dispatch(event: Event): Step {
+      const next = options.transition(state, event);
+      state = next.state;
+      for (const effect of next.effects) options.run(effect);
+      for (const waiter of [...waiters]) waiter();
+      return next;
+    },
+    waitFor(ready: (state: State) => boolean): Promise<void> {
+      return new Promise((resolve) => {
+        if (ready(state)) return resolve();
+        const waiter = (): void => {
+          if (!ready(state)) return;
+          waiters.delete(waiter);
+          resolve();
+        };
+        waiters.add(waiter);
+      });
+    },
+  };
+}