@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/channels/stop-command.js

@@ -0,0 +1,36 @@
+/**
+ * SHARED user-facing stop command: the chat channels (telegram, feishu/lark, slack) map an explicit
+ * "stop" ask onto the session control plane's `abort`. Policy decisions (design session-control.md
+ * §15): the stop message is a CONTROL ACTION, never a turn (it must not queue behind the run it
+ * stops); only the ACTIVE run is aborted — queued durable turns are independent asks and keep their
+ * at-least-once floor; and the hub stays gated by `config.sessionControl`, so without it the command
+ * degrades to a visible "not enabled" notice, never a silent ignore.
+ */
+import { log } from "../log.js";
+import { NO_ACTIVE_RUN_CODE } from "../session.js";
+/** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
+export function isStopText(text) {
+    return /^(stop|cancel)[.!]?$/i.test(text.trim());
+}
+const STOPPED_NOTICE = "⏹ Stopped.";
+const NOTHING_RUNNING_NOTICE = "Nothing is running.";
+const STOP_UNAVAILABLE_NOTICE = "⚠️ Stop isn't enabled on this deployment (set sessionControl: true in fastagent.config).";
+/** Dispatch `abort` for the session and map the outcome to the customer-facing line. Never throws;
+ *  full details go to the operator log. */
+export async function dispatchStop(control, session, label) {
+    if (!control)
+        return STOP_UNAVAILABLE_NOTICE;
+    try {
+        const result = await control.dispatch(session, { type: "abort" });
+        if (result.ok)
+            return STOPPED_NOTICE;
+        if (result.error.code === NO_ACTIVE_RUN_CODE)
+            return NOTHING_RUNNING_NOTICE;
+        log.warn(`${label} stop dispatch rejected for ${session}: ${result.error.code} — ${result.error.message}`);
+        return `⚠️ Could not stop (${result.error.code}).`;
+    }
+    catch (error) {
+        log.warn(`${label} stop dispatch failed for ${session}: ${String(error)}`);
+        return "⚠️ Could not stop — see the server logs.";
+    }
+}

package/dist/channels/tasks.d.ts

@@ -0,0 +1,7 @@
+export interface TaskTracker {
+    /** Track one task. The caller keeps its own `.catch` — rejections must already be handled. */
+    track(task: Promise<unknown>): void;
+    /** Resolves when every currently-tracked task has settled. */
+    drain(): Promise<void>;
+}
+export declare function createTaskTracker(): TaskTracker;

package/dist/channels/tasks.js

@@ -0,0 +1,25 @@
+/**
+ * SHARED fire-and-forget side-task tracking. Channels launch work off the request path (stop
+ * feedback, DM welcomes) that must not block the transport ACK but MUST be drained on shutdown
+ * (`turnsIdle`) — otherwise a reply in flight when the process exits is silently dropped. Error
+ * handling stays with the caller: track() only guarantees the drain sees the task settle.
+ */
+import { beginWork } from "./busy.js";
+export function createTaskTracker() {
+    const tasks = new Set();
+    return {
+        track(task) {
+            tasks.add(task);
+            // Tracked side tasks count as process-wide in-flight work (busy.ts) — same signal the turn
+            // queue reports, read by serving surfaces that must not idle while background work runs.
+            const workDone = beginWork();
+            void task
+                .finally(() => {
+                workDone();
+                tasks.delete(task);
+            })
+                .catch(() => { }); // the caller's chain owns the error
+        },
+        drain: () => Promise.all(tasks).then(() => undefined),
+    };
+}

