@krischoichoi/channel-telegram 0.6.0

package/lib/rich-streaming-reply.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `TelegramRichStreamingReply` — DSH `ReplyHandle` over Bot API 10.1 rich
+ * drafts (plan §6.1 / §20.4).
+ *
+ * For private DMs with rich output active, the plan replaces per-delta
+ * `editMessageText` with the native rich draft flow:
+ *
+ *   sendRichMessageDraft(draft_id)   → 30s temporary preview, updated in place
+ *   … (throttled by ReplyRouter)     →  same draft_id re-sent with the growing
+ *                                       partial Markdown
+ *   sendRichMessage(final)           →  persists the final result; the draft
+ *                                       preview is superseded
+ *
+ * The draft is inherently *partial-safe*: the server renders whatever has been
+ * sent so far, so an unfinished code fence / table / link never breaks the
+ * pipeline (plan §20.4 Partial Markdown Gate). Only the final `sendRichMessage`
+ * renders the *complete* Markdown; on a format failure the final falls back to
+ * plain text once (never an infinite rich→plain→rich loop).
+ *
+ * The handle does NOT throttle internally — ReplyRouter owns throttling via
+ * config `reply.updateIntervalMs`. Operations are serialized so concurrent
+ * router flushes cannot interleave.
+ */
+import type { ChannelTarget, OutboundMessage, ReplyHandle } from '@krischoichoi/channel-core';
+import type { TelegramUpstream } from './upstream.js';
+import { type RenderOptions } from './render/index.js';
+export interface TelegramRichStreamingReplyOptions {
+    /** Output formatting policy (mode/fallback) for the final rich send. */
+    formatting?: Partial<RenderOptions>;
+}
+export declare class TelegramRichStreamingReply implements ReplyHandle {
+    private readonly upstream;
+    private readonly target;
+    private readonly placeholder;
+    private readonly options;
+    private text;
+    private draftId;
+    private started;
+    private finalized;
+    private draftPending;
+    private finalPending;
+    private cooldownUntil;
+    private cooldownTimer;
+    private queue;
+    constructor(upstream: TelegramUpstream, target: ChannelTarget, placeholder?: string, options?: TelegramRichStreamingReplyOptions, draftId?: number);
+    get activeDraftId(): number;
+    /** Open the temporary draft preview. */
+    start(): Promise<void>;
+    append(delta: string): Promise<void>;
+    replace(message: OutboundMessage): Promise<void>;
+    finish(message?: OutboundMessage): Promise<void>;
+    fail(error: unknown): Promise<void>;
+    /** Re-send the same draft id with the newest partial Markdown preview. */
+    private flushDraft;
+    /**
+     * Persist the final result. For DM rich mode the final is one (or, when
+     * overflowing, several) `sendRichMessage` calls carrying the complete
+     * Markdown; a format failure falls back to plain exactly once.
+     */
+    private flushFinal;
+    private sendFinal;
+    private enqueue;
+    private inCooldown;
+    /** Keep only the current draft/final state while Telegram asks us to wait. */
+    private enterCooldown;
+    private scheduleCooldown;
+    private clearCooldown;
+}
+//# sourceMappingURL=rich-streaming-reply.d.ts.map

package/lib/rich-streaming-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-streaming-reply.d.ts","sourceRoot":"","sources":["../src/rich-streaming-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAQzE,MAAM,WAAW,iCAAiC;IAChD,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CACrC;AAED,qBAAa,0BAA2B,YAAW,WAAW;IAY1D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAd1B,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,KAAK,CAAoC;gBAG9B,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,aAAa,EACrB,WAAW,SAAM,EACjB,OAAO,GAAE,iCAAsC,EAChE,OAAO,CAAC,EAAE,MAAM;IAKlB,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,wCAAwC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpC,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhD,MAAM,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhD,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBnC,0EAA0E;YAC5D,UAAU;IAkBxB;;;;OAIG;YACW,UAAU;YAaV,SAAS;IAyBvB,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,UAAU;IAMlB,8EAA8E;IAC9E,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,aAAa;CAOtB"}

package/lib/rich-streaming-reply.js

