@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/channels/slack/slack-api.js

@@ -1,13 +1,12 @@
 /** Slack Web API transport: one JSON pipeline plus authenticated, capped private-file downloads. */
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { attachmentPath } from "../kit/attachment-path.js";
 import { codePointPrefix } from "../kit/text.js";
 const API_TIMEOUT_MS = 30_000;
 const DOWNLOAD_TIMEOUT_MS = 120_000;
 const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
 const RETRIES = 3;
 const MAX_RETRY_AFTER_S = 30;
-const MAX_REDIRECTS = 3;
 /** Slack's standard-Markdown fields cap each call at 12,000 characters. Keep headroom for
  * code-fence balancing and future server-side transformations. */
 const SLACK_MAX_MARKDOWN = 10_000;
@@ -95,11 +94,6 @@ export function chunkSlackMarkdown(markdown, maxPoints = SLACK_MAX_MARKDOWN) {
     }
     return output;
 }
-function safeFileName(file) {
-    const raw = file.name ?? file.title ?? file.id ?? "file";
-    const safe = raw.replace(/[/\\]/g, "_").replace(/^\.+/, "_") || "file";
-    return `${file.id ?? "slack"}-${safe}`;
-}
 function fileDownloadUrl(file) {
     if (file.file_access === "check_file_info")
         throw new Error(`Slack file ${file.id ?? "(unknown)"} is not ready`);
@@ -140,23 +134,7 @@ async function readBytesCapped(response) {
 }
 export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" }) {
     const apiBase = baseUrl.replace(/\/$/, "");
-    const configuredOrigin = new URL(apiBase).origin;
     const currentToken = typeof botToken === "string" ? async () => botToken : botToken;
-    const trustedDownloadUrl = (value) => {
-        const url = new URL(value);
-        const host = url.hostname.toLowerCase();
-        const slackHost = host === "slack-files.com" ||
-            host.endsWith(".slack-files.com") ||
-            host === "slack.com" ||
-            host.endsWith(".slack.com") ||
-            host === "slack-edge.com" ||
-            host.endsWith(".slack-edge.com");
-        if (!slackHost && url.origin !== configuredOrigin)
-            throw new Error(`refusing non-Slack file URL host ${host}`);
-        if (url.protocol !== "https:" && url.origin !== configuredOrigin)
-            throw new Error("refusing non-HTTPS Slack file URL");
-        return url;
-    };
     const call = async (method, body, httpMethod = "POST") => {
         const url = new URL(`${apiBase}/${method}`);
         if (httpMethod === "GET") {
@@ -211,36 +189,26 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
             throw new SlackApiError(method, response.status, detail, data.error);
         }
     };
+    // Slack owns both halves of this download: the URL comes from its own files.info response, and it
+    // documents url_private as taking our bearer token. Where that URL leads is Slack's call; whether a
+    // redirect hop still carries the token is fetch's, which drops the header cross-origin.
     const download = async (file) => {
-        let url = trustedDownloadUrl(fileDownloadUrl(file));
-        for (let redirect = 0;; redirect++) {
-            let response;
-            try {
-                const token = await currentToken();
-                response = await fetch(url, {
-                    headers: { authorization: `Bearer ${token}` },
-                    redirect: "manual",
-                    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
-                });
-            }
-            catch (error) {
-                throw new SlackApiError("file download", 0, String(error), undefined, { cause: error });
-            }
-            if (response.status >= 300 && response.status < 400) {
-                const location = response.headers.get("location");
-                if (!location || redirect >= MAX_REDIRECTS) {
-                    throw new SlackApiError("file download", response.status, "invalid or excessive redirect");
-                }
-                await response.body?.cancel().catch(() => { });
-                url = trustedDownloadUrl(new URL(location, url).toString());
-                continue;
-            }
-            if (!response.ok) {
-                const detail = codePointPrefix(await response.text().catch(() => ""), 300) || "file bytes were rejected";
-                throw new SlackApiError("file download", response.status, detail);
-            }
-            return { bytes: await readBytesCapped(response), contentType: response.headers.get("content-type") ?? undefined };
+        let response;
+        try {
+            const token = await currentToken();
+            response = await fetch(fileDownloadUrl(file), {
+                headers: { authorization: `Bearer ${token}` },
+                signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw new SlackApiError("file download", 0, String(error), undefined, { cause: error });
+        }
+        if (!response.ok) {
+            const detail = codePointPrefix(await response.text().catch(() => ""), 300) || "file bytes were rejected";
+            throw new SlackApiError("file download", response.status, detail);
         }
+        return { bytes: await readBytesCapped(response), contentType: response.headers.get("content-type") ?? undefined };
     };
     const api = {
         async authTest() {
@@ -387,10 +355,10 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
         },
         async fetchFile(file, channelId, filesDir) {
             const { bytes } = await download(file);
-            const dir = join(filesDir, channelId);
+            // The id prefix keeps two same-named uploads in one channel apart.
+            const suggested = `${file.id ?? "slack"}-${file.name ?? file.title ?? file.id ?? "file"}`;
+            const { dir, name, path } = attachmentPath(filesDir, channelId, suggested);
             await mkdir(dir, { recursive: true });
-            const name = safeFileName(file);
-            const path = join(dir, name);
             await writeFile(path, bytes);
             return { path, name, size: bytes.byteLength };
         },

package/dist/channels/slack/slack.js

@@ -5,13 +5,15 @@ import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { createSeenRing } from "../kit/seen.js";
+import { signatureIsFresh } from "../kit/signature.js";
 import { createThreadParticipants } from "../kit/thread-participants.js";
 import { createTaskTracker } from "../kit/tasks.js";
 import { ensureStateHome } from "../kit/state.js";
 import { dispatchStop, isStopText } from "../kit/stop-command.js";
 import { codePointPrefix } from "../kit/text.js";
 import { createTurnQueue } from "../kit/turn-queue.js";
-import { createTurnStore } from "../kit/turn-store.js";
+import { commitAnsweredTurn, createTurnStore } from "../kit/turn-store.js";
+import { discussionBlock } from "../kit/context-buffer.js";
 import { createSlackBotTokenProvider } from "./bot-auth.js";
 import { collectSlackBufferedFiles, createSlackContextBuffer } from "./context-buffer.js";
 import { invokeSlackTurn } from "./invoke-turn.js";
@@ -22,7 +24,8 @@ import { createSlackApi } from "./slack-api.js";
 import { createWelcomedUsers } from "./welcomed.js";
 export { defaultSlackRoute, slackEnvelope };
 const MAX_EVENT_BYTES = 1 << 20;
-const MAX_TURN_ATTEMPTS = 3;
+/** Slack's own documented window — it re-signs every redelivery with a current timestamp, so a tight
+ *  one costs nothing. The Feishu ingress reads hours off the same helper for the opposite reason. */
 const MAX_SIGNATURE_AGE_S = 5 * 60;
 const QUEUED_PLACEHOLDER = "⏳ Queued — I’ll start once the current task finishes.";
 const DEFERRED_PLACEHOLDER = "⏳ Delayed by a temporary system issue — I’ll retry automatically.";
@@ -45,10 +48,9 @@ function isStoredSlackTurn(value) {
 }
 /** Verify Slack's v0 HMAC over the exact raw body and reject timestamps outside the replay window. */
 export function verifySlackSignature(signingSecret, timestamp, signature, rawBody, nowMs = Date.now()) {
-    if (!/^\d+$/.test(timestamp) || !/^v0=[a-f0-9]{64}$/i.test(signature))
+    if (!/^v0=[a-f0-9]{64}$/i.test(signature))
         return false;
-    const seconds = Number(timestamp);
-    if (!Number.isSafeInteger(seconds) || Math.abs(Math.floor(nowMs / 1000) - seconds) > MAX_SIGNATURE_AGE_S)
+    if (!signatureIsFresh(timestamp, MAX_SIGNATURE_AGE_S, nowMs))
         return false;
     const expected = `v0=${createHmac("sha256", signingSecret).update(`v0:${timestamp}:${rawBody}`).digest("hex")}`;
     const actualBytes = Buffer.from(signature);
@@ -134,6 +136,9 @@ export function slackChannel(options) {
                 });
             });
         };
+        // Side tasks (stop feedback, DM welcomes) run off the ACK path but drain in turnsIdle. Declared
+        // ahead of its consumers so no construction-time path can reach it in the temporal dead zone.
+        const sideTasks = createTaskTracker(label);
         const seen = createSeenRing(join(stateHome, "seen.json"), label);
         const threadParticipants = createThreadParticipants(join(stateHome, "thread-participants.json"), label);
         /** A thread's participation is keyed by the SESSION it describes — "the agent answered here" is a
@@ -186,7 +191,7 @@ export function slackChannel(options) {
                     log.error(`${label} deferring durable turn ${turn.id} because Slack authentication failed: ${String(error)}`);
                     return;
                 }
-                const attempt = store.startAttempt(turn.id, MAX_TURN_ATTEMPTS);
+                const attempt = store.startAttempt(turn.id);
                 if (attempt === "exceeded") {
                     notifyDropped(turn);
                     return;
@@ -205,7 +210,7 @@ export function slackChannel(options) {
                 const startedAt = Date.now();
                 log.info(`${label} turn start: turn=${turn.id} session=${turn.session} channel=${turn.channelId}`);
                 const { text: recent, consumed } = buffer.peek(turn.bufferKey);
-                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${turn.baseText}` : turn.baseText;
+                const prompt = `${discussionBlock(recent)}${turn.baseText}`;
                 const buffered = collectSlackBufferedFiles(consumed, new Set(turn.fileIds));
                 const messageRef = messageRefOf(turn.id);
                 const reaction = reactionEmojis && messageRef
@@ -218,10 +223,7 @@ export function slackChannel(options) {
                     })
                     : undefined;
                 try {
-                    await streamSlackReply(invokeSlackTurn(agent, turn.session, prompt, { api, channelId: turn.channelId, filesDir: join(stateHome, "files"), label }, { primaryFileIds: turn.fileIds, buffered }, () => {
-                        store.remove(turn.id);
-                        buffer.commit(turn.bufferKey, consumed);
-                    }), api, targetOf(turn), formatError, {
+                    await streamSlackReply(invokeSlackTurn(agent, turn.session, prompt, { api, channelId: turn.channelId, filesDir: join(stateHome, "files"), label }, { primaryFileIds: turn.fileIds, buffered }, () => commitAnsweredTurn(store, buffer, { id: turn.id, bufferKey: turn.bufferKey, consumed })), api, targetOf(turn), formatError, {
                         rendering,
                         initialPreviewTs: turn.previewTs,
                         threadTitle: turn.threadTitle,
@@ -410,8 +412,6 @@ export function slackChannel(options) {
                 });
             }
         };
-        // Side tasks (stop feedback, DM welcomes) run off the ACK path but drain in turnsIdle.
-        const sideTasks = createTaskTracker();
         // First-run DM welcome: app_home_opened(tab="messages") signals a DM open. Post once per user.
         const welcomeInFlight = new Set();
         const maybeWelcome = (envelope) => {

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

@@ -139,12 +139,32 @@ export declare function messageText(m: TelegramMessage): string;
  * `text: `${telegramEnvelope(m)}\n\n[extra]``. The channel still appends downloaded attachments.
  */
 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.
+ */
+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). Returns `{}` (act; the channel fills
+ * 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).
  */
 export declare function defaultTelegramRoute(update: TelegramUpdate, options?: {

package/dist/channels/telegram/parse.js

@@ -108,20 +108,66 @@ function botName(botUsername) {
     return s || undefined;
 }
 /**
- * Whether the message @mentions the bot — read from the `mention` ENTITIES Telegram's server already
- * parsed, not a regex over the raw text. The entity type excludes by construction what a text scan
- * false-matches: `@bot` inside a code block or a URL is not a `mention` entity, a glued `/cmd@bot` is a
- * `bot_command` — and slicing the exact offset/length range makes `@fast` vs `@fastagent` confusion
- * impossible. (Offsets are UTF-16 code units = native JS string indexing.) No text fallback: mention
- * entities are produced server-side, so their absence means there is no mention.
+ * 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.
  */
-function mentionsBot(m, botUsername) {
+function botMentions(m, botUsername) {
     const name = botName(botUsername);
     if (!name)
-        return false;
+        return [];
     const text = m.text ?? m.caption ?? "";
     const entities = (m.text !== undefined ? m.entities : m.caption_entities) ?? [];
-    return entities.some((e) => e.type === "mention" && text.slice(e.offset, e.offset + e.length).toLowerCase() === `@${name}`);
+    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). */
+function textWithoutBotMentions(m, botUsername) {
+    const text = m.text ?? m.caption ?? "";
+    return botMentions(m, botUsername)
+        .sort((a, b) => b.offset - a.offset)
+        .reduce((out, e) => out.slice(0, e.offset) + out.slice(e.offset + e.length), text)
+        .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.
+ */
+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.
+    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).
+    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
@@ -143,13 +189,21 @@ function repliesToBot(m, options) {
  * answer private chats always; a group only on a reply to THIS bot (by `botId`) or a `mention` entity
  * naming it (when `botUsername` is supplied — telegramChannel parses the id from the token and resolves
  * the username via getMe). A bare or directed slash command does NOT summon in a group (that was noisy;
- * a bot author who wants commands adds a custom route). Returns `{}` (act; the channel fills
+ * 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).
  */
 export function defaultTelegramRoute(update, options) {
     const m = pickMessage(update);
     if (!m)
         return null;
-    const summoned = m.chat.type === "private" || repliesToBot(m, options) || mentionsBot(m, options?.botUsername);
+    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.
+        telegramStop(update, options);
     return summoned ? {} : null;
 }

package/dist/channels/telegram/scaffold/channel.ts

@@ -15,11 +15,15 @@ export default telegramChannel({
   // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
   // full details always go to the server log regardless.
   onError: (failed) => `⚠️ ${failed.details}`,
+  // Your bot's @username. Optional — resolved via getMe when omitted — but set it if you pass a `route`
+  // below: the channel needs its own copy to recognise a `/stop` addressed to it.
+  // botUsername: "your_bot",
   // The channel owns transport + format (HTML) + attachments (photo→vision, file→disk) + streaming.
   // `route` (POLICY) is OPTIONAL — omitted, it uses defaultTelegramRoute: private chats always answer,
-  // groups only on a reply to THIS bot or an @mention of it. Override to customise, reusing the
-  // export — but pass your bot's identity: group summon needs it (the omitted default gets it from
-  // the channel; a bare `defaultTelegramRoute(u)` answers only private chats):
+  // groups only on a reply to THIS bot, an @mention of it, or a `/stop` addressed to it. Override to
+  // customise, reusing the export — but pass your bot's identity BOTH here and as `botUsername` above
+  // (the omitted default gets it from the channel; a bare `defaultTelegramRoute(u)` answers only
+  // private chats):
   //   route: (u) => defaultTelegramRoute(u, { botUsername: "my_bot" }) && { session: `user:${u.message?.from?.id}` },
   //   route: (u) => defaultTelegramRoute(u, { botUsername: "my_bot" }) && { text: `${telegramEnvelope(u.message!)}\n[extra]` },
 });

package/dist/channels/telegram/telegram-api.js

@@ -16,7 +16,8 @@
  * parse fallback, and the getFile→download dance. (telegram.ts orchestrates; no agent, no rendering.)
  */
 import { mkdir, writeFile } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename } from "node:path";
+import { attachmentPath } from "../kit/attachment-path.js";
 /** Telegram's hard text limit per message. */
 export const TELEGRAM_MAX_TEXT = 4096;
 const PARSE_ERROR = /can't parse|entit|unsupported|unclosed|tag/i;
@@ -317,12 +318,10 @@ async function fetchTelegramImage(api, botToken, fileId) {
 /** Download a Telegram file_id to <filesDir>/<chat>/<name>. Throws on failure / oversize. */
 async function downloadTelegramFile(api, botToken, fileId, chatId, filesDir) {
     const { bytes, remotePath } = await getFileBytes(api, botToken, fileId);
-    const name = basename(remotePath);
-    const dir = join(filesDir, String(chatId));
+    const { dir, name, path } = attachmentPath(filesDir, chatId, basename(remotePath));
     await mkdir(dir, { recursive: true });
-    const dest = join(dir, name);
-    await writeFile(dest, bytes);
-    return { path: dest, name, size: bytes.byteLength };
+    await writeFile(path, bytes);
+    return { path, name, size: bytes.byteLength };
 }
 /** Fetch the message's images. Throws if any cannot be loaded — the caller surfaces it (no silent drop). */
 export async function resolveImages(api, botToken, fileIds) {

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

@@ -1,7 +1,7 @@
 import type { ChannelModule } from "../../channel.ts";
-import { type TelegramMessage, type TelegramRoute, type TelegramUpdate, defaultTelegramRoute, telegramEnvelope } from "./parse.ts";
+import { type TelegramMessage, type TelegramRoute, type TelegramUpdate, defaultTelegramRoute, telegramEnvelope, telegramStop } from "./parse.ts";
 import { type TelegramFailure } from "./preview.ts";
-export { defaultTelegramRoute, telegramEnvelope };
+export { defaultTelegramRoute, telegramEnvelope, telegramStop };
 export type { TelegramFailure, TelegramMessage, TelegramRoute, TelegramUpdate };
 export interface TelegramChannelOptions {
     /** Webhook secret token (the `secret_token` you set via setWebhook); verifies inbound updates. */

package/dist/channels/telegram/telegram.js

@@ -29,25 +29,17 @@ import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { invokeTurn } from "./invoke-turn.js";
 import { collectAttachments, createContextBuffer } from "./context-buffer.js";
-import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, } from "./parse.js";
+import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, telegramStop, } from "./parse.js";
 import { defaultErrorMessage, streamReply } from "./preview.js";
 import { ensureStateHome } from "../kit/state.js";
 import { dispatchStop } from "../kit/stop-command.js";
 import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
 import { createTurnQueue } from "../kit/turn-queue.js";
+import { commitAnsweredTurn } from "../kit/turn-store.js";
+import { discussionBlock } from "../kit/context-buffer.js";
 import { createTurnStore } from "./turn-store.js";
 // Re-export the public surface authored elsewhere, so `@fastagent-sh/fastagent/telegram` keeps one entry point.
-export { defaultTelegramRoute, telegramEnvelope };
-/** Execution ceiling: a turn that has STARTED running this many times without finishing is dropped
- *  rather than run again (a poison turn must not loop forever under a restart policy). Counted per turn
- *  at dequeue, so a never-run turn queued behind a poison one keeps its full budget.
- *
- *  Known limitation: `startAttempt` cannot tell a self-inflicted process crash from an external SIGTERM
- *  (no graceful drain), so a legitimately LONG turn interrupted by this many successive deploys is
- *  dropped ("please ask again") as if it were poison. Accepted: catching SIGTERM to spare it would
- *  reintroduce the drain the design refuses, and a turn outliving this many deploy cycles is an outlier
- *  — raise this constant if such turns are expected. */
-const MAX_TURN_ATTEMPTS = 3;
+export { defaultTelegramRoute, telegramEnvelope, telegramStop };
 /** Update body cap — Telegram updates are small JSON; 1 MiB is generous and guards a public endpoint. */
 const MAX_UPDATE_BYTES = 1 << 20;
 /** Constant-time compare so the secret-token check leaks no timing signal. */
@@ -77,9 +69,10 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             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
-        // group messages that feed the context buffer, so warn if it is on.
+        // One getMe at startup: the bot's @username (for the default route's group @mention summon and for
+        // recognising an addressed `/stop`, only when not supplied) and the group-privacy flag — privacy
+        // mode off is required to receive the un-summoned group messages that feed the context buffer, so
+        // warn if it is on.
         let mentionName = botUsername;
         void callApi(apiBaseUrl, botToken, "getMe", {}).then((me) => {
             if (mentionName === undefined)
@@ -88,7 +81,11 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 log.warn("[telegram] privacy mode is on: the bot only sees @mentions / replies / commands, so group " +
                     "context (un-summoned messages) won't be captured. Disable it via @BotFather → /setprivacy.");
             }
-        }, (e) => log.warn(`[telegram] getMe failed; @mention summon + privacy check skipped: ${String(e)}`));
+        }, 
+        // Name every capability the missing username costs, so "the bot ignores /stop@name" is
+        // diagnosable from this ONE line — the alternative, a warn per undecidable message, repeats a
+        // single startup fact on every update.
+        (e) => log.warn(`[telegram] getMe failed; @mention summon, addressed /stop, and the privacy check are skipped: ${String(e)}`));
         // A bot token is "<bot_id>:<secret>" — the bot's own id is knowable synchronously, so reply-to-bot
         // targeting is precise from the first update (no getMe race; getMe only resolves the @username).
         // Every real token parses; one that doesn't (a mock/test token) degrades visibly: reply summon stays
@@ -154,10 +151,10 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 await notices.get(rec.id);
                 notices.delete(rec.id);
                 // Count this execution against the durable record (poison-turn ceiling) before running it again.
-                const decision = store.startAttempt(rec.id, MAX_TURN_ATTEMPTS);
+                const decision = store.startAttempt(rec.id);
                 if (decision === "exceeded") {
-                    // Started MAX_TURN_ATTEMPTS times without finishing — tell the asker (reusing its ⏳ notice if
-                    // any), drop it.
+                    // Started the ceiling's worth of times without finishing (turn-store.ts MAX_TURN_ATTEMPTS) —
+                    // tell the asker (reusing its ⏳ notice if any), drop it.
                     notifyDropped(rec);
                     return;
                 }
@@ -182,7 +179,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 // Fold the un-summoned discussion since the last answered turn into the prompt; it is cleared
                 // only when the turn COMPLETES (then it lives in the session).
                 const { text: recent, consumed } = buffer.peek(rec.placeKey);
-                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${rec.baseText}` : rec.baseText;
+                const prompt = `${discussionBlock(recent)}${rec.baseText}`;
                 const buffered = collectAttachments(consumed, {
                     files: new Set(rec.fileIds),
                     images: new Set(rec.imageFileIds),
@@ -204,14 +201,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                             fileIds: rec.fileIds,
                         },
                         buffered,
-                    }, () => {
-                        // On completed, ORDER the two durable clears so a crash between them can't replay a
-                        // context-stripped turn: drop the intent FIRST (a crash after this won't replay it), THEN
-                        // commit the context buffer (a crash before this just re-folds the same context into the
-                        // next summon — harmless and additive). The reverse order would leave intent+no-context.
-                        store.remove(rec.id);
-                        buffer.commit(rec.placeKey, consumed);
-                    }), apiBaseUrl, botToken, target, formatError, rec.previewId);
+                    }, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey: rec.placeKey, consumed })), apiBaseUrl, botToken, target, formatError, rec.previewId);
                     log.info(`[telegram] turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
                 }
                 catch (error) {
@@ -313,47 +303,45 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 }
                 return new Response(null, { status: 200 });
             }