package/dist/channels/telegram/context-buffer.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Telegram's half of the shared context buffer (mechanics + consume protocol: ../context-buffer.ts):
+ * the entry shape, its fold-line rendering, and buffered-attachment selection. Bucketed by Telegram
+ * "place" (chat[:thread]), not session: an un-summoned message has no route session, and the flush
+ * feeds whatever turn answers that place.
+ */
+import { type ContextBuffer as GenericContextBuffer } from "../context-buffer.ts";
 /** One buffered un-summoned message (object identity is the commit key). Besides the sender label and
  *  one-line body, it carries what a LATER summon needs to resolve references into the discussion:
  *  message ids ("reply to the one Alex answered"), and attachment file_ids so "summarize the file from
@@ -39,21 +46,5 @@ export declare function collectAttachments(consumed: BufferEntry[], primary: {
     images: BufferedRef[];
     skipped: number;
 };
-export interface ContextBuffer {
-    /** Record an un-summoned message. Persists BEFORE returning (pre-ACK: a throw becomes the webhook's
-     *  500, and Telegram redelivers once the disk recovers) — staged on a copy and rolled back on a
-     *  failed write, so the redelivery does not double-append the entry already in memory. */
-    push(placeKey: string, entry: BufferEntry): void;
-    /** Render the fold text and snapshot the consumed entries (see the module header's consume protocol). */
-    peek(placeKey: string): {
-        text: string;
-        consumed: BufferEntry[];
-    };
-    /** Remove exactly `consumed` (by identity) — call on the turn's `completed` event, when the folded
-     *  discussion provably lives in the durable session. Consumes entries WHOLE, including ones whose
-     *  attachments failed to load or were cap-skipped: their text is in the session (keeping them would
-     *  re-fold duplicate text), and the prompt note said what is missing; re-post an attachment to use
-     *  it. Post-ACK: a failed write is logged, never thrown (it must not abort the turn's delivery). */
-    commit(placeKey: string, consumed: BufferEntry[]): void;
-}
+export type ContextBuffer = GenericContextBuffer<BufferEntry>;
 export declare function createContextBuffer(path: string): ContextBuffer;

package/dist/channels/telegram/context-buffer.js

@@ -1,29 +1,10 @@
 /**
- * Group-context buffer: recent UN-summoned messages per Telegram "place" (chat[:thread]), kept under a
- * char budget and folded into the next answered turn's prompt, so a summoned agent has the discussion
- * it didn't see turn-by-turn. Bucketed by place (not session): an un-summoned message has no route
- * session, and the flush feeds whatever turn answers that place.
- *
- * DURABLE: persisted synchronously before the webhook 200 (Telegram never redelivers an ACKed update,
- * so ACK-then-persist would be a silent-loss window) and reloaded on start. The consume protocol is
- * peek → (turn completes) → commit: peek renders WITHOUT clearing and snapshots exactly which entries
- * it consumed; commit removes only those, by object identity — so a failure or crash before the turn's
- * `completed` leaves them intact for the next summon, and a message that arrives while the turn runs
- * survives for the next answered turn (a whole-bucket delete would lose it).
+ * Telegram's half of the shared context buffer (mechanics + consume protocol: ../context-buffer.ts):
+ * the entry shape, its fold-line rendering, and buffered-attachment selection. Bucketed by Telegram
+ * "place" (chat[:thread]), not session: an un-summoned message has no route session, and the flush
+ * feeds whatever turn answers that place.
  */