@@ -0,0 +1,207 @@
+import { TelegramApiError } from './api-error.js';
+import { RICH_MESSAGE_MAX_UTF8 } from './rich-message.js';
+import { truncateGraphemes } from './render/segment.js';
+import { sendWithFallback } from './render/index.js';
+/** A non-zero integer that identifies this reply stream across draft updates. */
+function newDraftId() {
+    const value = globalThis.crypto.getRandomValues(new Uint32Array(1))[0] ?? 0;
+    return value === 0 ? 1 : value;
+}
+export class TelegramRichStreamingReply {
+    upstream;
+    target;
+    placeholder;
+    options;
+    text = '';
+    draftId;
+    started = false;
+    finalized = false;
+    draftPending = false;
+    finalPending = false;
+    cooldownUntil = 0;
+    cooldownTimer;
+    queue = Promise.resolve();
+    constructor(upstream, target, placeholder = '…', options = {}, draftId) {
+        this.upstream = upstream;
+        this.target = target;
+        this.placeholder = placeholder;
+        this.options = options;
+        this.draftId = draftId ?? newDraftId();
+    }
+    get activeDraftId() {
+        return this.draftId;
+    }
+    /** Open the temporary draft preview. */
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.draftPending = true;
+        await this.flushDraft(this.placeholder);
+    }
+    append(delta) {
+        return this.replace({ text: this.text + delta });
+    }
+    replace(message) {
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            if (message.text === undefined)
+                return;
+            this.text = message.text;
+            this.draftPending = true;
+            await this.flushDraft();
+        });
+    }
+    finish(message) {
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            if (message?.text !== undefined)
+                this.text = message.text;
+            this.draftPending = false;
+            this.finalPending = true;
+            await this.flushFinal();
+        });
+    }
+    fail(error) {
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            if (isRateLimit(error))
+                return;
+            this.finalized = true;
+            this.clearCooldown();
+            const msg = `Warning: ${messageOf(error)}`;
+            try {
+                await sendWithFallback(msg, { mode: 'plain' }, (plan) => {
+                    const text = plan.kind === 'rich' ? (plan.texts[0] ?? '') : (plan.chunks[0] ?? '');
+                    return this.upstream.sendMessage(this.target.conversationId, text);
+                });
+            }
+            catch {
+                // Marking failure must not mask the original error.
+            }
+        });
+    }
+    /** Re-send the same draft id with the newest partial Markdown preview. */
+    async flushDraft(placeholder) {
+        if (!this.started || !this.draftPending || this.inCooldown())
+            return;
+        const source = this.text || placeholder;
+        if (!source)
+            return;
+        try {
+            await this.upstream.sendRichMessageDraft(this.target.conversationId, this.draftId, { markdown: truncateGraphemes(source, RICH_MESSAGE_MAX_UTF8) }, targetOptions(this.target));
+            this.draftPending = false;
+        }
+        catch (error) {
+            if (!isRateLimit(error))
+                throw error;
+            this.enterCooldown(error);
+        }
+    }
+    /**
+     * Persist the final result. For DM rich mode the final is one (or, when
+     * overflowing, several) `sendRichMessage` calls carrying the complete
+     * Markdown; a format failure falls back to plain exactly once.
+     */
+    async flushFinal() {
+        if (!this.finalPending || this.inCooldown())
+            return;
+        try {
+            await this.sendFinal();
+            this.finalPending = false;
+            this.finalized = true;
+            this.clearCooldown();
+        }
+        catch (error) {
+            if (!isRateLimit(error))
+                throw error;
+            this.enterCooldown(error);
+        }
+    }
+    async sendFinal() {
+        const options = {
+            mode: this.options.formatting?.mode ?? 'auto',
+        };
+        const source = this.text;
+        if (!source)
+            return;
+        await sendWithFallback(source, options, async (plan) => {
+            if (plan.kind === 'rich') {
+                for (const text of plan.texts) {
+                    await this.upstream.sendRichMessage(this.target.conversationId, { markdown: text }, targetOptions(this.target));
+                }
+                return;
+            }
+            // plain fallback path.
+            for (const chunk of plan.chunks) {
+                await this.upstream.sendMessage(this.target.conversationId, chunk, targetOptions(this.target), plan.parseMode ? { parseMode: plan.parseMode } : undefined);
+            }
+        });
+    }
+    enqueue(task) {
+        const next = this.queue.then(task, task);
+        this.queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    inCooldown() {
+        if (Date.now() >= this.cooldownUntil)
+            return false;
+        this.scheduleCooldown();
+        return true;
+    }
+    /** Keep only the current draft/final state while Telegram asks us to wait. */
+    enterCooldown(error) {
+        const seconds = error.parameters?.retryAfter;
+        const delay = typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0
+            ? Math.ceil(seconds * 1000)
+            : 1_000;
+        this.cooldownUntil = Math.max(this.cooldownUntil, Date.now() + delay);
+        this.scheduleCooldown();
+    }
+    scheduleCooldown() {
+        if (this.cooldownTimer || this.finalized)
+            return;
+        const delay = Math.max(0, this.cooldownUntil - Date.now());
+        this.cooldownTimer = setTimeout(() => {
+            this.cooldownTimer = undefined;
+            void this.enqueue(async () => {
+                if (this.finalized)
+                    return;
+                if (this.finalPending) {
+                    await this.flushFinal();
+                }
+                else {
+                    await this.flushDraft();
+                }
+            });
+        }, delay);
+    }
+    clearCooldown() {
+        this.cooldownUntil = 0;
+        if (this.cooldownTimer) {
+            clearTimeout(this.cooldownTimer);
+            this.cooldownTimer = undefined;
+        }
+    }
+}
+function isRateLimit(error) {
+    return error instanceof TelegramApiError || (typeof error === 'object'
+        && error !== null
+        && 'kind' in error
+        && error.kind === 'rate-limit');
+}
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function targetOptions(target) {
+    return {
+        replyToMessageId: target.replyToMessageId,
+        messageThreadId: target.threadId,
+    };
+}
+//# sourceMappingURL=rich-streaming-reply.js.map

