@fastagent-sh/fastagent 0.18.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 { codePointPrefix } from "../text.js";
+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.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelModule } from "../../host/node.ts";
+import type { ChannelModule } from "../../channel.ts";
 import { type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRoute, defaultSlackRoute, slackEnvelope } from "./parse.ts";
 import { type SlackFailure, type SlackRendering } from "./preview.ts";
 export { defaultSlackRoute, slackEnvelope };

package/dist/channels/slack/slack.js

@@ -4,14 +4,16 @@ import { isAbsolute, join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
-import { createSeenRing } from "../seen.js";
-import { createThreadParticipants } from "../thread-participants.js";
-import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome } from "../state.js";
-import { dispatchStop, isStopText } from "../stop-command.js";
-import { codePointPrefix } from "../text.js";
-import { createTurnQueue } from "../turn-queue.js";
-import { createTurnStore } from "../turn-store.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 { 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/slack/welcomed.js

@@ -1,6 +1,6 @@
 /** Durable set of users who have already received the first-run DM welcome, so it is sent at most once. */
 import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "../state.js";
+import { loadStateFile, saveStateFile } from "../kit/state.js";
 function key(teamId, userId) {
     return `${teamId}:${userId}`;
 }

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

@@ -1,10 +1,10 @@
 /**
- * Telegram's half of the shared context buffer (mechanics + consume protocol: ../context-buffer.ts):
+ * Telegram's half of the shared context buffer (mechanics + consume protocol: ../kit/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";
+import { type ContextBuffer as GenericContextBuffer } from "../kit/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

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

@@ -1,10 +1,10 @@
 /**
- * Telegram's half of the shared context buffer (mechanics + consume protocol: ../context-buffer.ts):
+ * Telegram's half of the shared context buffer (mechanics + consume protocol: ../kit/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 { BUFFER_ATTACH_MAX, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
+import { BUFFER_ATTACH_MAX, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
 function bufferLine(e) {
     const meta = [
         e.messageId !== undefined ? `msg ${e.messageId}` : undefined,

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

@@ -6,7 +6,7 @@
  * wiring and the per-turn lifecycle.
  */
 import type { Agent, AgentEvent } from "../../agent.ts";
-import { type BusyRetry } from "../invoke-turn-kit.ts";
+import { type BusyRetry } from "../kit/invoke-turn-kit.ts";
 import type { BufferedRef } from "./context-buffer.ts";
 /** Everything the transport needs to fetch a turn's attachments. */
 export interface TurnTransport {

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

@@ -1,5 +1,5 @@
 import { log } from "../../log.js";
-import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../kit/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.)";

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

@@ -5,8 +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";
+import { BUFFER_LINE_MAX_CHARS } from "../kit/context-buffer.js";
+import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../kit/text.js";
 /** The actionable message in an update (a fresh message or channel post). Edits (`edited_message` /
  *  `edited_channel_post`) are deliberately NOT actionable: answering them re-answers every typo fix (a
  *  duplicate reply per edit), so an edited message changes nothing — the standard bot behavior. The
@@ -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/preview.d.ts

@@ -6,7 +6,7 @@
  * 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 ChannelFailure, defaultErrorMessage } from "../kit/preview-kit.ts";
 import { type Target } from "./telegram-api.ts";
 /** A terminal failure, as the channel hands it to `onError` — the shared channel shape. */
 export type TelegramFailure = ChannelFailure;

package/dist/channels/telegram/preview.js

@@ -1,4 +1,4 @@
-import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../preview-kit.js";
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../kit/preview-kit.js";
 import { log } from "../../log.js";
 import { TELEGRAM_MAX_TEXT, callApi, editMessageText, sendMessage } from "./telegram-api.js";
 export { defaultErrorMessage };
@@ -120,7 +120,11 @@ export async function streamReply(events, api, botToken, target, formatError, pr
                 // below regardless.
                 finalized = true;
                 {
-                    const msg = formatError({ details: e.details, retryable: e.retryable }) ?? "";
+                    const msg = formatError({
+                        details: e.details,
+                        retryable: e.retryable,
+                        ...(e.code !== undefined ? { code: e.code } : {}),
+                    }) ?? "";
                     await finalize(api, botToken, target, messageId, msg).catch(() => { });
                 }
                 throw new Error(`agent failed: ${e.details} (retryable=${e.retryable})`);

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 "../../host/node.ts";
-import { type TelegramMessage, type TelegramRoute, type TelegramUpdate, defaultTelegramRoute, telegramEnvelope } from "./parse.ts";
+import type { ChannelModule } from "../../channel.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. */