-            {
-                const session = r.session ?? placeKey;
-                const chatId = r.chatId ?? m.chat.id;
-                // Reply to the summoning message in groups (threads the answer under the asker); a 1:1 DM needs no
-                // reply-quote. Only when the RESOLVED target is the message's own chat+thread: a route that
-                // redirects elsewhere must not carry a reply_parameters that resolves in the wrong place (fail, or
-                // quote a same-id message there). Compare VALUES, not whether the route touched the field — a route
-                // 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);
-                if (baseText.trim() !== "" || imageFileIds.length > 0 || fileIds.length > 0) {
-                    // Everything the turn needs, as a plain record; persisted pre-ACK then run serially per session.
-                    submit({
-                        id: `${update.update_id}`,
-                        session,
-                        placeKey,
-                        baseText,
-                        chatId,
-                        threadId,
-                        replyTo: m.chat.type !== "private" && sameTarget ? m.message_id : undefined,
-                        imageFileIds,
-                        fileIds,
-                    }, true);
-                }
+            const session = r.session ?? placeKey;
+            const chatId = r.chatId ?? m.chat.id;
+            // Reply to the summoning message in groups (threads the answer under the asker); a 1:1 DM needs no
+            // reply-quote. Only when the RESOLVED target is the message's own chat+thread: a route that
+            // redirects elsewhere must not carry a reply_parameters that resolves in the wrong place (fail, or
+            // quote a same-id message there). Compare VALUES, not whether the route touched the field — a route
+            // 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;
+            const replyTo = m.chat.type !== "private" && sameTarget ? m.message_id : undefined;
+            // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the
+            // run it stops. Awaited before the ACK: dispatch + one sendMessage is fast, and a delivery failure
+            // logs instead of failing the webhook. Read AFTER the route, on the route's own session: the route
+            // is both the gate (a route that ignores this chat must not have the bot abort or answer in it) and
+            // the session authority (a route that remaps `session` would otherwise have its stop abort a
+            // session nobody runs). The default route summons an ADDRESSED `/stop` in a group for this reason:
+            // the general slash-command refusal would leave it buffered as discussion while the run kept going.
+            // An unaddressed one is not a command at all (see telegramStop) and never reaches here.
+            if (telegramStop(update, { botUsername: mentionName, botId })) {
+                const feedback = await dispatchStop(control, session, "[telegram]");
+                await sendMessage(apiBaseUrl, botToken, { chatId, threadId, replyTo }, 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);
+            if (baseText.trim() !== "" || imageFileIds.length > 0 || fileIds.length > 0) {
+                // Everything the turn needs, as a plain record; persisted pre-ACK then run serially per session.
+                submit({
+                    id: `${update.update_id}`,
+                    session,
+                    placeKey,
+                    baseText,
+                    chatId,
+                    threadId,
+                    replyTo,
+                    imageFileIds,
+                    fileIds,
+                }, true);
             }
             return new Response(null, { status: 200 });
         };