@fastagent-sh/fastagent 0.21.0 → 0.22.0

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

@@ -2,9 +2,7 @@
 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 Telegram's server parsed out of `text` (mentions, commands, URLs, code…). */
     entities?: {
         type: string;
         offset: number;
@@ -20,7 +18,7 @@ export interface TelegramMessage {
         length: number;
         [k: string]: unknown;
     }[];
-    /** Photo sizes, smallest → largest. The channel sends the largest to the model as a vision image. */
+    /** Photo sizes, smallest → largest. */
     photo?: {
         file_id: string;
         file_unique_id: string;
@@ -85,16 +83,20 @@ export interface TelegramMessage {
     };
     [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`. */
+/**
+ * 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).
+ */
 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. */
+/**
+ * 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;
@@ -105,68 +107,39 @@ export interface TelegramRoute {
     /** 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. */
+/** The actionable message in an update (a fresh message or channel post). */
 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). */
+/** The message's OWN photo (largest size), without the replied-to message's. */
 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). */
+/** file_ids to download to disk: this message's files plus a replied-to message's ("summarize this file"). */
 export declare function extractFiles(m: TelegramMessage): string[];
-/** The message's OWN files, without the replied-to message's (see {@link ownImages} for why). */
+/** The message's OWN files, without the replied-to message's. */
 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. */
+/** A stable sender label for attribution. */
 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). */
+/**
+ * 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.
+ * 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).
  */
 export declare function telegramEnvelope(m: TelegramMessage): string;
 /**
- * Whether the update is a `/stop` ADDRESSED TO THIS BOT — the one question the channel asks about a
- * stop, because an unaddressed one is not a command it may act on. Four ways to address it, all
- * equivalent: a bare `/stop` in a private chat (no one else is there), `/stop@thisbot`, an `@thisbot`
- * mention beside the command, and a bare `/stop` replying to one of this bot's messages.
- *
- * A BARE `/stop` in a group is deliberately NOT one of them. Telegram hands it to every bot in the
- * chat — and only promises to deliver it at all when this bot spoke last — so it names no one: acting
- * on it lets a bystander's ask for a different bot abort this bot's run, and answering it lets that
- * bystander make this bot talk. It stays ordinary discussion, which is what the group sees anyway.
- *
- * Takes the UPDATE, like `route` itself, so a custom route can ask it directly — that route is the
- * gate a stop must pass, and one that refuses this update silences the command.
+ * Whether the update is a `/stop` ADDRESSED TO THIS BOT — the one question the channel asks about a stop, because an
+ * unaddressed one is not a command it may act on.
  */
 export declare function telegramStop(update: TelegramUpdate, options?: {
     botUsername?: string;
     botId?: number;
 }): boolean;
-/**
- * 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) — except a `/stop` ADDRESSED to this bot, which
- * must reach the run it stops rather than sit in the buffer behind it (see {@link telegramStop}; a
- * bare group `/stop` addresses no one and stays ordinary discussion). Returns `{}` (act; the channel fills
- * session/target/prompt from the message) or `null` (ignore).
- */
+/** The default routing policy (used when `route` is omitted; exported so a custom route can reuse it). */
 export declare function defaultTelegramRoute(update: TelegramUpdate, options?: {
     botUsername?: string;
     botId?: number;

package/dist/channels/telegram/parse.js

@@ -1,16 +1,7 @@
-/**
- * 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.
- */
+/** Telegram protocol parsing — PURE: message field extraction, the prompt envelope, and the summon/route policy. */
 import { BUFFER_LINE_MAX_CHARS } from "../kit/context-buffer.js";
 import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../kit/text.js";
-/** 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. */
+/** The actionable message in an update (a fresh message or channel post). */
 export function pickMessage(update) {
     return update.message ?? update.channel_post;
 }
@@ -18,30 +9,28 @@ export function pickMessage(update) {
 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). */
+/** The message's OWN photo (largest size), without the replied-to message's. */
 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). */
+/** file_ids to download to disk: this message's files plus a replied-to message's ("summarize this file"). */
 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). */
+/** The message's OWN files, without the replied-to message's. */
 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. */
+/** A stable sender label for attribution. */
 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). */
+/**
+ * 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]";
@@ -56,9 +45,10 @@ export function attachmentSummary(m) {
         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. */
+/**
+ * A message's readable body: its text, else its caption, else a one-line attachment summary; undefined for an
+ * empty/service message.
+ */
 function bodyOf(m) {
     return m.text ?? m.caption ?? attachmentSummary(m);
 }
@@ -67,13 +57,8 @@ export function messageText(m) {
     return truncateCodePointPrefix((bodyOf(m) ?? "").replace(/\s+/g, " ").trim(), BUFFER_LINE_MAX_CHARS);
 }
 /**
- * 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.
+ * 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).
  */
 export function telegramEnvelope(m) {
     const r = m.reply_to_message;
@@ -84,9 +69,7 @@ export function telegramEnvelope(m) {
     ]
         .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.
+    // In a shared group session the model sees turns from different people (each `from`-tagged).
     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
@@ -101,20 +84,14 @@ export function telegramEnvelope(m) {
         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. */
+/** Normalize a configured bot username: drop a leading `@`, trim, lowercase (usernames are case-insensitive). */
 function botName(botUsername) {
     const s = botUsername?.replace(/^@/, "").trim().toLowerCase();
     return s || undefined;
 }
 /**
- * The `mention` ENTITIES naming THIS bot — read from what 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. Empty when the bot does not know
- * its own username — "which of these names me?" has no answer then, and guessing would mis-summon.
+ * The `mention` ENTITIES naming THIS bot — read from what Telegram's server already parsed, not a regex over the raw
+ * text.
  */
 function botMentions(m, botUsername) {
     const name = botName(botUsername);
@@ -124,14 +101,10 @@ function botMentions(m, botUsername) {
     const entities = (m.text !== undefined ? m.entities : m.caption_entities) ?? [];
     return entities.filter((e) => e.type === "mention" && text.slice(e.offset, e.offset + e.length).toLowerCase() === `@${name}`);
 }
-/** Whether the message @mentions the bot. */
 function mentionsBot(m, botUsername) {
     return botMentions(m, botUsername).length > 0;
 }
-/** The message text with THIS bot's mentions cut out, so a command addressed to it reads as the bare
- *  command. Only its own: a message that names someone else (`@otherbot /stop`) must keep that name,
- *  or cutting it would turn an ask aimed elsewhere into this bot's command. Cut from the end so the
- *  earlier offsets stay valid (they are UTF-16 code units = native JS indexing). */
+/** The message text with THIS bot's mentions cut out, so a command addressed to it reads as the bare command. */
 function textWithoutBotMentions(m, botUsername) {
     const text = m.text ?? m.caption ?? "";
     return botMentions(m, botUsername)
@@ -140,41 +113,27 @@ function textWithoutBotMentions(m, botUsername) {
         .trim();
 }
 /**
- * Whether the update is a `/stop` ADDRESSED TO THIS BOT — the one question the channel asks about a
- * stop, because an unaddressed one is not a command it may act on. Four ways to address it, all
- * equivalent: a bare `/stop` in a private chat (no one else is there), `/stop@thisbot`, an `@thisbot`
- * mention beside the command, and a bare `/stop` replying to one of this bot's messages.
- *
- * A BARE `/stop` in a group is deliberately NOT one of them. Telegram hands it to every bot in the
- * chat — and only promises to deliver it at all when this bot spoke last — so it names no one: acting
- * on it lets a bystander's ask for a different bot abort this bot's run, and answering it lets that
- * bystander make this bot talk. It stays ordinary discussion, which is what the group sees anyway.
- *
- * Takes the UPDATE, like `route` itself, so a custom route can ask it directly — that route is the
- * gate a stop must pass, and one that refuses this update silences the command.
+ * Whether the update is a `/stop` ADDRESSED TO THIS BOT — the one question the channel asks about a stop, because an
+ * unaddressed one is not a command it may act on.
  */
 export function telegramStop(update, options) {
     const m = pickMessage(update);
     if (!m)
         return false;
-    // This bot's own mentions are cut out before matching: `@thisbot /stop` is the same command as
-    // `/stop@thisbot`. Anyone else's stays in the text, so `@otherbot /stop` never reduces to a command
-    // here — not even when it also replies to this bot.
+    // This bot's own mentions are cut out before matching: `@thisbot /stop` is the same command as `/stop@thisbot`.
     const match = /^\/stop(?:@([A-Za-z0-9_]+))?$/i.exec(textWithoutBotMentions(m, options?.botUsername));
     if (!match)
         return false;
-    // `/stop@name` states its addressee: ours only when the name is ours, and never when this bot does
-    // not know its own username (fail closed — the same rule reply/mention summon follows).
+    // `/stop@name` states its addressee: ours only when the name is ours, and never when this bot does not know its own
+    // username (fail closed — the same rule reply/mention summon follows).
     if (match[1] !== undefined)
         return match[1].toLowerCase() === botName(options?.botUsername);
     return m.chat.type === "private" || mentionsBot(m, options?.botUsername) || repliesToBot(m, options);
 }
-/** 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. */
+/**
+ * Whether the message replies to THIS bot — not just any bot: in a multi-bot group, replying to another bot must not
+ * summon ours.
+ */
 function repliesToBot(m, options) {
     const r = m.reply_to_message?.from;
     if (r?.is_bot !== true)
@@ -184,16 +143,7 @@ function repliesToBot(m, options) {
     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) — except a `/stop` ADDRESSED to this bot, which
- * must reach the run it stops rather than sit in the buffer behind it (see {@link telegramStop}; a
- * bare group `/stop` addresses no one and stays ordinary discussion). Returns `{}` (act; the channel fills
- * session/target/prompt from the message) or `null` (ignore).
- */
+/** The default routing policy (used when `route` is omitted; exported so a custom route can reuse it). */
 export function defaultTelegramRoute(update, options) {
     const m = pickMessage(update);
     if (!m)
@@ -201,9 +151,7 @@ export function defaultTelegramRoute(update, options) {
     const summoned = m.chat.type === "private" ||
         repliesToBot(m, options) ||
         mentionsBot(m, options?.botUsername) ||
-        // Adds exactly ONE case to the three above: the `/stop@thisbot` suffix form. Every other way to
-        // address a stop (private, mention, reply) is already a summon on its own — telegramStop repeats
-        // those three by design, since it must answer "addressed to me?" without a route to lean on.
+        // Adds exactly ONE case to the three above: the `/stop@thisbot` suffix form.
         telegramStop(update, options);
     return summoned ? {} : null;
 }

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

@@ -6,14 +6,23 @@
  * message, works in groups and private (unlike sendMessageDraft, which is private/forum-topic only).
  */
 import type { AgentEvent } from "../../agent.ts";
+import * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
+import { type PortFailure } from "../../effect-port.ts";
 import { type ChannelFailure, defaultErrorMessage } from "../kit/preview-kit.ts";
 import { type Target } from "./telegram-api.ts";
 /** A terminal failure, as the channel hands it to `onError` — the shared channel shape. */
 export type TelegramFailure = ChannelFailure;
 export { defaultErrorMessage };
+/**
+ * Deliver a reply this process did not generate: a recovered answer. The run that produced it is gone with its
+ * preview, but a "⏳ Queued" notice THIS process put up while the record waited its turn is still there — so the
+ * same terminal-write policy applies, taking that message over rather than leaving it pinned above the answer.
+ */
+export declare function deliverTelegramAnswer(api: string, botToken: string, target: Target, text: string, previewId?: number): Promise<void>;
 /**
  * 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>;
+export declare function telegramReply(events: Stream.Stream<AgentEvent, PortFailure>, api: string, botToken: string, target: Target, formatError: (failed: TelegramFailure) => string | undefined, previewId?: number, onAnswered?: (answer: string) => void): Effect.Effect<void, PortFailure, import("effect/Scope").Scope>;

package/dist/channels/telegram/preview.js

@@ -1,4 +1,9 @@
-import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../kit/preview-kit.js";
+import * as Effect from "effect/Effect";
+import * as Clock from "effect/Clock";
+import { previewPump, renderReply } from "../kit/delivery.js";
+import { DROPPABLE_FRAME } from "../kit/transport.js";
+import { portJoin } from "../../effect-port.js";
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../kit/preview-kit.js";
 import { log } from "../../log.js";
 import { TELEGRAM_MAX_TEXT, callApi, editMessageText, sendMessage } from "./telegram-api.js";
 export { defaultErrorMessage };
@@ -10,7 +15,7 @@ const EDIT_THROTTLE_MS = 1500;
 /** How much of the (growing) reasoning to peek at in the live view — the most recent tail. */
 const THINKING_PREVIEW = 280;
 /**
- * The terminal-write POLICY: resolve the single preview message into `text`. streamReply owns the
+ * The terminal-write POLICY: resolve the single preview message into `text`. telegramReply 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.
@@ -44,109 +49,83 @@ async function finalize(api, botToken, target, messageId, text, opts = {}) {
     }
     await sendMessage(api, botToken, target, text, { html });
 }
+/**
+ * Deliver a reply this process did not generate: a recovered answer. The run that produced it is gone with its
+ * preview, but a "⏳ Queued" notice THIS process put up while the record waited its turn is still there — so the
+ * same terminal-write policy applies, taking that message over rather than leaving it pinned above the answer.
+ */
+export function deliverTelegramAnswer(api, botToken, target, text, previewId) {
+    return finalize(api, botToken, target, previewId, text);
+}
 /**
  * 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) {
-    // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal
-    // policy, formatting, and delivery below.
-    const turn = createTurnView();
-    const view = () => {
-        const v = composeTurnBody([
-            thinkingLine(turn, THINKING_PREVIEW),
-            toolLines(turn),
-            turn.retrying ? RETRY_NOTICE : "",
-            revealedAnswer(turn, EDIT_THROTTLE_MS),
-        ]);
-        // Before any reasoning/tool/text arrives, show an explicit placeholder rather than an empty edit.
-        return v === "" ? THINKING_PLACEHOLDER : 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");
-    };
-    // The shared single-writer pump (preview-kit) serializes edits to the one preview message. (No
-    // keepalive: a real message does not expire, unlike a Bot API `sendMessageDraft` (30s window).)
-    const { touch, finish } = createPreviewPump({
-        flush: flushPreview,
-        throttleMs: EDIT_THROTTLE_MS,
-        onError: (e) => log.warn(`[telegram] live preview failed (final reply still sends): ${String(e)}`),
-    });
-    touch(); // send the "💭 Thinking…" placeholder immediately
-    try {
-        for await (const e of events) {
-            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, turn.answer.trim() !== "" ? turn.answer : "(no reply)");
+export function telegramReply(events, api, botToken, target, formatError, previewId, onAnswered) {
+    return Effect.gen(function* () {
+        const clock = yield* Clock.Clock;
+        const now = () => clock.currentTimeMillisUnsafe();
+        // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal
+        // policy, formatting, and delivery below.
+        const turn = createTurnView();
+        const view = () => {
+            const v = composeTurnBody([
+                thinkingLine(turn, THINKING_PREVIEW),
+                toolLines(turn),
+                turn.retrying ? RETRY_NOTICE : "",
+                revealedAnswer(turn, EDIT_THROTTLE_MS, now()),
+            ]);
+            // Before any reasoning/tool/text arrives, show an explicit placeholder rather than an empty edit.
+            return v === "" ? THINKING_PLACEHOLDER : 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 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) {
+                // plain — a partial answer may carry unbalanced HTML; droppable — see DROPPABLE_FRAME.
+                await editMessageText(api, botToken, target, messageId, text, DROPPABLE_FRAME);
                 return;
             }
-            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,
-                        ...(e.code !== undefined ? { code: e.code } : {}),
-                    }) ?? "";
-                    await finalize(api, botToken, target, messageId, msg).catch(() => { });
-                }
-                throw new Error(`agent failed: ${e.details} (retryable=${e.retryable})`);
-            }
-            if (applyTurnEvent(turn, e))
-                touch();
-        }
-        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(() => { });
-        }
-    }
+            // 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).
+            //
+            // NOT droppable, unlike the frames above: this send happens once and every later frame depends on
+            // its id, so dropping it costs the whole turn's live preview rather than one redrawable view.
+            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");
+        };
+        const { touch, finish } = yield* previewPump({
+            flush: flushPreview,
+            throttleMs: EDIT_THROTTLE_MS,
+            onError: (e) => log.warn(`[telegram] live preview failed (final reply still sends): ${String(e)}`),
+        });
+        touch(); // send the "💭 Thinking…" placeholder immediately
+        yield* renderReply(events, {
+            label: "[telegram]",
+            finish,
+            formatError,
+            onEvent: (event) => {
+                if (applyTurnEvent(turn, event, now()))
+                    touch();
+            },
+            answer: () => (turn.answer.trim() !== "" ? turn.answer : "(no reply)"),
+            ...(onAnswered ? { onAnswered } : {}),
+            settle: (text) => portJoin(() => finalize(api, botToken, target, messageId, text)),
+        });
+    });
 }