@llblab/pi-telegram 0.54.3 → 0.55.0

package/dist/lib/model.d.ts

@@ -3,6 +3,7 @@
  * Zones: pi agent model control, telegram controls, queue continuation
  * Owns model identity, thinking levels, scoped resolution, current-model state, and in-flight model switching
  */
+import * as Machine from "./machine.ts";
 import { type PendingTelegramTurn } from "./queue.ts";
 export interface MenuModel {
     provider: string;
@@ -44,17 +45,10 @@ export declare function parseTelegramScopedModelPatternList(value: string): stri
 export declare function parseTelegramCliScopedModelPatterns(args: string[]): string[] | undefined;
 export declare function resolveScopedModelPatterns<TModel extends MenuModel = MenuModel>(patterns: string[], availableModels: TModel[]): ScopedTelegramModel<TModel>[];
 export declare function sortScopedModels<TModel extends MenuModel = MenuModel>(models: ScopedTelegramModel<TModel>[], currentModel: TModel | undefined): ScopedTelegramModel<TModel>[];
-export interface PendingModelSwitchStore<TSelection> {
-    get: () => TSelection | undefined;
-    set: (selection: TSelection | undefined) => void;
-    clear: () => void;
-    has: () => boolean;
-}
 export interface TelegramInFlightModelSwitchState {
     isIdle: boolean;
     hasAbortHandler: boolean;
 }
-export declare function createPendingModelSwitchStore<TSelection>(): PendingModelSwitchStore<TSelection>;
 export declare function canRestartAgentRunForTelegramModelSwitch(state: TelegramInFlightModelSwitchState): boolean;
 export declare function shouldTriggerPendingTelegramModelSwitchAbort(state: {
     hasPendingModelSwitch: boolean;
@@ -62,12 +56,6 @@ export declare function shouldTriggerPendingTelegramModelSwitchAbort(state: {
     hasAbortHandler: boolean;
     activeToolExecutions: number;
 }): boolean;
-export declare function restartTelegramModelSwitchContinuation<TTurn, TSelection>(state: {
-    activeTurn: TTurn | undefined;
-    abort: (() => void) | undefined;
-    selection: TSelection;
-    queueContinuation: (turn: TTurn, selection: TSelection) => void;
-}): boolean;
 export declare function buildTelegramModelSwitchContinuationText<TModel extends MenuModel>(telegramPrefix: string, model: TModel, thinkingLevel?: ScopedTelegramModel<TModel>["thinkingLevel"]): string;
 export type TelegramModelSwitchContinuationSource = Pick<PendingTelegramTurn, "chatId" | "replyToMessageId" | "target">;
 export declare function buildTelegramModelSwitchContinuationTurn<TModel extends MenuModel>(options: {
@@ -100,8 +88,6 @@ export declare function createTelegramModelSwitchContinuationQueueRuntime<TConte
 }): (turn: TelegramModelSwitchContinuationSource, selection: TSelection, ctx: TContext) => void;
 export interface TelegramModelSwitchControllerDeps<TContext, TSelection> {
     isIdle: (ctx: TContext) => boolean;
-    getPendingModelSwitch: () => TSelection | undefined;
-    setPendingModelSwitch: (selection: TSelection | undefined) => void;
     getActiveTurn: () => PendingTelegramTurn | undefined;
     getAbortHandler: () => (() => void) | undefined;
     hasAbortHandler: () => boolean;
@@ -111,6 +97,8 @@ export interface TelegramModelSwitchControllerDeps<TContext, TSelection> {
 }
 export interface TelegramModelSwitchController<TContext, TSelection> {
     canOfferInFlightSwitch: (ctx: TContext) => boolean;
+    /** A staged switch waits for its abort; queue dispatch and live-work observation treat it as pending control. */
+    hasPendingSwitch: () => boolean;
     stagePendingSwitch: (selection: TSelection, ctx: TContext, continuationTurn?: TelegramModelSwitchContinuationSource) => void;
     clearPendingSwitch: () => void;
     queueContinuation: (turn: TelegramModelSwitchContinuationSource, selection: TSelection, ctx: TContext) => void;
@@ -124,4 +112,55 @@ export interface TelegramModelSwitchControllerRuntimeDeps<TContext, TSelection e
     appendQueuedItem: (item: PendingTelegramTurn, ctx: TContext) => void;
 }
 export declare function createTelegramModelSwitchControllerRuntime<TContext, TSelection extends ScopedTelegramModel>(deps: TelegramModelSwitchControllerRuntimeDeps<TContext, TSelection>): TelegramModelSwitchController<TContext, TSelection>;
+/** The whole model-switch state; only `transitionTelegramModelSwitch` produces a new one. */
+export interface TelegramModelSwitchMachineState<TSelection> {
+    /** One staged switch: the selection and the turn its continuation answers move and clear together. */
+    readonly pending: {
+        readonly selection: TSelection;
+        /** The active Telegram turn at staging, or the model menu's own target for a local run. */
+        readonly turn?: TelegramModelSwitchContinuationSource;
+    } | null;
+}
+/** Facts owned by other domains, sampled by the shell when the event is dispatched. */
+interface TelegramModelSwitchRunFacts {
+    activeTurn?: TelegramModelSwitchContinuationSource;
+    hasAbortHandler: boolean;
+    activeToolExecutions: number;
+}
+export type TelegramModelSwitchEvent<TSelection> = {
+    type: "staged";
+    selection: TSelection;
+    turn?: TelegramModelSwitchContinuationSource;
+} | ({
+    type: "abortRequested";
+} & TelegramModelSwitchRunFacts) | {
+    type: "restartRequested";
+    selection: TSelection;
+    turn?: TelegramModelSwitchContinuationSource;
+    hasAbortHandler: boolean;
+} | {
+    type: "cleared";
+};
+export type TelegramModelSwitchEffect<TSelection> = {
+    type: "queueContinuation";
+    turn: TelegramModelSwitchContinuationSource;
+    selection: TSelection;
+} | {
+    type: "abort";
+};
+export interface TelegramModelSwitchStep<TSelection> extends Machine.TelegramMachineStep<TelegramModelSwitchMachineState<TSelection>, TelegramModelSwitchEffect<TSelection>> {
+    /** `abortRequested` / `restartRequested`: the run was stopped for a continuation. */
+    result: boolean;
+}
+export declare function createTelegramModelSwitchMachineState<TSelection>(): TelegramModelSwitchMachineState<TSelection>;
+/**
+ * Pure model-switch transition. A staged switch fires only once no tool runs and an abort handler exists; any restart
+ * or clear consumes the staged switch too, so a stale selection can never abort the continuation run it started.
+ */
+export declare function transitionTelegramModelSwitch<TSelection>(state: TelegramModelSwitchMachineState<TSelection>, event: TelegramModelSwitchEvent<TSelection>): TelegramModelSwitchStep<TSelection>;
+/**
+ * The shell around `transitionTelegramModelSwitch`: it samples the active turn, abort handler and tool count into
+ * events, and runs the continuation and abort effects with the caller's context and the handler it sampled.
+ */
 export declare function createTelegramModelSwitchController<TContext, TSelection>(deps: TelegramModelSwitchControllerDeps<TContext, TSelection>): TelegramModelSwitchController<TContext, TSelection>;
+export {};

package/dist/lib/model.js

@@ -3,6 +3,7 @@
  * Zones: pi agent model control, telegram controls, queue continuation
  * Owns model identity, thinking levels, scoped resolution, current-model state, and in-flight model switching
  */
+import * as Machine from "./machine.js";
 import { truncateTelegramQueueSummary, } from "./queue.js";
 import { TELEGRAM_PREFIX } from "./turns.js";
 export const THINKING_LEVELS = [
@@ -249,19 +250,6 @@ export function sortScopedModels(models, currentModel) {
     });
     return sorted;
 }
-export function createPendingModelSwitchStore() {
-    let selection;
-    return {
-        get: () => selection,
-        set: (nextSelection) => {
-            selection = nextSelection;
-        },
-        clear: () => {
-            selection = undefined;
-        },
-        has: () => selection !== undefined,
-    };
-}
 export function canRestartAgentRunForTelegramModelSwitch(state) {
     return !state.isIdle && state.hasAbortHandler;
 }
@@ -271,13 +259,6 @@ export function shouldTriggerPendingTelegramModelSwitchAbort(state) {
         state.hasAbortHandler &&
         state.activeToolExecutions === 0);
 }
-export function restartTelegramModelSwitchContinuation(state) {
-    if (!state.activeTurn || !state.abort)
-        return false;
-    state.queueContinuation(state.activeTurn, state.selection);
-    state.abort();
-    return true;
-}
 export function buildTelegramModelSwitchContinuationText(telegramPrefix, model, thinkingLevel) {
     const modelLabel = `${model.provider}/${model.id}`;
     const thinkingSuffix = thinkingLevel ? `; thinking: ${thinkingLevel}` : "";
@@ -332,8 +313,6 @@ export function createTelegramModelSwitchContinuationQueueRuntime(deps) {
 export function createTelegramModelSwitchControllerRuntime(deps) {
     return createTelegramModelSwitchController({
         isIdle: deps.isIdle,
-        getPendingModelSwitch: deps.getPendingModelSwitch,
-        setPendingModelSwitch: deps.setPendingModelSwitch,
         getActiveTurn: deps.getActiveTurn,
         getAbortHandler: deps.getAbortHandler,
         hasAbortHandler: deps.hasAbortHandler,
@@ -347,36 +326,106 @@ export function createTelegramModelSwitchControllerRuntime(deps) {
         updateStatus: deps.updateStatus,
     });
 }
+export function createTelegramModelSwitchMachineState() {
+    return { pending: null };
+}
+/** The continuation is queued before the abort, so the stopped run always has its successor waiting. */
+const restartFor = (turn, selection) => ({
+    state: { pending: null },
+    effects: [{ type: "queueContinuation", turn, selection }, { type: "abort" }],
+    result: true,
+});
+/**
+ * Pure model-switch transition. A staged switch fires only once no tool runs and an abort handler exists; any restart
+ * or clear consumes the staged switch too, so a stale selection can never abort the continuation run it started.
+ */
+export function transitionTelegramModelSwitch(state, event) {
+    const unchanged = { state, effects: [], result: false };
+    switch (event.type) {
+        case "staged":
+            return {
+                state: {
+                    pending: {
+                        selection: event.selection,
+                        ...(event.turn ? { turn: event.turn } : {}),
+                    },
+                },
+                effects: [],
+                result: false,
+            };
+        case "abortRequested": {
+            const pending = state.pending;
+            const turn = pending?.turn ?? event.activeTurn;
+            if (!pending ||
+                !turn ||
+                !shouldTriggerPendingTelegramModelSwitchAbort({
+                    hasPendingModelSwitch: true,
+                    hasContinuationTurn: true,
+                    hasAbortHandler: event.hasAbortHandler,
+                    activeToolExecutions: event.activeToolExecutions,
+                }))
+                return unchanged;
+            return restartFor(turn, pending.selection);
+        }
+        case "restartRequested":
+            return event.turn && event.hasAbortHandler
+                ? restartFor(event.turn, event.selection)
+                : unchanged;
+        case "cleared":
+            return { state: { pending: null }, effects: [], result: false };
+    }
+}
+/**
+ * The shell around `transitionTelegramModelSwitch`: it samples the active turn, abort handler and tool count into
+ * events, and runs the continuation and abort effects with the caller's context and the handler it sampled.
+ */
 export function createTelegramModelSwitchController(deps) {
-    let pendingContinuationTurn;
-    const triggerPendingAbort = (ctx) => {
-        const turn = pendingContinuationTurn ?? deps.getActiveTurn();
-        if (!shouldTriggerPendingTelegramModelSwitchAbort({
-            hasPendingModelSwitch: !!deps.getPendingModelSwitch(),
-            hasContinuationTurn: !!turn,
-            hasAbortHandler: deps.hasAbortHandler(),
-            activeToolExecutions: deps.getActiveToolExecutions(),
-        })) {
-            return false;
+    // The context and abort handler of the call being dispatched; effects run synchronously inside that dispatch.
+    let call;
+    const machine = Machine.createTelegramMachineRunner({
+        initial: createTelegramModelSwitchMachineState(),
+        transition: transitionTelegramModelSwitch,
+        run(effect) {
+            if (!call)
+                return;
+            if (effect.type === "queueContinuation")
+                deps.queueContinuation(effect.turn, effect.selection, call.ctx);
+            else
+                call.abort?.();
+        },
+    });
+    const dispatchFor = (ctx, abort, event) => {
+        const preceding = call;
+        call = { ctx, abort };
+        try {
+            return machine.dispatch(event).result;
+        }
+        finally {
+            call = preceding;
         }
-        const selection = deps.getPendingModelSwitch();
+    };
+    const triggerPendingAbort = (ctx) => {
         const abort = deps.getAbortHandler();
-        if (!selection || !turn || !abort)
-            return false;
-        pendingContinuationTurn = undefined;
-        deps.setPendingModelSwitch(undefined);
-        deps.queueContinuation(turn, selection, ctx);
-        abort();
-        return true;
+        return dispatchFor(ctx, abort, {
+            type: "abortRequested",
+            activeTurn: deps.getActiveTurn(),
+            hasAbortHandler: deps.hasAbortHandler() && !!abort,
+            activeToolExecutions: deps.getActiveToolExecutions(),
+        });
     };
     return {
         canOfferInFlightSwitch: (ctx) => canRestartAgentRunForTelegramModelSwitch({
             isIdle: deps.isIdle(ctx),
             hasAbortHandler: deps.hasAbortHandler(),
         }),
+        hasPendingSwitch: () => machine.state.pending !== null,
         stagePendingSwitch: (selection, ctx, continuationTurn) => {
-            pendingContinuationTurn = deps.getActiveTurn() ?? continuationTurn;
-            deps.setPendingModelSwitch(selection);
+            const turn = deps.getActiveTurn() ?? continuationTurn;
+            machine.dispatch({
+                type: "staged",
+                selection,
+                ...(turn ? { turn } : {}),
+            });
             try {
                 deps.updateStatus(ctx);
             }
@@ -385,23 +434,19 @@ export function createTelegramModelSwitchController(deps) {
             }
         },
         clearPendingSwitch: () => {
-            pendingContinuationTurn = undefined;
-            deps.setPendingModelSwitch(undefined);
+            machine.dispatch({ type: "cleared" });
         },
         queueContinuation: deps.queueContinuation,
         triggerPendingAbort,
         restartInterruptedTurn: (selection, ctx, continuationTurn) => {
-            const restarted = restartTelegramModelSwitchContinuation({
-                activeTurn: deps.getActiveTurn() ?? continuationTurn,
-                abort: deps.getAbortHandler(),
+            const abort = deps.getAbortHandler();
+            const turn = deps.getActiveTurn() ?? continuationTurn;
+            return dispatchFor(ctx, abort, {
+                type: "restartRequested",
                 selection,
-                queueContinuation: (turn, nextSelection) => {
-                    deps.queueContinuation(turn, nextSelection, ctx);
-                },
+                ...(turn ? { turn } : {}),
+                hasAbortHandler: !!abort,
             });
-            if (restarted)
-                pendingContinuationTurn = undefined;
-            return restarted;
         },
     };
 }

package/dist/lib/polling.js

@@ -893,6 +893,8 @@ export function createTelegramThreadCapabilityMonitor(deps) {
     return {
         start(ctx) {
             stop();
+            // Disabled-mode confirmation counts consecutive probes of one run, never observations from before a restart.
+            consecutiveDisabledProbes = 0;
             const expectedGeneration = generation;
             interval = setInterval(() => {
                 if (generation !== expectedGeneration)

package/dist/lib/preview.d.ts

@@ -2,42 +2,28 @@
  * Telegram preview streaming helpers
  * Zones: telegram outbound, native rich markdown drafts
  * Owns safe draft preview selection, runtime updates, and preview finalization
+ * The streaming state machine is a pure transition function driven by one imperative shell per runtime.
  */
 import type { TelegramAssistantOutputPreparation } from "./activity.ts";
 import { type TelegramTarget } from "./target.ts";
-export type TelegramDraftSupport = "unknown" | "supported";
 export interface TelegramPreviewState {
     mode: "draft";
     draftId?: number;
     pendingText: string;
     lastSentText: string;
 }
-export interface TelegramPreviewRuntimeState extends TelegramPreviewState {
-    flushPromise?: Promise<void>;
-    flushRequested?: boolean;
-    precedingFlush?: Promise<void>;
-    publicationPromise?: Promise<void>;
-    sealed?: boolean;
-    nextDraftAt?: number;
-    flushTimer?: ReturnType<typeof setTimeout>;
+/** One immutable preview segment; a replacement segment gets a new id, so late results for an old one are dropped. */
+export interface TelegramPreviewSegment extends Readonly<TelegramPreviewState> {
+    readonly id: number;
+    readonly sealed: boolean;
 }
 export type TelegramPreviewReplyMarkup = unknown;
-export interface TelegramPreviewRuntimeDeps {
-    getState: () => TelegramPreviewRuntimeState | undefined;
-    setState: (state: TelegramPreviewRuntimeState | undefined) => void;
-    maxMessageLength: number;
-    minDraftIntervalMs?: number;
-    getDraftSupport: () => TelegramDraftSupport;
-    setDraftSupport: (support: TelegramDraftSupport) => void;
-    allocateDraftId: () => number;
-    sendDraft: (chatId: number, draftId: number, text?: string, options?: {
-        parse_mode?: string;
-        entities?: unknown[];
-        message_thread_id?: number;
-    }) => Promise<unknown>;
-    canSend?: () => boolean;
-    recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
-}
+type TelegramDraftSender = (chatId: number, draftId: number, text?: string, options?: {
+    parse_mode?: string;
+    entities?: unknown[];
+    message_thread_id?: number;
+}) => Promise<unknown>;
+type TelegramPreviewEventRecorder = (category: string, error: unknown, details?: Record<string, unknown>) => void;
 export interface TelegramPreviewActiveTurn {
     chatId: number;
     replyToMessageId?: number;
@@ -46,28 +32,6 @@ export interface TelegramPreviewActiveTurn {
     voiceReplyRequired?: boolean;
     guestQueryId?: string;
 }
-export interface TelegramAssistantMessagePreviewStartDeps<TMessage> {
-    getActiveTurn: () => TelegramPreviewActiveTurn | undefined;
-    isAssistantMessage: (message: TMessage) => boolean;
-    getState: () => TelegramPreviewRuntimeState | undefined;
-    setState: (state: TelegramPreviewRuntimeState | undefined) => void;
-    createPreviewState: () => TelegramPreviewRuntimeState;
-    canSend?: () => boolean;
-}
-export interface TelegramAssistantMessagePreviewUpdateDeps<TMessage> {
-    getActiveTurn: () => TelegramPreviewActiveTurn | undefined;
-    isAssistantMessage: (message: TMessage) => boolean;
-    getState: () => TelegramPreviewRuntimeState | undefined;
-    setState: (state: TelegramPreviewRuntimeState | undefined) => void;
-    createPreviewState: () => TelegramPreviewRuntimeState;
-    canSend?: () => boolean;
-    getMessageText: (message: TMessage) => string;
-    minDraftIntervalMs?: number;
-    schedulePreviewFlush: (chatId: number, options?: {
-        target?: TelegramTarget;
-    }) => void;
-}
-export type TelegramAssistantMessagePreviewHookDeps<TMessage> = TelegramAssistantMessagePreviewStartDeps<TMessage> & TelegramAssistantMessagePreviewUpdateDeps<TMessage>;
 export interface TelegramAssistantMessagePreviewHookEvent<TMessage> {
     message: TMessage;
 }
@@ -78,46 +42,37 @@ export interface TelegramAssistantMessagePreviewHooks<TMessage> {
 export interface TelegramPreviewControllerDeps {
     getDefaultReplyToMessageId?: () => number | undefined;
     maxMessageLength?: number;
-    initialDraftSupport?: TelegramDraftSupport;
-    sendDraft: (chatId: number, draftId: number, text?: string, options?: {
-        parse_mode?: string;
-        entities?: unknown[];
-        message_thread_id?: number;
-    }) => Promise<unknown>;
+    sendDraft: TelegramDraftSender;
     canSend?: () => boolean;
     maxDraftId?: number;
-    recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
+    /** Throttle between draft frames; defaults to the native draft cadence. */
+    minDraftIntervalMs?: number;
+    recordRuntimeEvent?: TelegramPreviewEventRecorder;
 }
+type TelegramPreviewTargetOptions = {
+    target?: TelegramTarget;
+};
 export interface TelegramPreviewController {
+    /** Read-only view of the current segment; it never grants mutation. */
+    getState: () => TelegramPreviewSegment | undefined;
+    /** True while a draft request is in flight or a pending request waits behind a publication. */
+    isFlushing: () => boolean;
     seal: () => void;
     preparePublication: () => TelegramAssistantOutputPreparation | undefined;
-    prepareClear: (chatId: number, options?: {
-        target?: TelegramTarget;
+    prepareClear: (chatId: number, options?: TelegramPreviewTargetOptions & {
         isDeliveryActive?: () => boolean;
     }) => () => Promise<void>;
-    getState: () => TelegramPreviewRuntimeState | undefined;
-    setState: (state: TelegramPreviewRuntimeState | undefined) => void;
     setPendingText: (text: string) => void;
-    createState: () => TelegramPreviewRuntimeState;
     resetState: () => void;
     invalidate: () => void;
-    clear: (chatId: number, options?: {
+    clear: (chatId: number, options?: TelegramPreviewTargetOptions & {
         awaitFlush?: boolean;
-        target?: TelegramTarget;
-    }) => Promise<void>;
-    flush: (chatId: number, options?: {
-        target?: TelegramTarget;
     }) => Promise<void>;
-    scheduleFlush: (chatId: number, options?: {
-        target?: TelegramTarget;
-    }) => void;
-    finalize: (chatId: number, replyToMessageId?: number, options?: {
-        target?: TelegramTarget;
-    }) => Promise<boolean>;
+    flush: (chatId: number, options?: TelegramPreviewTargetOptions) => Promise<void>;
+    scheduleFlush: (chatId: number, options?: TelegramPreviewTargetOptions) => void;
+    finalize: (chatId: number, replyToMessageId?: number, options?: TelegramPreviewTargetOptions) => Promise<boolean>;
 }
-export type TelegramPreviewControllerRuntimeDeps = TelegramPreviewControllerDeps;
-export declare function createTelegramPreviewControllerRuntime(deps: TelegramPreviewControllerRuntimeDeps): TelegramPreviewController;
-export interface TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup = TelegramPreviewReplyMarkup> extends TelegramPreviewControllerRuntimeDeps {
+export interface TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup = TelegramPreviewReplyMarkup> extends TelegramPreviewControllerDeps {
     getActiveTurn: () => TelegramPreviewActiveTurn | undefined;
     isAssistantMessage: (message: TMessage) => boolean;
     getMessageText: (message: TMessage) => string;
@@ -126,35 +81,113 @@ export interface TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup = Te
         target?: TelegramTarget;
     }) => Promise<number | undefined>;
 }
+type TelegramMarkdownFinalizer<TReplyMarkup> = (chatId: number, markdown: string, replyToMessageId?: number, options?: {
+    replyMarkup?: TReplyMarkup;
+    target?: TelegramTarget;
+}) => Promise<boolean>;
 export interface TelegramPreparedPreviewDelivery<TReplyMarkup = unknown> {
     clearPreview: TelegramPreviewController["clear"];
     setPreviewPendingText: TelegramPreviewController["setPendingText"];
-    finalizeMarkdownPreview: ReturnType<typeof createTelegramNativeMarkdownPreviewFinalizer<TReplyMarkup>>;
+    finalizeMarkdownPreview: TelegramMarkdownFinalizer<TReplyMarkup>;
 }
 export type TelegramAssistantPreviewRuntime<TMessage, TReplyMarkup = TelegramPreviewReplyMarkup> = TelegramPreviewController & TelegramAssistantMessagePreviewHooks<TMessage> & {
     prepareDelivery: (isDeliveryActive: () => boolean) => TelegramPreparedPreviewDelivery<TReplyMarkup>;
-    finalizeMarkdown: (chatId: number, markdown: string, replyToMessageId?: number, options?: {
-        replyMarkup?: TReplyMarkup;
-        target?: TelegramTarget;
-    }) => Promise<boolean>;
+    finalizeMarkdown: TelegramMarkdownFinalizer<TReplyMarkup>;
 };
-export declare function createTelegramNativeMarkdownPreviewFinalizer<TReplyMarkup>(deps: {
-    getState: () => TelegramPreviewRuntimeState | undefined;
-    clear: (chatId: number, options?: {
-        awaitFlush?: boolean;
-        target?: TelegramTarget;
-    }) => Promise<void>;
-    discard?: () => void;
-    isDeliveryActive?: () => boolean;
-    sendMarkdownReply: (chatId: number, replyToMessageId: number | undefined, markdown: string, options?: {
-        replyMarkup?: TReplyMarkup;
-        target?: TelegramTarget;
-    }) => Promise<number | undefined>;
-}): (chatId: number, markdown: string, replyToMessageId?: number, options?: {
-    replyMarkup?: TReplyMarkup;
+interface TelegramPreviewFlushRequest {
+    chatId: number;
     target?: TelegramTarget;
-}) => Promise<boolean>;
-export declare function createTelegramAssistantPreviewRuntime<TMessage, TReplyMarkup = TelegramPreviewReplyMarkup>(deps: TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup>): TelegramAssistantPreviewRuntime<TMessage, TReplyMarkup>;
+}
+interface TelegramPreviewMachineConfig {
+    maxDraftId: number;
+    maxMessageLength: number;
+    minDraftIntervalMs: number;
+}
+/** The whole preview state; only `transitionTelegramPreview` produces a new one. */
+export interface TelegramPreviewMachineState {
+    readonly segment: TelegramPreviewSegment | null;
+    /** Bumped by reset and invalidation; a result issued under an older generation is inert. */
+    readonly generation: number;
+    readonly nextSegmentId: number;
+    readonly nextDraftId: number;
+    readonly nextDraftAt: number;
+    /** Segment that owns the current generation's issued draft; old-generation requests do not block it. */
+    readonly inFlight: number | null;
+    /** The one coalesced flush request waiting behind an in-flight draft or an open publication. */
+    readonly pending: TelegramPreviewFlushRequest | null;
+    readonly publications: readonly number[];
+    /** The segment the throttle timer is armed for; the timer belongs to that segment alone. */
+    readonly timerSegmentId: number | null;
+}
+/** Impure inputs the runner samples at dispatch time, so transitions stay pure. */
+interface TelegramPreviewClock {
+    now: number;
+    canSend: boolean;
+}
+export type TelegramPreviewEvent = {
+    type: "reset";
+} | {
+    type: "invalidated";
+} | {
+    type: "segmentStarted";
+} | {
+    type: "segmentEnsured";
+} | {
+    type: "sealed";
+} | {
+    type: "discarded";
+} | {
+    type: "textSet";
+    text: string;
+} | {
+    type: "draftWindowOpened";
+    at: number;
+} | ({
+    type: "flushRequested";
+    request: TelegramPreviewFlushRequest;
+} & TelegramPreviewClock) | ({
+    type: "timerFired";
+    request: TelegramPreviewFlushRequest;
+    segmentId: number;
+} & TelegramPreviewClock) | ({
+    type: "draftSettled";
+    segmentId: number;
+    generation: number;
+    /** Present only when Telegram accepted the draft. */
+    text?: string;
+} & TelegramPreviewClock) | {
+    type: "publicationOpened";
+    id: number;
+} | ({
+    type: "publicationSettled";
+    id: number;
+} & TelegramPreviewClock);
+export type TelegramPreviewEffect = {
+    type: "sendDraft";
+    request: TelegramPreviewFlushRequest;
+    draftId: number;
+    text: string;
+    segmentId: number;
+    generation: number;
+} | {
+    type: "armTimer";
+    delay: number;
+    request: TelegramPreviewFlushRequest;
+    segmentId: number;
+} | {
+    type: "cancelTimer";
+} | {
+    type: "clearClosedGate";
+    request: TelegramPreviewFlushRequest;
+};
+export interface TelegramPreviewStep {
+    state: TelegramPreviewMachineState;
+    effects: readonly TelegramPreviewEffect[];
+}
+export declare function createTelegramPreviewMachineState(): TelegramPreviewMachineState;
+export declare function transitionTelegramPreview(state: TelegramPreviewMachineState, event: TelegramPreviewEvent, config: TelegramPreviewMachineConfig): TelegramPreviewStep;
+/** True while a draft request is in flight, or, when publications block, a pending request waits behind one. */
+export declare function isTelegramPreviewBusy(state: TelegramPreviewMachineState, blockedByPublication?: boolean): boolean;
 export declare function createTelegramPreviewController(deps: TelegramPreviewControllerDeps): TelegramPreviewController;
 /**
  * Returns true when the active turn is a Telegram Guest Mode query. A guest
@@ -164,26 +197,8 @@ export declare function createTelegramPreviewController(deps: TelegramPreviewCon
 export declare function shouldSuppressPreviewForGuestTurn(turn: {
     guestQueryId?: string;
 } | null | undefined): boolean;
+export declare function createTelegramAssistantPreviewRuntime<TMessage, TReplyMarkup = TelegramPreviewReplyMarkup>(deps: TelegramAssistantPreviewRuntimeDeps<TMessage, TReplyMarkup>): TelegramAssistantPreviewRuntime<TMessage, TReplyMarkup>;
 export declare function buildTelegramPreviewFinalText(state: TelegramPreviewState): string | undefined;
-export declare function createTelegramPreviewRuntimeState(): TelegramPreviewRuntimeState;
 export declare function allocateTelegramDraftId(currentDraftId: number, maxDraftId: number): number;
-interface TelegramNativeMarkdownPreviewSnapshot {
-    text: string;
-}
-export declare function shouldUseTelegramDraftPreview(_options: {
-    draftSupport: TelegramDraftSupport;
-    snapshot?: TelegramNativeMarkdownPreviewSnapshot;
-}): boolean;
-export declare function clearTelegramPreview(chatId: number, deps: TelegramPreviewRuntimeDeps, options?: {
-    awaitFlush?: boolean;
-    target?: TelegramTarget;
-    isDeliveryActive?: () => boolean;
-}): Promise<void>;
 export declare function getSafeTelegramRichMarkdownDraftPrefix(markdown: string, maxMessageLength: number): string | undefined;
-export declare function flushTelegramPreview(chatId: number, deps: TelegramPreviewRuntimeDeps, options?: {
-    target?: TelegramTarget;
-}): Promise<void>;
-export declare function finalizeTelegramPreview(chatId: number, deps: TelegramPreviewRuntimeDeps, options?: {
-    target?: TelegramTarget;
-}): Promise<boolean>;
 export {};