-import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "../state.js";
-/** Char budget for the per-place buffer — bounds the cost of folding it into a prompt; when exceeded
- *  the OLDEST un-summoned messages are dropped (not a time window: a quiet group keeps its
- *  sparse-but-relevant lines, a busy burst is capped). */
-const BUFFER_MAX_CHARS = 4000;
-/** How many buffered files and images (each, most recent first) a summon pulls in with the folded
- *  discussion — bounds the latency/token cost of "summarize the file from earlier" against a chatty
- *  group posting many attachments between summons. Skipped ones are counted into the prompt note, so
- *  the model never sees an attachment reference it silently cannot open. */
-const BUFFER_ATTACH_MAX = 3;
-/** One fold line. ALSO the eviction cost basis: the budget must price what the fold actually renders
- *  (sender + body + the msg/reply meta), or the fold would systematically overrun BUFFER_MAX_CHARS. */
+import { BUFFER_ATTACH_MAX, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
 function bufferLine(e) {
     const meta = [
         e.messageId !== undefined ? `msg ${e.messageId}` : undefined,
@@ -64,8 +45,6 @@ export function collectAttachments(consumed, primary) {
         skipped: Math.max(0, files.length - BUFFER_ATTACH_MAX) + Math.max(0, images.length - BUFFER_ATTACH_MAX),
     };
 }
-/** State files are an IO boundary: valid JSON of the WRONG SHAPE (hand-edited, version drift) must
- *  degrade exactly like a corrupt file — warn + empty — not flow in as trusted data. */
 function isBufferEntry(e) {
     const t = e;
     const strings = (v) => v === undefined || (Array.isArray(v) && v.every((x) => typeof x === "string"));
@@ -77,63 +56,5 @@ function isBufferEntry(e) {
         strings(t.imageIds));
 }
 export function createContextBuffer(path) {
-    const load = () => {
-        const raw = loadStateFile(path);
-        if (raw === undefined)
-            return new Map();
-        if (typeof raw === "object" &&
-            raw !== null &&
-            !Array.isArray(raw) &&
-            Object.values(raw).every((v) => Array.isArray(v) && v.every(isBufferEntry))) {
-            return new Map(Object.entries(raw));
-        }
-        log.warn(`[telegram] unexpected shape in ${path} — starting with an empty buffer`);
-        return new Map();
-    };
-    const buffers = load();
-    const persist = () => saveStateFile(path, Object.fromEntries(buffers));
-    return {
-        push(placeKey, entry) {
-            const prev = buffers.get(placeKey);
-            const buf = prev ? [...prev] : [];
-            buf.push(entry);
-            let total = buf.reduce((n, e) => n + bufferLine(e).length + 1, 0);
-            while (buf.length > 1 && total > BUFFER_MAX_CHARS) {
-                const dropped = buf.shift();
-                if (dropped)
-                    total -= bufferLine(dropped).length + 1;
-            }
-            buffers.set(placeKey, buf);
-            try {
-                persist();
-            }
-            catch (e) {
-                if (prev)
-                    buffers.set(placeKey, prev);
-                else
-                    buffers.delete(placeKey);
-                throw e;
-            }
-        },
-        peek(placeKey) {
-            const buf = buffers.get(placeKey) ?? [];
-            return { text: buf.map(bufferLine).join("\n"), consumed: [...buf] };
-        },
-        commit(placeKey, consumed) {
-            const buf = buffers.get(placeKey);
-            if (!buf)
-                return;
-            const remaining = buf.filter((e) => !consumed.includes(e));
-            if (remaining.length === 0)
-                buffers.delete(placeKey);
-            else
-                buffers.set(placeKey, remaining);
-            try {
-                persist();
-            }
-            catch (e) {
-                log.error(`[telegram] buffer write failed post-ACK (a restart may re-fold answered discussion): ${String(e)}`);
-            }
-        },
-    };
+    return createGenericContextBuffer({ path, label: "[telegram]", isEntry: isBufferEntry, line: bufferLine });
 }

package/dist/channels/telegram/invoke-turn.d.ts

@@ -5,7 +5,8 @@
  * pure) because this half touches the Bot API + disk; split from telegram.ts so the factory keeps only
  * wiring and the per-turn lifecycle.
  */
-import { type Agent, type AgentEvent } from "../../agent.ts";
+import type { Agent, AgentEvent } from "../../agent.ts";
+import { type BusyRetry } from "../invoke-turn-kit.ts";
 import type { BufferedRef } from "./context-buffer.ts";
 /** Everything the transport needs to fetch a turn's attachments. */
 export interface TurnTransport {
@@ -27,27 +28,9 @@ export interface TurnAttachments {
         skipped: number;
     };
 }
-/** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
- *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
- *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
- *  always an outside holder — wait for it like a queued turn, instead of erroring at the user. */
-export interface BusyRetry {
-    delayMs: number;
-    maxWaitMs: number;
-}
 /**
- * Run one turn: resolve its attachments, then stream agent.invoke. A primary-attachment failure surfaces
- * as a `failed` event (never a silent drop). `onCompleted` (if given) fires on the turn's `completed`
- * event — the durable-commit point: only then does the folded discussion provably live in the session,
- * so a failure or crash at ANY earlier point leaves the buffer intact for the next summon (a re-folded
- * block beats lost context). The caller uses it to remove the turn intent AND commit the context buffer,
- * in that order (see the call site) so a crash between the two clears cannot replay a context-stripped turn.
- *
- * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn (e.g. a self-scheduled
- * wake) holds this session's lease and OUR turn never started — replay-safe. Retry (bounded) instead of
- * yielding it: the user sees the "Thinking…" placeholder while waiting (the mirror of the scheduler
- * deferring a wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a
- * FIRST-event busy retries — attachments are already resolved, and a fail-fast reject is the only shape
- * the engine emits it in, so nothing that started is ever re-run.
+ * Run one turn: resolve its attachments, then stream agent.invoke with the shared busy-wait
+ * (invoke-turn-kit — `onCompleted` is the durable-commit point; see streamTurnWithBusyRetry). A
+ * primary-attachment failure surfaces as a `failed` event (never a silent drop).
  */
 export declare function invokeTurn(agent: Agent, session: string, text: string, transport: TurnTransport, attachments: TurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;

package/dist/channels/telegram/invoke-turn.js

@@ -1,12 +1,5 @@
-/**
- * Run one turn (the IO half of Telegram→Agent translation): assemble its inputs — resolve attachments
- * (download files to disk, load vision images) — and stream `agent.invoke` with the assembled prompt.
- * `invokeTurn` is the export; attachment resolution is an internal step. Split from parse.ts (which is
- * pure) because this half touches the Bot API + disk; split from telegram.ts so the factory keeps only
- * wiring and the per-turn lifecycle.
- */
-import { SESSION_BUSY_CODE } from "../../agent.js";
 import { log } from "../../log.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
 import { resolveFiles, resolveImages } from "./telegram-api.js";
 /** Appended to the prompt (not the system prompt): the channel owns Telegram-HTML formatting. */
 const HTML_INSTRUCTION = "\n\n(Format your reply in Telegram-supported HTML — <b> <i> <u> <s> <code> <pre> <a href> — not Markdown.)";
@@ -52,10 +45,7 @@ async function resolveTurnAttachments(t, attachments) {
             log.warn(`[telegram] could not load an earlier (buffered) attachment: ${String(r.reason)}`);
         }
     }
-    const missing = lost + buffered.skipped;
-    const bufferedNote = missing > 0
-        ? `\n[note: ${missing} attachment(s) from the earlier discussion are not loaded (expired, or older than the most recent few)]`
-        : "";
+    const missingNote = missingAttachmentsNote(lost + buffered.skipped);
     // PRIMARY first, background after — consistent with "primary wins": what the user pointed at this
     // turn leads. Buffered file entries are attributed like the fold's text lines ("the file Bob sent"
     // resolves); buffered PHOTOS cannot be (ImageRef carries no label), so their attribution stops at
@@ -63,37 +53,18 @@ async function resolveTurnAttachments(t, attachments) {
     // documented limit.
     const allFiles = [
         ...(files ?? []),
-        ...bufferedFiles.map(({ file, ref }) => ({
-            ...file,
-            name: `${file.name} (from ${ref.from}${ref.msg !== undefined ? `, msg ${ref.msg}` : ""}, earlier discussion)`,
-        })),
+        ...bufferedFiles.map(({ file, ref }) => ({ ...file, name: attributedFileName(file.name, ref.from, ref.msg) })),
     ];
-    const manifest = allFiles.length
-        ? `\n\n[attached files — read them with your tools:\n${allFiles.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
-        : "";
     const allImages = [...(images ?? []), ...bufferedImages];
-    return { images: allImages.length ? allImages : undefined, promptSuffix: `${bufferedNote}${manifest}` };
+    return {
+        images: allImages.length ? allImages : undefined,
+        promptSuffix: `${missingNote}${attachedFilesManifest(allFiles)}`,
+    };
 }
-// Each retry is a lease-check-level reject (tryAcquire runs before harness assembly) — waiting is nearly
-// free, and the loop exits within one delay of the holder finishing. So the cap is sized to outlast a
-// real tool-using wake turn (minutes), not to be short: 10 min. CEILING: a holder that runs longer than
-// this still surfaces the busy error to the user — the bound exists so a stuck lease can't hang a chat
-// turn forever.
-const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
 /**
- * Run one turn: resolve its attachments, then stream agent.invoke. A primary-attachment failure surfaces
- * as a `failed` event (never a silent drop). `onCompleted` (if given) fires on the turn's `completed`
- * event — the durable-commit point: only then does the folded discussion provably live in the session,
- * so a failure or crash at ANY earlier point leaves the buffer intact for the next summon (a re-folded
- * block beats lost context). The caller uses it to remove the turn intent AND commit the context buffer,
- * in that order (see the call site) so a crash between the two clears cannot replay a context-stripped turn.
- *
- * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn (e.g. a self-scheduled
- * wake) holds this session's lease and OUR turn never started — replay-safe. Retry (bounded) instead of
- * yielding it: the user sees the "Thinking…" placeholder while waiting (the mirror of the scheduler
- * deferring a wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a
- * FIRST-event busy retries — attachments are already resolved, and a fail-fast reject is the only shape
- * the engine emits it in, so nothing that started is ever re-run.
+ * Run one turn: resolve its attachments, then stream agent.invoke with the shared busy-wait
+ * (invoke-turn-kit — `onCompleted` is the durable-commit point; see streamTurnWithBusyRetry). A
+ * primary-attachment failure surfaces as a `failed` event (never a silent drop).
  */
 export async function* invokeTurn(agent, session, text, transport, attachments, onCompleted, busyRetry = DEFAULT_BUSY_RETRY) {
     let resolved;
@@ -105,23 +76,5 @@ export async function* invokeTurn(agent, session, text, transport, attachments,
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${HTML_INSTRUCTION}`, images: resolved.images };
-    const deadline = Date.now() + busyRetry.maxWaitMs;
-    for (;;) {
-        let retryBusy = false;
-        let first = true;
-        for await (const e of agent.invoke({ session }, prompt)) {
-            if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
-                retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
-                break;
-            }
-            first = false;
-            if (e.type === "completed")
-                onCompleted?.(); // the turn is durably in the session — commit point
-            yield e;
-        }
-        if (!retryBusy)
-            return;
-        log.info(`[telegram] session ${session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
-        await new Promise((r) => setTimeout(r, busyRetry.delayMs));
-    }
+    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: "[telegram]", onCompleted, busyRetry });
 }

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

@@ -1,10 +1,3 @@
-/**
- * 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;

package/dist/channels/telegram/parse.js

@@ -5,6 +5,8 @@
  * "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.
  */
+import { BUFFER_LINE_MAX_CHARS } from "../context-buffer.js";
+import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../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
@@ -62,7 +64,7 @@ function bodyOf(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);
+    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
@@ -88,7 +90,7 @@ export function telegramEnvelope(m) {
     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)}]`
+        ? `\n[in reply to ${fromLabel(r.from) ?? `msg ${r.message_id}`} (msg ${r.message_id}): ${truncateCodePointPrefix(bodyOf(r) ?? "(empty)", REFERENT_MAX_CODE_POINTS)}]`
         : "";
     const parts = [bodyOf(m) ?? ""];
     if (m.location)

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

@@ -6,14 +6,11 @@
  * message, works in groups and private (unlike sendMessageDraft, which is private/forum-topic only).
  */
 import type { AgentEvent } from "../../agent.ts";
+import { type ChannelFailure, defaultErrorMessage } from "../preview-kit.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;
+/** A terminal failure, as the channel hands it to `onError` — the shared channel shape. */
+export type TelegramFailure = ChannelFailure;
+export { defaultErrorMessage };
 /**
  * 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

package/dist/channels/telegram/preview.js

@@ -1,37 +1,14 @@
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../preview-kit.js";
 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.";
-}
+export { defaultErrorMessage };
 /** 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
@@ -73,39 +50,18 @@ async function finalize(api, botToken, target, messageId, text, opts = {}) {
  * 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 : "";
-    };
+    // 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 = [thinkingView(), toolView(), answerView()]
-            .filter((s) => s.trim() !== "")
-            .join("\n\n")
-            .trim();
+        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…" : v;
+        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.
@@ -134,103 +90,27 @@ export async function streamReply(events, api, botToken, target, formatError, pr
         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();
-    };
+    // 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
-    // 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") {
+            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)");
+                await finalize(api, botToken, target, messageId, turn.answer.trim() !== "" ? turn.answer : "(no reply)");
                 return;
             }
-            else if (e.type === "failed") {
+            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
@@ -245,6 +125,8 @@ export async function streamReply(events, api, botToken, target, formatError, pr
                 }
                 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
     }