package/lib/rich-streaming-reply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-streaming-reply.js","sourceRoot":"","sources":["../src/rich-streaming-reply.ts"],"names":[],"mappings":"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"}

package/lib/streaming-reply.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `TelegramStreamingReply` — DSH `ReplyHandle` over Telegram edit streaming.
+ *
+ * Telegram streaming is modeled as: send one message, then edit it in place
+ * with `editMessageText` as full-text previews arrive. This maps onto the
+ * reply contract used by ReplyRouter for `streaming: 'edit'`:
+ * - `replace(message)` -> create the message on first content, then edit
+ * - `append(delta)`    -> accumulate and edit full text (kept for symmetry)
+ * - `finish(message?)` -> render + send the final text and close
+ * - `fail(error)`      -> edit a short failure note when a message exists
+ *
+ * ## Preview-freeze fix (plan §3.2 / §6.3 / §20.5)
+ *
+ * The old implementation always edited `chunks[0]`, so once the model passed
+ * 4096 chars the first chunk stopped changing and the preview appeared frozen.
+ * This version shows a *rolling preview*: up to 4096 visible chars it shows the
+ * whole text; beyond that it shows `…` + the newest `4095` graphemes, so the
+ * preview keeps visibly moving while the model streams. The final message is
+ * always sent with complete, stable segmentation.
+ *
+ * ## Group rich final (plan §6.2)
+ *
+ * When configured for rich output on a non-DM target, `finish` upgrades the
+ * same message to a Rich Message with `editMessageRich` (first segment) plus
+ * `sendRichMessage` for any overflow. A formatting error falls back to plain
+ * once; the preview phase always uses plain edits so partial Markdown never
+ * triggers a rich parse (plan §20.5).
+ *
+ * ReplyRouter owns normal throttling via config `reply.updateIntervalMs`.
+ * This handle additionally honors Telegram 429 cooldowns by retaining only
+ * the newest desired preview until the retry window expires.
+ */
+import type { ChannelTarget, OutboundMessage, ReplyHandle } from '@krischoichoi/channel-core';
+import type { TelegramUpstream } from './upstream.js';
+import { type RenderOptions } from './render/index.js';
+export interface TelegramStreamingReplyOptions {
+    /** Output formatting policy for the final message (mode/fallback). */
+    formatting?: Partial<RenderOptions>;
+    /**
+     * When true and rich formatting is active, `finish` edits the SAME message
+     * into a Rich Message (group path); otherwise the final is plain text.
+     */
+    richFinal?: boolean;
+}
+export declare class TelegramStreamingReply implements ReplyHandle {
+    private readonly upstream;
+    private readonly target;
+    private readonly placeholder;
+    private readonly options;
+    private text;
+    private sentPreview;
+    private messageId;
+    private finalized;
+    private queue;
+    /** Latest desired preview; deliberately not an edit queue. */
+    private pendingPreview;
+    private cooldownUntil;
+    private cooldownTimer;
+    private finishing;
+    constructor(upstream: TelegramUpstream, target: ChannelTarget, placeholder?: string, options?: TelegramStreamingReplyOptions);
+    /** Send the initial placeholder message (called once by the adapter). */
+    start(): Promise<void>;
+    append(delta: string): Promise<void>;
+    replace(message: OutboundMessage): Promise<void>;
+    finish(message?: OutboundMessage): Promise<void>;
+    fail(error: unknown): Promise<void>;
+    /** Edit the rolling preview now; on `final` render + send the complete result. */
+    private sync;
+    /**
+     * Send the final message. Plain mode: first chunk edits the existing message,
+     * overflow chunks are sent as new messages. Rich mode (richFinal + rich
+     * formatting): upgrade the same message to a Rich Message; fall back to plain
+     * once on a format error.
+     */
+    private sendFinal;
+    /** Upgrade the in-place message to a Rich Message with plain-once fallback. */
+    private sendRichFinal;
+    /** Retry only the in-place final edit after a Telegram-requested cooldown. */
+    private editFinalText;
+    /** The rich final path uses Telegram's edit endpoint too, so it shares 429 recovery. */
+    private editFinalRich;
+    private isCoolingDown;
+    /** Honor the server's retry hint, extending (never shortening) cooldown. */
+    private startCooldown;
+    /** One timer, one latest-value flush. It never replays a sequence of edits. */
+    private scheduleCooldownFlush;
+    private clearCooldownTimer;
+    private waitForCooldown;
+    private enqueue;
+}
+/**
+ * Build a rolling preview for an in-progress stream: show the whole text up to
+ * `limit`, otherwise `…` + the newest `limit - 1` graphemes. This keeps the
+ * preview visibly changing once the model exceeds the single-message limit
+ * (plan §6.3), fixing the frozen `chunks[0]` behaviour.
+ */
+export declare function makePreview(text: string, limit: number): string;
+//# sourceMappingURL=streaming-reply.d.ts.map

