@fastagent-sh/fastagent 0.12.0

package/dist/channels/telegram/parse.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Telegram protocol parsing — PURE: message field extraction, the prompt envelope, and the summon/route
+ * policy. The defining invariant is purity: no state, no IO, no Bot API calls — plain data-in → data-out.
+ * In telegram.ts's pipeline (verify → decide via `route` → run the turn → stream reply), this is the
+ * "decide" and prompt-building half; telegram.ts wires it in and owns the stateful lifecycle. Kept
+ * separate so this layer tests as plain functions and reads without the factory's noise.
+ */
+/** A Telegram message (the common subset; `[k]` keeps the rest reachable without a types dependency). */
+export interface TelegramMessage {
+    message_id: number;
+    text?: string;
+    /** Entities Telegram's server parsed out of `text` (mentions, commands, URLs, code…). Offsets are
+     *  UTF-16 code units — exactly JS string indexing, so `text.slice(offset, offset + length)` is the
+     *  entity's text verbatim. */
+    entities?: {
+        type: string;
+        offset: number;
+        length: number;
+        [k: string]: unknown;
+    }[];
+    /** Caption on a media message (photo/document/…) — often the user's instruction for the attachment. */
+    caption?: string;
+    /** Entities of `caption`, same shape as {@link TelegramMessage.entities}. */
+    caption_entities?: {
+        type: string;
+        offset: number;
+        length: number;
+        [k: string]: unknown;
+    }[];
+    /** Photo sizes, smallest → largest. The channel sends the largest to the model as a vision image. */
+    photo?: {
+        file_id: string;
+        file_unique_id: string;
+        width: number;
+        height: number;
+        file_size?: number;
+    }[];
+    /** Structured payloads worth rendering into the prompt as text (no new modality needed). */
+    location?: {
+        latitude: number;
+        longitude: number;
+        [k: string]: unknown;
+    };
+    contact?: {
+        phone_number?: string;
+        first_name: string;
+        last_name?: string;
+        [k: string]: unknown;
+    };
+    poll?: {
+        question: string;
+        options?: {
+            text: string;
+        }[];
+        [k: string]: unknown;
+    };
+    /** Files — the channel downloads document/voice/video/audio on a routed message to disk. */
+    document?: {
+        file_id: string;
+        file_name?: string;
+        mime_type?: string;
+        file_size?: number;
+        [k: string]: unknown;
+    };
+    voice?: {
+        file_id: string;
+        [k: string]: unknown;
+    };
+    video?: {
+        file_id: string;
+        [k: string]: unknown;
+    };
+    audio?: {
+        file_id: string;
+        [k: string]: unknown;
+    };
+    /** Present in Threaded Mode (topics in private chats); reply with the same id to stay in-thread. */
+    message_thread_id?: number;
+    /** The message this one replies to, if any — inject its text/media so the agent has the referent. */
+    reply_to_message?: TelegramMessage;
+    chat: {
+        id: number;
+        type: string;
+        [k: string]: unknown;
+    };
+    from?: {
+        id: number;
+        username?: string;
+        is_bot?: boolean;
+        first_name?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** A Telegram update (the common subset the channel ACTS on — an update kind not listed here is ACKed
+ *  and dropped before `route` sees it, so listing it would be a false promise; `[k]` keeps the raw
+ *  payload reachable). Narrow for what you route on, e.g. `update.message?.text`. */
+export interface TelegramUpdate {
+    update_id: number;
+    message?: TelegramMessage;
+    channel_post?: TelegramMessage;
+    [k: string]: unknown;
+}
+/** What `route` returns: act with these (every field optional — omitted ones default from the message), or null to ignore. */
+export interface TelegramRoute {
+    /** Conversation identity (default: `chat` or `chat:thread`). */
+    session?: string;
+    /** Reply target chat (default: the message's chat). */
+    chatId?: number | string;
+    /** Reply thread (default: the message's thread). */
+    threadId?: number;
+    /** Base prompt (default: {@link telegramEnvelope}); the channel still appends attachments + the HTML hint. */
+    text?: string;
+}
+/** The actionable message in an update (a fresh message or channel post). Edits (`edited_message` /
+ *  `edited_channel_post`) are deliberately NOT actionable: answering them re-answers every typo fix (a
+ *  duplicate reply per edit), so an edited message changes nothing — the standard bot behavior. The
+ *  trade-off: editing a mention INTO an old message does not summon either; send a new message. */
+export declare function pickMessage(update: TelegramUpdate): TelegramMessage | undefined;
+/** file_ids to send the model as vision images: this message's largest photo + a replied-to photo. */
+export declare function extractImages(m: TelegramMessage): string[];
+/** The message's OWN photo (largest size), without the replied-to message's — the buffer path uses
+ *  this: each message is its own entry there, so counting the replied-to attachment again would
+ *  duplicate it and squeeze the attachment cap (the reply relation is expressed by `replyTo` instead). */
+export declare function ownImages(m: TelegramMessage): string[];
+/** file_ids to download to disk for the agent's tools: this message's files + a replied-to message's
+ *  (so "summarize this file" works when the user replies to a document with the mention). */
+export declare function extractFiles(m: TelegramMessage): string[];
+/** The message's OWN files, without the replied-to message's (see {@link ownImages} for why). */
+export declare function ownFiles(m: TelegramMessage): string[];
+/** A stable sender label for attribution. In a shared (multi-user) session the model must tell who is
+ *  who across turns; a username-less user still gets a name + id rather than vanishing. */
+export declare function fromLabel(from: TelegramMessage["from"]): string | undefined;
+/** A one-line description of a message's attachment, so the envelope names what was sent even before
+ *  the agent opens it (and so a media-only message isn't blank). */
+export declare function attachmentSummary(m: TelegramMessage): string | undefined;
+/** A one-line, length-capped rendering of a message's content for the context buffer. */
+export declare function messageText(m: TelegramMessage): string;
+/**
+ * The default base prompt: a context envelope (chat/thread/sender + a group note + reply) then the
+ * user's text/caption and a compact rendering of structured payloads (location/contact/poll). The
+ * sender is named on every message and a group chat is flagged — in a shared multi-user session that is
+ * how the model tells participants apart and knows it is not a 1:1. The reply
+ * block carries the replied-to sender, message id, and text/caption or an attachment summary (and the
+ * channel downloads a replied-to file/photo too). Exported so a custom `route` can reuse it, e.g.
+ * `text: `${telegramEnvelope(m)}\n\n[extra]``. The channel still appends downloaded attachments.
+ */
+export declare function telegramEnvelope(m: TelegramMessage): string;
+/**
+ * The default routing policy (used when `route` is omitted; exported so a custom route can reuse it):
+ * answer private chats always; a group only on a reply to THIS bot (by `botId`) or a `mention` entity
+ * naming it (when `botUsername` is supplied — telegramChannel parses the id from the token and resolves
+ * the username via getMe). A bare or directed slash command does NOT summon in a group (that was noisy;
+ * a bot author who wants commands adds a custom route). Returns `{}` (act; the channel fills
+ * session/target/prompt from the message) or `null` (ignore).
+ */
+export declare function defaultTelegramRoute(update: TelegramUpdate, options?: {
+    botUsername?: string;
+    botId?: number;
+}): TelegramRoute | null;

package/dist/channels/telegram/parse.js

@@ -0,0 +1,153 @@
+/**
+ * Telegram protocol parsing — PURE: message field extraction, the prompt envelope, and the summon/route
+ * policy. The defining invariant is purity: no state, no IO, no Bot API calls — plain data-in → data-out.
+ * In telegram.ts's pipeline (verify → decide via `route` → run the turn → stream reply), this is the
+ * "decide" and prompt-building half; telegram.ts wires it in and owns the stateful lifecycle. Kept
+ * separate so this layer tests as plain functions and reads without the factory's noise.
+ */
+/** The actionable message in an update (a fresh message or channel post). Edits (`edited_message` /
+ *  `edited_channel_post`) are deliberately NOT actionable: answering them re-answers every typo fix (a
+ *  duplicate reply per edit), so an edited message changes nothing — the standard bot behavior. The
+ *  trade-off: editing a mention INTO an old message does not summon either; send a new message. */
+export function pickMessage(update) {
+    return update.message ?? update.channel_post;
+}
+/** file_ids to send the model as vision images: this message's largest photo + a replied-to photo. */
+export function extractImages(m) {
+    return [...ownImages(m), ...(m.reply_to_message ? ownImages(m.reply_to_message) : [])];
+}
+/** The message's OWN photo (largest size), without the replied-to message's — the buffer path uses
+ *  this: each message is its own entry there, so counting the replied-to attachment again would
+ *  duplicate it and squeeze the attachment cap (the reply relation is expressed by `replyTo` instead). */
+export function ownImages(m) {
+    return [m.photo?.at(-1)?.file_id].filter((id) => Boolean(id));
+}
+/** file_ids to download to disk for the agent's tools: this message's files + a replied-to message's
+ *  (so "summarize this file" works when the user replies to a document with the mention). */
+export function extractFiles(m) {
+    return [...ownFiles(m), ...(m.reply_to_message ? ownFiles(m.reply_to_message) : [])];
+}
+/** The message's OWN files, without the replied-to message's (see {@link ownImages} for why). */
+export function ownFiles(m) {
+    return [m.document?.file_id, m.voice?.file_id, m.video?.file_id, m.audio?.file_id].filter((id) => Boolean(id));
+}
+/** A stable sender label for attribution. In a shared (multi-user) session the model must tell who is
+ *  who across turns; a username-less user still gets a name + id rather than vanishing. */
+export function fromLabel(from) {
+    if (!from)
+        return undefined;
+    return from.username ? `@${from.username}` : `${from.first_name ?? "user"} (id ${from.id})`;
+}
+/** A one-line description of a message's attachment, so the envelope names what was sent even before
+ *  the agent opens it (and so a media-only message isn't blank). */
+export function attachmentSummary(m) {
+    if (m.photo?.length)
+        return "[photo]";
+    if (m.document) {
+        return `[document: ${m.document.file_name ?? "file"}${m.document.mime_type ? ` (${m.document.mime_type})` : ""}]`;
+    }
+    if (m.voice)
+        return "[voice message]";
+    if (m.video)
+        return "[video]";
+    if (m.audio)
+        return "[audio]";
+    return undefined;
+}
+/** A message's readable body: its text, else its caption, else a one-line attachment summary; undefined
+ *  for an empty/service message. The single source for "what did this message say" — envelope, reply-
+ *  quote, and the context-buffer line all read through it so their fallbacks cannot drift apart. */
+function bodyOf(m) {
+    return m.text ?? m.caption ?? attachmentSummary(m);
+}
+/** A one-line, length-capped rendering of a message's content for the context buffer. */
+export function messageText(m) {
+    return (bodyOf(m) ?? "").replace(/\s+/g, " ").trim().slice(0, 280);
+}
+/**
+ * The default base prompt: a context envelope (chat/thread/sender + a group note + reply) then the
+ * user's text/caption and a compact rendering of structured payloads (location/contact/poll). The
+ * sender is named on every message and a group chat is flagged — in a shared multi-user session that is
+ * how the model tells participants apart and knows it is not a 1:1. The reply
+ * block carries the replied-to sender, message id, and text/caption or an attachment summary (and the
+ * channel downloads a replied-to file/photo too). Exported so a custom `route` can reuse it, e.g.
+ * `text: `${telegramEnvelope(m)}\n\n[extra]``. The channel still appends downloaded attachments.
+ */
+export function telegramEnvelope(m) {
+    const r = m.reply_to_message;
+    const meta = [
+        `chat ${m.chat.id} (${m.chat.type})`,
+        m.message_thread_id ? `thread ${m.message_thread_id}` : undefined,
+        fromLabel(m.from) ? `from ${fromLabel(m.from)}` : undefined,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    // In a shared group session the model sees turns from different people (each `from`-tagged); tell it
+    // so it addresses participants by name and does not assume one continuous interlocutor. A 1:1 DM is
+    // self-evident, so no note there.
+    const isGroup = m.chat.type === "group" || m.chat.type === "supergroup";
+    const scope = isGroup ? "\n[group chat — multiple people; each message is prefixed with its sender]" : "";
+    const replyTo = r
+        ? `\n[in reply to ${fromLabel(r.from) ?? `msg ${r.message_id}`} (msg ${r.message_id}): ${(bodyOf(r) ?? "(empty)").slice(0, 280)}]`
+        : "";
+    const parts = [bodyOf(m) ?? ""];
+    if (m.location)
+        parts.push(`[location: ${m.location.latitude},${m.location.longitude}]`);
+    if (m.contact)
+        parts.push(`[contact: ${m.contact.first_name} ${m.contact.phone_number ?? ""}]`);
+    if (m.poll)
+        parts.push(`[poll: ${m.poll.question} — ${(m.poll.options ?? []).map((o) => o.text).join(" / ")}]`);
+    return `[telegram: ${meta}]${scope}${replyTo}\n${parts.filter(Boolean).join("\n")}`;
+}
+/** Normalize a configured bot username: drop a leading `@`, trim, lowercase (usernames are case-
+ *  insensitive). Undefined when unknown. */
+function botName(botUsername) {
+    const s = botUsername?.replace(/^@/, "").trim().toLowerCase();
+    return s || undefined;
+}
+/**
+ * Whether the message @mentions the bot — read from the `mention` ENTITIES Telegram's server already
+ * parsed, not a regex over the raw text. The entity type excludes by construction what a text scan
+ * false-matches: `@bot` inside a code block or a URL is not a `mention` entity, a glued `/cmd@bot` is a
+ * `bot_command` — and slicing the exact offset/length range makes `@fast` vs `@fastagent` confusion
+ * impossible. (Offsets are UTF-16 code units = native JS string indexing.) No text fallback: mention
+ * entities are produced server-side, so their absence means there is no mention.
+ */
+function mentionsBot(m, botUsername) {
+    const name = botName(botUsername);
+    if (!name)
+        return false;
+    const text = m.text ?? m.caption ?? "";
+    const entities = (m.text !== undefined ? m.entities : m.caption_entities) ?? [];
+    return entities.some((e) => e.type === "mention" && text.slice(e.offset, e.offset + e.length).toLowerCase() === `@${name}`);
+}
+/** Whether the message replies to THIS bot — not just any bot: in a multi-bot group, replying to
+ *  another bot must not summon ours. Identity is the bot's numeric id (stable; a username is a mutable
+ *  handle) — telegramChannel parses it synchronously from the token, so there is no resolution race.
+ *  Without an id, fall back to username; with NEITHER, fail closed (false): answering "is this a reply
+ *  to me?" with "I don't know who I am, so yes" would mis-summon in every multi-bot group — a caller
+ *  reusing the route bare must supply an identity to get reply summon. */
+function repliesToBot(m, options) {
+    const r = m.reply_to_message?.from;
+    if (r?.is_bot !== true)
+        return false;
+    if (options?.botId !== undefined)
+        return r.id === options.botId;
+    const name = botName(options?.botUsername);
+    return name !== undefined && r.username?.toLowerCase() === name;
+}
+/**
+ * The default routing policy (used when `route` is omitted; exported so a custom route can reuse it):
+ * answer private chats always; a group only on a reply to THIS bot (by `botId`) or a `mention` entity
+ * naming it (when `botUsername` is supplied — telegramChannel parses the id from the token and resolves
+ * the username via getMe). A bare or directed slash command does NOT summon in a group (that was noisy;
+ * a bot author who wants commands adds a custom route). Returns `{}` (act; the channel fills
+ * session/target/prompt from the message) or `null` (ignore).
+ */
+export function defaultTelegramRoute(update, options) {
+    const m = pickMessage(update);
+    if (!m)
+        return null;
+    const summoned = m.chat.type === "private" || repliesToBot(m, options) || mentionsBot(m, options?.botUsername);
+    return summoned ? {} : null;
+}

package/dist/channels/telegram/preview.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Live-preview rendering: consume one turn's event stream into a Telegram chat. A single real message
+ * is sent once ("💭 Thinking…", or an already-sent "⏳ queued" notice is taken over), then
+ * editMessageText'd in place with the latest tool calls + partial text (PLAIN — a partial answer may
+ * carry unbalanced HTML); on completion the same message is edited into the final answer as HTML. One
+ * message, works in groups and private (unlike sendMessageDraft, which is private/forum-topic only).
+ */
+import type { AgentEvent } from "../../agent.ts";
+import { type Target } from "./telegram-api.ts";
+/** A terminal failure, as the channel hands it to `onError`. */
+export interface TelegramFailure {
+    details: string;
+    retryable: boolean;
+}
+/** The customer-facing default: neutral, no leaked internals; differentiate only on whether to retry. */
+export declare function defaultErrorMessage(failed: TelegramFailure): string;
+/**
+ * Consume one turn's event stream into a Telegram chat, live (see the module header for the preview
+ * model). Preview edits are best-effort (logged once if they fail); the final write is authoritative
+ * and surfaces a real failure (bad token, etc.).
+ */
+export declare function streamReply(events: AsyncIterable<AgentEvent>, api: string, botToken: string, target: Target, formatError: (failed: TelegramFailure) => string | undefined, previewId?: number): Promise<void>;

package/dist/channels/telegram/preview.js

@@ -0,0 +1,266 @@
+import { log } from "../../log.js";
+import { TELEGRAM_MAX_TEXT, callApi, editMessageText, sendMessage } from "./telegram-api.js";
+/** The customer-facing default: neutral, no leaked internals; differentiate only on whether to retry. */
+export function defaultErrorMessage(failed) {
+    return failed.retryable ? "⚠️ Temporary problem — please try again." : "⚠️ Sorry, something went wrong.";
+}
+/** How often (ms) to edit the live-preview message; tool events still flush on the next loop. Edits to
+ *  one message are rate-limited tighter than sends, so pace them ~1.5s (vs every token). Doubles as the
+ *  answer-preview aging window (see answerView): partial answer text stays hidden until it has existed
+ *  this long — one knob, same order of magnitude. */
+const EDIT_THROTTLE_MS = 1500;
+/** Max length of a tool's arg preview in the live view. */
+const TOOL_ARG_MAX = 48;
+/** How much of the (growing) reasoning to peek at in the live view — the most recent tail. */
+const THINKING_PREVIEW = 280;
+/** One-line, truncated: collapse whitespace so a multi-line command/arg stays on one line. */
+function clip(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    return one.length > TOOL_ARG_MAX ? `${one.slice(0, TOOL_ARG_MAX - 1)}…` : one;
+}
+/**
+ * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
+ * rather than just `🔧 read`. Generic (the channel knows no tool schemas): show the salient value — the
+ * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
+ */
+function summarizeArgs(args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return clip(String(args));
+    const values = Object.values(args);
+    const primary = values.find((v) => typeof v === "string" || typeof v === "number");
+    if (primary !== undefined)
+        return clip(String(primary));
+    return values.length > 0 ? clip(JSON.stringify(args)) : "";
+}
+/**
+ * The terminal-write POLICY: resolve the single preview message into `text`. streamReply owns the
+ * preview lifecycle, so this composition of transport primitives lives here, not in telegram-api. One
+ * message → edit the preview in place; if the edit fails (preview gone, or a persistent 429/5xx) fall
+ * back to deleting the placeholder and sending fresh, so no "Thinking…" is left pinned above the answer.
+ * Many messages → delete the preview and send the whole answer as consecutive fresh messages (editing
+ * would pin the first chunk where an active group has scrolled past). No preview → fresh send. EMPTY text
+ * = "say nothing" → just delete the preview.
+ */
+async function finalize(api, botToken, target, messageId, text, opts = {}) {
+    const html = opts.html ?? true;
+    if (text.trim() === "") {
+        if (messageId !== undefined)
+            await callApi(api, botToken, "deleteMessage", { chat_id: target.chatId, message_id: messageId });
+        return;
+    }
+    if (messageId !== undefined) {
+        // "Fits in one message" is a plain length check against Telegram's limit — not chunkText, whose html
+        // mode exists for SPLIT chunks and is irrelevant to an un-split text.
+        if (text.length <= TELEGRAM_MAX_TEXT) {
+            try {
+                await editMessageText(api, botToken, target, messageId, text, { html });
+                return;
+            }
+            catch {
+                // Edit failed — the preview may be gone, or still there (429 retries exhausted / 5xx). Fall through
+                // to delete + fresh send below so a still-present "Thinking…" is not left pinned above the answer.
+            }
+        }
+        // Too long for one message, OR a failed single-message edit: remove the placeholder best-effort (a lingering one above
+        // the answer is worse than the extra call), then send the whole reply as fresh, consecutive messages.
+        await callApi(api, botToken, "deleteMessage", { chat_id: target.chatId, message_id: messageId }).catch(() => { });
+    }
+    await sendMessage(api, botToken, target, text, { html });
+}
+/**
+ * Consume one turn's event stream into a Telegram chat, live (see the module header for the preview
+ * model). Preview edits are best-effort (logged once if they fail); the final write is authoritative
+ * and surfaces a real failure (bad token, etc.).
+ */
+export async function streamReply(events, api, botToken, target, formatError, previewId) {
+    const tools = [];
+    const toolIndexById = new Map();
+    let thinking = "";
+    let answer = "";
+    let answerPreviewSince;
+    const mark = { running: "…", ok: "✓", error: "✗" };
+    const toolView = () => tools.map((t) => `🔧 ${t.label} ${mark[t.status]}`).join("\n");
+    // Reasoning is process, not the answer: shown (capped to its tail) in the live preview only, never
+    // in the persisted final message (which is `answer` alone).
+    const thinkingView = () => {
+        const t = thinking.replace(/\s+/g, " ").trim();
+        if (t === "")
+            return "";
+        return `💭 ${t.length > THINKING_PREVIEW ? `…${t.slice(t.length - THINKING_PREVIEW + 1)}` : t}`;
+    };
+    // The answer is hidden until its first delta has aged one EDIT_THROTTLE_MS: the pump's leading-edge
+    // flush would otherwise turn the very first content delta (often a lone character or unbalanced markup)
+    // into its own Telegram edit — the short-reply flicker (placeholder → "O" → "OK."). Aging is anchored
+    // at delta ARRIVAL (set in the event loop, not here) so an in-flight edit can't skew the clock, and
+    // there is deliberately NO timer at the boundary: a young answer surfaces on the next content-driven
+    // preview pass, so a turn completing within the window sends the final answer edit only.
+    const answerView = () => {
+        if (answer.trim() === "" || answerPreviewSince === undefined)
+            return "";
+        return Date.now() - answerPreviewSince >= EDIT_THROTTLE_MS ? answer : "";
+    };
+    const view = () => {
+        const v = [thinkingView(), toolView(), answerView()]
+            .filter((s) => s.trim() !== "")
+            .join("\n\n")
+            .trim();
+        // Before any reasoning/tool/text arrives, show an explicit placeholder rather than an empty edit.
+        return v === "" ? "💭 Thinking…" : v;
+    };
+    // The live preview is ONE real message: sent once (capturing its id + threading under the asker),
+    // then edited in place. messageId/lastSent are shared with the final write on completion.
+    // `previewId`: an already-sent message to take over as the preview (the "⏳ queued" notice) — the
+    // pump edits it in place, so the queue notice morphs into the live view instead of leaving an orphan.
+    let messageId = previewId;
+    let previewSent = messageId !== undefined; // a placeholder send was attempted — guards against re-sending when no id came back
+    let finalized = false; // a terminal write (completed/failed) ran — the finally skips its orphan cleanup
+    let lastSent = "";
+    const flushPreview = async () => {
+        const text = view();
+        if (text === lastSent)
+            return; // skip an unchanged edit (Telegram rejects "message is not modified")
+        lastSent = text;
+        if (messageId !== undefined) {
+            await editMessageText(api, botToken, target, messageId, text); // plain — a partial answer may carry unbalanced HTML
+            return;
+        }
+        // No preview message yet. Send the placeholder ONCE; never re-send (that would spam a new message per
+        // frame). If Telegram returns ok WITHOUT a message_id (proxy / odd API base / unparseable body) we
+        // cannot edit — fail visibly and stop previewing (the final write still lands via finalize).
+        if (previewSent)
+            return;
+        previewSent = true;
+        messageId = await sendMessage(api, botToken, target, text, { html: false });
+        if (messageId === undefined)
+            throw new Error("telegram sendMessage returned ok without a message_id — live preview disabled for this turn");
+    };
+    // ── Live-preview pump: a SINGLE serialized writer. ──────────────────────────────────────────
+    // Events mutate state (thinking / tools / answer) and mark the preview dirty; the pump edits the
+    // message to the LATEST view() with at most ONE edit in flight, paced by a throttle. One-in-flight is
+    // the whole point: concurrent edits can reach Telegram out of order — an older frame landing over a
+    // newer one is the "shows 3-4 steps, blanks, re-fills" flicker. Serializing keeps frames monotonic.
+    // (No keepalive: a real message does not expire, unlike a Bot API `sendMessageDraft` (30s window).)
+    let dirty = false;
+    let pumping = false;
+    let stopped = false;
+    let previewErrLogged = false;
+    let pumpDone;
+    let wakeThrottle; // set while the pump is mid-throttle; finish() cuts it short
+    const runPump = async () => {
+        pumping = true;
+        try {
+            while (dirty && !stopped) {
+                dirty = false;
+                try {
+                    await flushPreview();
+                }
+                catch (e) {
+                    // Best-effort preview (the final write is authoritative), but a failing edit must be visible —
+                    // log once per turn so a never-rendering preview is diagnosable, not silent.
+                    if (!previewErrLogged) {
+                        previewErrLogged = true;
+                        log.warn(`[telegram] live preview failed (final reply still sends): ${String(e)}`);
+                    }
+                }
+                if (dirty && !stopped) {
+                    // Pace + coalesce a burst into one edit. Interruptible: finish() cuts this short so the final
+                    // write is not delayed by up to EDIT_THROTTLE_MS after the turn completes.
+                    await new Promise((resolve) => {
+                        const t = setTimeout(resolve, EDIT_THROTTLE_MS);
+                        wakeThrottle = () => {
+                            clearTimeout(t);
+                            resolve();
+                        };
+                    });
+                    wakeThrottle = undefined;
+                }
+            }
+        }
+        finally {
+            pumping = false;
+        }
+    };
+    // Mark the preview dirty and ensure the single writer is running (an edit already in flight picks up
+    // the new state on its next loop). Synchronous — callers never await a network write.
+    const touch = () => {
+        dirty = true;
+        if (!pumping)
+            pumpDone = runPump();
+    };
+    touch(); // send the "💭 Thinking…" placeholder immediately
+    // Stop the pump and await any in-flight edit, so the final write below is strictly the LAST one to the
+    // preview message (no stale frame landing after the answer).
+    const finish = async () => {
+        stopped = true;
+        wakeThrottle?.(); // cut an in-flight throttle so the final write is not delayed up to EDIT_THROTTLE_MS
+        await pumpDone?.catch(() => { });
+    };
+    try {
+        for await (const e of events) {
+            if (e.type === "text") {
+                answer += e.delta;
+                if (answerPreviewSince === undefined && answer.trim() !== "")
+                    answerPreviewSince = Date.now();
+                touch();
+            }
+            else if (e.type === "thinking") {
+                thinking += e.delta;
+                touch();
+            }
+            else if (e.type === "tool_started") {
+                const arg = summarizeArgs(e.args);
+                toolIndexById.set(e.id, tools.length);
+                tools.push({ label: arg ? `${e.name} ${arg}` : e.name, status: "running" });
+                touch();
+            }
+            else if (e.type === "tool_ended") {
+                const i = toolIndexById.get(e.id);
+                const t = i === undefined ? undefined : tools[i];
+                if (t)
+                    t.status = e.isError ? "error" : "ok";
+                touch();
+            }
+            else if (e.type === "completed") {
+                await finish();
+                // Edit the preview into the final answer (HTML, plain fallback); the persisted message is the
+                // answer alone — the process (thinking/tools) was preview-only. Mark finalized BEFORE delivering:
+                // the terminal was reached, so a delivery failure here is a plain failure, not an "abnormal exit"
+                // (which would wrongly fire the finally's neutral-notice fallback = double delivery + wrong text).
+                finalized = true;
+                await finalize(api, botToken, target, messageId, answer.trim() !== "" ? answer : "(no reply)");
+                return;
+            }
+            else if (e.type === "failed") {
+                await finish();
+                // Two audiences: the chat (customer-facing — formatError, neutral by default) and the operator
+                // log (dev-facing — the full details, via the throw below + the handler's catch). Same terminal
+                // write as completed: edit → fresh-send if the preview is gone; an empty notice deletes the
+                // placeholder (suppress = no residue). HTML like the answer — symmetric, and finalize already
+                // falls back to plain if a custom onError returns markup Telegram rejects. Best-effort — we throw
+                // below regardless.
+                finalized = true;
+                {
+                    const msg = formatError({ details: e.details, retryable: e.retryable }) ?? "";
+                    await finalize(api, botToken, target, messageId, msg).catch(() => { });
+                }
+                throw new Error(`agent failed: ${e.details} (retryable=${e.retryable})`);
+            }
+        }
+        throw new Error("stream ended without a terminal event"); // violates SPEC MUST 1
+    }
+    finally {
+        await finish();
+        // Abnormal exit (stream ended without a terminal, the generator threw, or the consumer abandoned): no
+        // terminal write ran. Show the SAME neutral notice a `failed` event would — the preview may show real
+        // partial work, so don't delete it silently, and don't leave the user in silence. A suppressing
+        // onError still collapses to a delete (finalize on empty text).
+        if (!finalized) {
+            // retryable:false — an abnormal end (no terminal / a throw) is of UNKNOWN retryability, so use the
+            // neutral "something went wrong" default rather than promising "try again" that may not help.
+            const notice = formatError({ details: "the turn ended without completing", retryable: false }) ?? "";
+            // finalize handles messageId===undefined (no preview reached) with a fresh send — so the user is
+            // told even when the turn died before any message.
+            await finalize(api, botToken, target, messageId, notice).catch(() => { });
+        }
+    }
+}

package/dist/channels/telegram/register-webhook.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Register `<baseUrl>/telegram` as the bot's webhook (with the .env secret). Waits for the server to be
+ * REACHABLE first — polling `<baseUrl>/health` — because Telegram VERIFIES the URL when you set it, and a
+ * fresh deploy's container (healthcheck + routing) or a fresh tunnel's DNS is not routable for some
+ * seconds after the deploy/tunnel command returns. Tracking real readiness (not a fixed timer) is what
+ * fixes the race that made the first real deploy need a manual `setWebhook`. Missing tokens print the
+ * manual instruction instead of failing. `opts` (timeouts) exist for tests; production uses the defaults.
+ */
+export declare function registerTelegramWebhook(baseUrl: string, opts?: {
+    readyTimeoutMs?: number;
+    readyIntervalMs?: number;
+    retryMs?: number;
+}): Promise<void>;