@fastagent-sh/fastagent 0.14.0 → 0.15.0

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/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
     }

package/dist/channels/telegram/telegram.js

@@ -32,6 +32,7 @@ import { collectAttachments, createContextBuffer } from "./context-buffer.js";
 import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, } from "./parse.js";
 import { defaultErrorMessage, streamReply } from "./preview.js";
 import { ensureStateHome } from "../state.js";
+import { dispatchStop } from "../stop-command.js";
 import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
 import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "./turn-store.js";
@@ -67,15 +68,14 @@ function tokenMatches(header, secret) {
  * share the first's turn-store/context-buffer. One telegram instance per workspace (single-process).
  */
 export function telegramChannel({ secretToken, botToken, route, onError, botUsername, apiBaseUrl = "https://api.telegram.org", }) {
-    // Both are mandatory: an unset secret_token would accept forged updates (the endpoint is public);
-    // the bot token is required to send the reply. Fail at construction (startup), not silently.
-    if (!secretToken) {
-        throw new Error("telegramChannel requires a non-empty secretToken (the webhook secret_token; an unset one accepts forged updates)");
-    }
-    if (!botToken) {
-        throw new Error("telegramChannel requires a non-empty botToken (used to send the agent's reply)");
-    }
-    return ({ agent, stateRoot }) => {
+    return ({ agent, stateRoot, control }) => {
+        // Validate at activation so deploy may inspect the module shape before secrets are provisioned.
+        if (!secretToken) {
+            throw new Error("telegramChannel requires a non-empty secretToken (the webhook secret_token; an unset one accepts forged updates)");
+        }
+        if (!botToken) {
+            throw new Error("telegramChannel requires a non-empty botToken (used to send the agent's reply)");
+        }
         const formatError = onError ?? defaultErrorMessage;
         // One getMe at startup: the bot's @username (for the default route's group @mention summon, only when
         // not supplied) and the group-privacy flag — privacy mode off is required to receive the un-summoned
@@ -323,6 +323,20 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 // that explicitly returns the same chat/thread still quotes.
                 const threadId = r.threadId ?? m.message_thread_id;
                 const sameTarget = String(chatId) === String(m.chat.id) && threadId === m.message_thread_id;
+                // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the
+                // run it stops. `/stop@otherbot` is not ours; a bare `/stop` always is. Awaited before the ACK:
+                // dispatch + one sendMessage is fast, and a delivery failure logs instead of failing the webhook.
+                const stopMatch = /^\/stop(?:@([A-Za-z0-9_]+))?$/i.exec(messageText(m).trim());
+                if (stopMatch && (!stopMatch[1] || stopMatch[1].toLowerCase() === mentionName?.toLowerCase())) {
+                    const feedback = await dispatchStop(control, session, "[telegram]");
+                    const target = {
+                        chatId,
+                        threadId,
+                        replyTo: m.chat.type !== "private" && sameTarget ? m.message_id : undefined,
+                    };
+                    await sendMessage(apiBaseUrl, botToken, target, feedback, { html: false }).catch((e) => log.warn(`[telegram] stop feedback failed: ${String(e)}`));
+                    return new Response(null, { status: 200 });
+                }
                 const baseText = r.text ?? telegramEnvelope(m);
                 const imageFileIds = extractImages(m);
                 const fileIds = extractFiles(m);

package/dist/channels/{feishu/text.d.ts → text.d.ts}

@@ -1,4 +1,4 @@
-/** Pure Unicode-safe text slicing helpers shared by Feishu/Lark rendering paths. JavaScript string
+/** Pure Unicode-safe text slicing helpers shared by channel rendering paths (Feishu/Lark cards, the preview kit). JavaScript string
  * indexes are UTF-16 code units, so direct `slice()` can tear a surrogate pair and send replacement
  * characters after JSON/UTF-8 encoding. These helpers only cut at Unicode code-point boundaries. */
 /** Take at most `maxPoints` Unicode code points from the start, without adding a marker. */

package/dist/channels/{feishu/text.js → text.js}

@@ -1,4 +1,4 @@
-/** Pure Unicode-safe text slicing helpers shared by Feishu/Lark rendering paths. JavaScript string
+/** Pure Unicode-safe text slicing helpers shared by channel rendering paths (Feishu/Lark cards, the preview kit). JavaScript string
  * indexes are UTF-16 code units, so direct `slice()` can tear a surrogate pair and send replacement
  * characters after JSON/UTF-8 encoding. These helpers only cut at Unicode code-point boundaries. */
 /** Take at most `maxPoints` Unicode code points from the start, without adding a marker. */

package/dist/channels/turn-queue.js

@@ -5,7 +5,7 @@
  * instead of colliding on the lease and being dropped as "busy").
  *
  * Channel-neutral (records are opaque beyond a `session` key), shared by the stateful chat channels
- * (telegram, Feishu; Lark reuses Feishu). Durability is layered ON TOP by the caller: turn-store.ts
+ * (Telegram, Feishu/Lark, Slack). Durability is layered ON TOP by the caller: turn-store.ts
  * persists an accepted turn's intent pre-ACK and replays a crash-surviving one on the next start (L1,
  * process-crash recovery, at-least-once). Exactly-once / deterministic step-replay (L2) is the K-axis
  * backend — an external queue with distributed locking (SPEC §11) — not this in-memory queue.

package/dist/channels/turn-store.d.ts

@@ -9,7 +9,7 @@ export interface TurnRecordBase {
     attempts: number;
 }
 export interface TurnStore<T extends TurnRecordBase> {
-    /** Persist an accepted turn before the ACK. A failed write throws (→ webhook 500, the platform redelivers). */
+    /** Persist an accepted turn before the ACK. A failed write throws (→ HTTP response / WS ACK 500, so the platform redelivers). */
     add(rec: T): void;
     /** Remove a finished turn. Post-ACK: a failed write is logged, never thrown (must not abort delivery). */
     remove(id: string): void;

package/dist/channels/turn-store.js

@@ -31,8 +31,7 @@
  *
  * Channel-neutral, generic over the record shape: the channel supplies its own record type (everything
  * its runner needs to re-execute the turn), the shape validator (state files are an IO boundary), the
- * arrival ordering for recovery, and its log label. telegram/turn-store.ts and the Feishu channel are the
- * two consumers.
+ * arrival ordering for recovery, and its log label. Telegram, Feishu/Lark, and Slack consume it.
  *
  * ponytail: at-least-once with a per-turn EXECUTION ceiling. A poison turn that deterministically
  * crashes the process would replay forever under a container restart policy. The counter is bumped at
@@ -84,7 +83,7 @@ export function createTurnStore(path, opts) {
                 return;
             turns.set(rec.id, rec);
             try {
-                persist(); // pre-ACK: a throw becomes the webhook's 500 and the platform redelivers
+                persist(); // pre-ACK: the transport maps this throw to HTTP/WS 500, so the platform redelivers
             }
             catch (e) {
                 // Roll the memory back so it matches disk (mirrors context-buffer.push): otherwise the phantom

package/dist/cli/add-feishu.d.ts

@@ -0,0 +1,27 @@
+import { type FeishuGroupBehavior, type FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
+import { type FeishuApi } from "../channels/feishu/feishu-api.ts";
+import { type GroupBehaviorChoice } from "../scaffold/add-channel.ts";
+export interface GroupBehaviorSetup {
+    /** Safe to proceed to version publishing now; false means Permissions still needs manual/admin work. */
+    publishReady: boolean;
+}
+export declare function configureGroupBehavior(input: {
+    kind: "feishu" | "lark";
+    appId: string;
+    apiBase: string;
+    api: Pick<FeishuApi, "listAppScopes" | "addAppScopes">;
+    behavior: FeishuGroupBehavior;
+    /** Whether the author chose the behavior (flag or prompt). A defaulted "context" inspects and
+     * reports only — it must never PATCH the sensitive scope into the app draft. */
+    explicit: boolean;
+    note?: (message: string) => void;
+    openUrl?: (url: string) => void;
+}): Promise<GroupBehaviorSetup>;
+/**
+ * Create or resume the platform app behind `add feishu` / `add lark`. Returns credentials for the
+ * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
+ * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
+ * irreversible and must not wait for the caller). Throws on refusal (a committable .env, a
+ * non-interactive lark run); the caller surfaces that as a startup failure.
+ */
+export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", envIgnored: boolean, ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehaviorChoice): Promise<Record<string, string> | undefined>;