package/lib/streaming-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-reply.d.ts","sourceRoot":"","sources":["../src/streaming-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEzE,MAAM,WAAW,6BAA6B;IAC5C,sEAAsE;IACtE,UAAU,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACpC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,sBAAuB,YAAW,WAAW;IAatD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAf1B,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAoC;IACjD,8DAA8D;IAC9D,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,SAAS,CAAS;gBAGP,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,aAAa,EACrB,WAAW,SAAM,EACjB,OAAO,GAAE,6BAAkC;IAG9D,yEAAyE;IACnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpC,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhD,MAAM,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAehD,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAenC,kFAAkF;YACpE,IAAI;IA2BlB;;;;;OAKG;YACW,SAAS;IAyBvB,+EAA+E;YACjE,aAAa;IAkC3B,8EAA8E;YAChE,aAAa;IAa3B,wFAAwF;YAC1E,aAAa;IAa3B,OAAO,CAAC,aAAa;IAIrB,4EAA4E;IAC5E,OAAO,CAAC,aAAa;IASrB,+EAA+E;IAC/E,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,kBAAkB;YAKZ,eAAe;IAQ7B,OAAO,CAAC,OAAO;CAQhB;AAkBD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/lib/streaming-reply.js

@@ -0,0 +1,274 @@
+import { TelegramApiError } from './api-error.js';
+import { REGULAR_MESSAGE_MAX } from './rich-message.js';
+import { truncateGraphemes, tailGraphemes, visibleLength, splitByGraphemes } from './render/segment.js';
+import { sendWithFallback } from './render/index.js';
+export class TelegramStreamingReply {
+    upstream;
+    target;
+    placeholder;
+    options;
+    text = '';
+    sentPreview;
+    messageId;
+    finalized = false;
+    queue = Promise.resolve();
+    /** Latest desired preview; deliberately not an edit queue. */
+    pendingPreview;
+    cooldownUntil = 0;
+    cooldownTimer;
+    finishing = false;
+    constructor(upstream, target, placeholder = '…', options = {}) {
+        this.upstream = upstream;
+        this.target = target;
+        this.placeholder = placeholder;
+        this.options = options;
+    }
+    /** Send the initial placeholder message (called once by the adapter). */
+    async start() {
+        if (this.messageId)
+            return;
+        const preview = makePreview(this.placeholder, REGULAR_MESSAGE_MAX);
+        const sent = await this.upstream.sendMessage(this.target.conversationId, preview, targetOptions(this.target));
+        this.messageId = sent.messageId;
+        this.sentPreview = preview;
+    }
+    append(delta) {
+        return this.replace({ text: this.text + delta });
+    }
+    replace(message) {
+        return this.enqueue(async () => {
+            if (this.finalized || this.finishing)
+                return;
+            if (message.text === undefined)
+                return;
+            this.text = message.text;
+            this.pendingPreview = makePreview(this.text, REGULAR_MESSAGE_MAX);
+            await this.sync(false);
+        });
+    }
+    finish(message) {
+        // Suppress a deferred preview immediately. `finish` itself may wait in the
+        // operation queue behind one in-flight edit, but no newer preview should
+        // be sent once the turn has ended.
+        this.finishing = true;
+        this.clearCooldownTimer();
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            if (message?.text !== undefined)
+                this.text = message.text;
+            this.pendingPreview = undefined;
+            await this.sync(true);
+            this.finalized = true;
+        });
+    }
+    fail(error) {
+        return this.enqueue(async () => {
+            if (this.finalized)
+                return;
+            if (isRateLimitError(error))
+                return;
+            this.finalized = true;
+            if (!this.messageId)
+                return;
+            const text = truncateGraphemes(`Warning: ${messageOf(error)}`, REGULAR_MESSAGE_MAX);
+            try {
+                await this.upstream.editMessageText(this.target.conversationId, this.messageId, text);
+            }
+            catch {
+                // Marking the message failed must not mask the original error.
+            }
+        });
+    }
+    /** Edit the rolling preview now; on `final` render + send the complete result. */
+    async sync(final) {
+        if (!this.text)
+            return;
+        if (final) {
+            await this.waitForCooldown();
+            await this.sendFinal();
+            return;
+        }
+        if (!this.messageId)
+            return;
+        const preview = this.pendingPreview ?? makePreview(this.text, REGULAR_MESSAGE_MAX);
+        if (this.finishing || this.isCoolingDown()) {
+            this.pendingPreview = preview;
+            if (!this.finishing)
+                this.scheduleCooldownFlush();
+            return;
+        }
+        if (this.sentPreview !== preview) {
+            this.pendingPreview = undefined;
+            try {
+                await this.upstream.editMessageText(this.target.conversationId, this.messageId, preview);
+                this.sentPreview = preview;
+            }
+            catch (error) {
+                if (!isRateLimitError(error))
+                    throw error;
+                if (this.pendingPreview === undefined)
+                    this.pendingPreview = preview;
+                this.startCooldown(error);
+            }
+        }
+    }
+    /**
+     * Send the final message. Plain mode: first chunk edits the existing message,
+     * overflow chunks are sent as new messages. Rich mode (richFinal + rich
+     * formatting): upgrade the same message to a Rich Message; fall back to plain
+     * once on a format error.
+     */
+    async sendFinal() {
+        const mode = this.options.formatting?.mode ?? 'auto';
+        if (this.options.richFinal && mode !== 'plain') {
+            await this.sendRichFinal();
+            return;
+        }
+        const chunks = splitByGraphemes(this.text, REGULAR_MESSAGE_MAX);
+        if (this.messageId && this.sentPreview !== chunks[0]) {
+            await this.editFinalText(chunks[0] ?? '');
+            this.sentPreview = chunks[0];
+        }
+        else if (!this.messageId) {
+            const sent = await this.upstream.sendMessage(this.target.conversationId, chunks[0] ?? '', targetOptions(this.target));
+            this.messageId = sent.messageId;
+        }
+        for (const chunk of chunks.slice(1)) {
+            await this.upstream.sendMessage(this.target.conversationId, chunk, {
+                messageThreadId: this.target.threadId,
+            });
+        }
+    }
+    /** Upgrade the in-place message to a Rich Message with plain-once fallback. */
+    async sendRichFinal() {
+        const source = this.text;
+        if (!source)
+            return;
+        await sendWithFallback(source, { mode: 'rich-markdown' }, async (plan) => {
+            if (plan.kind === 'rich') {
+                // Edit the same message into the first rich segment; overflow as new
+                // rich messages.
+                if (this.messageId) {
+                    await this.editFinalRich({ markdown: plan.texts[0] ?? '' });
+                }
+                for (const text of plan.texts.slice(1)) {
+                    await this.upstream.sendRichMessage(this.target.conversationId, { markdown: text });
+                }
+                return;
+            }
+            // Plain fallback on the same message + new overflow messages.
+            if (this.messageId) {
+                await this.editFinalText(plan.chunks[0] ?? '');
+            }
+            else {
+                const sent = await this.upstream.sendMessage(this.target.conversationId, plan.chunks[0] ?? '', targetOptions(this.target));
+                this.messageId = sent.messageId;
+            }
+            for (const chunk of plan.chunks.slice(1)) {
+                await this.upstream.sendMessage(this.target.conversationId, chunk, {
+                    messageThreadId: this.target.threadId,
+                });
+            }
+        });
+    }
+    /** Retry only the in-place final edit after a Telegram-requested cooldown. */
+    async editFinalText(text) {
+        while (true) {
+            await this.waitForCooldown();
+            try {
+                await this.upstream.editMessageText(this.target.conversationId, this.messageId, text);
+                return;
+            }
+            catch (error) {
+                if (!isRateLimitError(error))
+                    throw error;
+                this.startCooldown(error);
+            }
+        }
+    }
+    /** The rich final path uses Telegram's edit endpoint too, so it shares 429 recovery. */
+    async editFinalRich(message) {
+        while (true) {
+            await this.waitForCooldown();
+            try {
+                await this.upstream.editMessageRich(this.target.conversationId, this.messageId, message);
+                return;
+            }
+            catch (error) {
+                if (!isRateLimitError(error))
+                    throw error;
+                this.startCooldown(error);
+            }
+        }
+    }
+    isCoolingDown() {
+        return Date.now() < this.cooldownUntil;
+    }
+    /** Honor the server's retry hint, extending (never shortening) cooldown. */
+    startCooldown(error) {
+        const retryAfter = error.parameters?.retryAfter;
+        const delayMs = Number.isFinite(retryAfter)
+            ? Math.max(1, Math.ceil(retryAfter)) * 1000
+            : 1000;
+        this.cooldownUntil = Math.max(this.cooldownUntil, Date.now() + delayMs);
+        this.scheduleCooldownFlush();
+    }
+    /** One timer, one latest-value flush. It never replays a sequence of edits. */
+    scheduleCooldownFlush() {
+        if (this.finishing || this.finalized || this.cooldownTimer || !this.pendingPreview)
+            return;
+        this.cooldownTimer = setTimeout(() => {
+            this.cooldownTimer = undefined;
+            void this.enqueue(() => this.sync(false)).catch(() => { });
+        }, Math.max(1, this.cooldownUntil - Date.now()));
+    }
+    clearCooldownTimer() {
+        if (this.cooldownTimer)
+            clearTimeout(this.cooldownTimer);
+        this.cooldownTimer = undefined;
+    }
+    async waitForCooldown() {
+        while (this.isCoolingDown()) {
+            await new Promise((resolve) => {
+                setTimeout(resolve, Math.max(1, this.cooldownUntil - Date.now()));
+            });
+        }
+    }
+    enqueue(task) {
+        const next = this.queue.then(task, task);
+        this.queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function isRateLimitError(error) {
+    return error instanceof TelegramApiError && error.kind === 'rate-limit';
+}
+function targetOptions(target) {
+    return {
+        replyToMessageId: target.replyToMessageId,
+        messageThreadId: target.threadId,
+    };
+}
+/**
+ * Build a rolling preview for an in-progress stream: show the whole text up to
+ * `limit`, otherwise `…` + the newest `limit - 1` graphemes. This keeps the
+ * preview visibly changing once the model exceeds the single-message limit
+ * (plan §6.3), fixing the frozen `chunks[0]` behaviour.
+ */
+export function makePreview(text, limit) {
+    return makeRollingPreview(text, limit);
+}
+/** Internal: rolling head/tail preview implementation. */
+function makeRollingPreview(text, limit) {
+    if (visibleLength(text) <= limit)
+        return text;
+    // Show `…` + the newest (limit-1) graphemes so the user sees output continue.
+    return `…${tailGraphemes(text, limit - 1)}`;
+}
+//# sourceMappingURL=streaming-reply.js.map