@fastagent-sh/fastagent 0.29.0 → 0.30.1

package/dist/channels/telegram/setup.js

@@ -0,0 +1,42 @@
+/** What a Telegram bot's setup asks for (channels/setup.ts): its token from BotFather, and for a webhook a secret. */
+import { randomBytes } from "node:crypto";
+import { SetupRefused, pasteOne } from "../setup.js";
+import { TelegramApiError, callApi } from "./telegram-api.js";
+const TOKEN = /^\d+:[A-Za-z0-9_-]{30,}$/;
+export const telegramSetup = ({ way }) => ({
+    finish: () => [],
+    values: [
+        pasteOne({
+            name: "TELEGRAM_BOT_TOKEN",
+            label: "Bot token",
+            guide: {
+                instructions: "Message @BotFather, send /newbot, follow its questions, and copy the token it gives you.",
+                url: "https://t.me/BotFather",
+            },
+            async check(value) {
+                if (!TOKEN.test(value)) {
+                    throw new SetupRefused("That is not a bot token.", {
+                        fix: "BotFather's token looks like 123456789:AAH…, a number, a colon and a long string.",
+                    });
+                }
+                try {
+                    const me = await callApi("https://api.telegram.org", value, "getMe", {});
+                    return me.username ? `bot @${me.username}` : "bot";
+                }
+                catch (error) {
+                    if (error instanceof TelegramApiError && (error.status === 401 || error.status === 404)) {
+                        throw new SetupRefused("Telegram does not accept this token.", {
+                            fix: "Copy it again from BotFather (/mybots → the bot → API Token).",
+                            why: error.message,
+                        });
+                    }
+                    throw error;
+                }
+            },
+        }),
+        // Only a webhook has an inbound request to verify: a polling bot asks Telegram for its updates.
+        ...(way === "webhook"
+            ? [{ kind: "make", name: "TELEGRAM_SECRET_TOKEN", make: () => randomBytes(24).toString("hex") }]
+            : []),
+    ],
+});

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

@@ -1,5 +1,6 @@
 import type { ImageAttachment as ImageRef } from "../kit/invoke-turn-kit.ts";
 import type { CallOptions } from "../kit/transport.ts";
+import type { TelegramUpdate } from "./parse.ts";
 /** Telegram's hard text limit per message. */
 export declare const TELEGRAM_MAX_TEXT = 4096;
 /** Where a reply goes: a chat, optionally a thread (Threaded Mode), optionally replying to a message. */
@@ -41,6 +42,31 @@ interface Api {
         file_size?: number;
     };
     setWebhook: unknown;
+    deleteWebhook: unknown;
+    getWebhookInfo: {
+        url?: string;
+    };
+    getUpdates: TelegramUpdate[];
+}
+/** What a Telegram call may be told beyond the shared budget: a longer wait (a long poll) and a way to be cut short. */
+export interface TelegramCallOptions extends CallOptions {
+    /** Replaces the per-attempt timeout; a long poll must outlast the wait it asks Telegram for. */
+    readonly timeoutMs?: number;
+    /** Ends the call early, as a failure the caller reads as its own cancellation. */
+    readonly signal?: AbortSignal;
+}
+/** A named Bot API failure. `status` 0 = the transport itself failed (network error / timeout) before
+ *  any HTTP status existed; otherwise the HTTP status with Telegram's own description (or a note that
+ *  the body carried no usable answer). A typed class (not a plain Error) because callers tell failures apart:
+ *  sendMessage's parse-mode fallback, editMessageText's "not modified" swallow, and the long poll's reading of a
+ *  401 or a 409 — each does `instanceof` + reads `.status` / `.description`. */
+export declare class TelegramApiError extends Error {
+    readonly method: string;
+    readonly status: number;
+    readonly description: string;
+    constructor(method: string, status: number, description: string, options?: {
+        cause?: unknown;
+    });
 }
 /**
  * The pipeline: one Bot API call, carrying every transport invariant (see the module header). Returns
@@ -48,7 +74,7 @@ interface Api {
  */
 export declare function callApi<M extends keyof Api>(api: string, botToken: string, method: M, 
 /** JSON params, or a multipart form for an upload (a file's bytes; its own, longer timeout). */
-params: Record<string, unknown> | FormData, opts?: CallOptions): Promise<Api[M]>;
+params: Record<string, unknown> | FormData, opts?: TelegramCallOptions): Promise<Api[M]>;
 /**
  * Split text into ≤4096-char chunks (Telegram's limit), preferring a newline boundary. When `html`, it is
  * tag-aware: a tag that would SPAN a boundary is CLOSED at the chunk's end and REOPENED (attributes and

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

@@ -37,11 +37,10 @@ const RETRIES = 3;
 const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
 /** A named Bot API failure. `status` 0 = the transport itself failed (network error / timeout) before
  *  any HTTP status existed; otherwise the HTTP status with Telegram's own description (or a note that
- *  the body carried no usable answer). Module-private: no EXTERNAL caller matches on the type; it
- *  stays a typed class (not a plain Error) because this module's own retry logic — sendMessage's
- *  parse-mode fallback, editMessageText's "not modified" swallow — does `instanceof` + reads
- *  `.description`. */
-class TelegramApiError extends Error {
+ *  the body carried no usable answer). A typed class (not a plain Error) because callers tell failures apart:
+ *  sendMessage's parse-mode fallback, editMessageText's "not modified" swallow, and the long poll's reading of a
+ *  401 or a 409 — each does `instanceof` + reads `.status` / `.description`. */
+export class TelegramApiError extends Error {
     method;
     status;
     description;
@@ -57,6 +56,8 @@ class TelegramApiError extends Error {
         this.description = description;
     }
 }
+/** The per-attempt timeout, also ended by the caller's own signal when it gave one. */
+const withCancel = (timeout, cancel) => cancel === undefined ? timeout : AbortSignal.any([timeout, cancel]);
 /** Sleep on the GLOBAL timer (not `node:timers/promises`) so tests can drive it with fake timers. */
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
@@ -77,7 +78,7 @@ params, opts = {}) {
                 ...(upload
                     ? { body: params }
                     : { headers: { "content-type": "application/json" }, body: JSON.stringify(params) }),
-                signal: AbortSignal.timeout(upload ? DOWNLOAD_TIMEOUT_MS : API_TIMEOUT_MS),
+                signal: withCancel(AbortSignal.timeout(opts.timeoutMs ?? (upload ? DOWNLOAD_TIMEOUT_MS : API_TIMEOUT_MS)), opts.signal),
             });
             raw = await res.text(); // the body read shares the timeout — a mid-body stall is a transport failure too
         }

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

@@ -1,4 +1,4 @@
-import type { ChannelModule } from "../../channel.ts";
+import type { ChannelModule, LongConnectionChannelModule } 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, telegramStop };
@@ -17,5 +17,13 @@ export interface TelegramChannelOptions {
     /** Bot API base, for tests. */
     apiBaseUrl?: string;
 }
-/** Build a Telegram bot channel: policy options in, a {@link ChannelModule} out. */
-export declare function telegramChannel({ secretToken, botToken, route, onError, botUsername, apiBaseUrl, }: TelegramChannelOptions): ChannelModule;
+/** What a channel that polls is given: the webhook one's options without the secret that verifies a webhook. */
+export type TelegramPollingChannelOptions = Omit<TelegramChannelOptions, "secretToken">;
+/** Build a Telegram bot channel that receives by webhook: policy options in, a {@link ChannelModule} out. */
+export declare function telegramChannel(options: TelegramChannelOptions): ChannelModule;
+/**
+ * Build a Telegram bot channel that receives by long polling: the process asks Telegram for updates, so no public URL
+ * and no webhook secret are involved. It takes the webhook away from the bot first (`getUpdates` does not work while
+ * one is set), so a bot is polled by one process or reached by one webhook, never both.
+ */
+export declare function telegramPollingChannel(options: TelegramPollingChannelOptions): LongConnectionChannelModule;

package/dist/channels/telegram/telegram.js

@@ -19,109 +19,181 @@ import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
 import { createTurnRunner } from "../kit/turn-runner.js";
 import { discussionBlock } from "../kit/context-buffer.js";
 import { portJoin } from "../../effect-port.js";
+import { pollTelegramUpdates } from "./polling.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, telegramStop };
+const TELEGRAM_API = "https://api.telegram.org";
 /** Update body cap — Telegram updates are small JSON; 1 MiB is generous and guards a public endpoint. */
 const MAX_UPDATE_BYTES = 1 << 20;
-/** Build a Telegram bot channel: policy options in, a {@link ChannelModule} out. */
-export function telegramChannel({ secretToken, botToken, route, onError, botUsername, apiBaseUrl = "https://api.telegram.org", }) {
-    return ({ agent, sessionFor, recordedSession, stateDir: stateHome }) => {
-        // 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)");
+/** The channel's state and policy, over the context it is mounted in: everything but how updates arrive. */
+function createTelegramRuntime({ botToken, route, onError, botUsername, apiBaseUrl }, { agent, sessionFor, recordedSession, stateDir: stateHome }) {
+    // Validate at activation so deploy may inspect the module shape before secrets are provisioned.
+    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 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)
+            mentionName = me.username;
+        if (me.can_read_all_group_messages === false) {
+            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.");
         }
-        const formatError = onError ?? defaultErrorMessage;
-        // 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)
-                mentionName = me.username;
-            if (me.can_read_all_group_messages === false) {
-                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.");
+    }, 
+    // Name every capability the missing username costs, so "the bot ignores /stop@name" is diagnosable from this
+    // ONE line.
+    (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).
+    const tokenId = Number(botToken.split(":")[0]);
+    const botId = Number.isSafeInteger(tokenId) && tokenId > 0 ? tokenId : undefined;
+    if (botId === undefined) {
+        log.warn("[telegram] bot token has no parseable bot id — reply-to-bot summon disabled until getMe resolves");
+    }
+    const decide = route ?? ((update) => defaultTelegramRoute(update, { botUsername: mentionName, botId }));
+    const buffer = createContextBuffer(join(stateHome, "buffers.json"));
+    // The send tool rides this channel's token, and what it sends lands in this buffer (shared-api.ts says why).
+    registerTelegramTransport({
+        apiBaseUrl,
+        botToken,
+        record: (placeKey, entry) => buffer.push(placeKey, entry),
+    });
+    // Durable turn intent (L1): persist an accepted turn pre-ACK, remove it when the turn ends; a crash leaves it for
+    // replay on the next start.
+    const store = createTurnStore(join(stateHome, "turns.json"));
+    const sideTasks = createTaskTracker("[telegram]");
+    const targetOf = (r) => ({ chatId: r.chatId, threadId: r.threadId, replyTo: r.replyTo });
+    // Tell the asker when a turn is dropped at the execution ceiling: the chain's end needs a signal, not just an
+    // operator log line.
+    const notifyDropped = (r) => {
+        const body = "⚠️ I couldn’t complete an earlier request — please ask again.";
+        const sent = r.previewId !== undefined
+            ? editMessageText(apiBaseUrl, botToken, targetOf(r), r.previewId, body, { html: false })
+            : sendMessage(apiBaseUrl, botToken, targetOf(r), body, { html: false }).then(() => { });
+        void sent.catch((e) => log.warn(`[telegram] could not notify a dropped turn (conversation=${r.conversation}): ${String(e)}`));
+    };
+    const runner = createTurnRunner({
+        label: "[telegram]",
+        store,
+        discussion: buffer,
+        toStored: ({ previewId: _live, ...intent }) => ({ ...intent, attempts: 0 }),
+        fromStored: ({ attempts: _a, ...intent }) => ({ ...intent, previewId: undefined }),
+        discussionKey: (rec) => rec.placeKey,
+        where: (rec) => `chat=${rec.chatId}${rec.threadId !== undefined ? ` thread=${rec.threadId}` : ""}`,
+        // Queue feedback: when this session already has a turn running/queued, a silent wait reads as "the bot ignored
+        // me" once the current turn runs long.
+        onQueuedBehind: (rec) => ({
+            done: sendMessage(apiBaseUrl, botToken, targetOf(rec), "⏳ Queued — I’ll start once the current task finishes.", {
+                html: false,
+            }).then((id) => {
+                if (id !== undefined)
+                    rec.previewId = id;
+            }, (e) => log.warn(`[telegram] queue notice failed (the turn still runs): ${String(e)}`)),
+        }),
+        // Its ⏳ notice (if any) now falsely reads "Queued": delete it best-effort.
+        onDeferred: (rec) => {
+            if (rec.previewId !== undefined) {
+                void callApi(apiBaseUrl, botToken, "deleteMessage", {
+                    chat_id: rec.chatId,
+                    message_id: rec.previewId,
+                }).catch(() => { });
             }
-        }, 
-        // Name every capability the missing username costs, so "the bot ignores /stop@name" is diagnosable from this
-        // ONE line.
-        (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).
-        const tokenId = Number(botToken.split(":")[0]);
-        const botId = Number.isSafeInteger(tokenId) && tokenId > 0 ? tokenId : undefined;
-        if (botId === undefined) {
-            log.warn("[telegram] bot token has no parseable bot id — reply-to-bot summon disabled until getMe resolves");
-        }
-        const decide = route ?? ((update) => defaultTelegramRoute(update, { botUsername: mentionName, botId }));
-        const buffer = createContextBuffer(join(stateHome, "buffers.json"));
-        // The send tool rides this channel's token, and what it sends lands in this buffer (shared-api.ts says why).
-        registerTelegramTransport({
-            apiBaseUrl,
-            botToken,
-            record: (placeKey, entry) => buffer.push(placeKey, entry),
-        });
-        // Durable turn intent (L1): persist an accepted turn pre-ACK, remove it when the turn ends; a crash leaves it for
-        // replay on the next start.
-        const store = createTurnStore(join(stateHome, "turns.json"));
-        const sideTasks = createTaskTracker("[telegram]");
-        const targetOf = (r) => ({ chatId: r.chatId, threadId: r.threadId, replyTo: r.replyTo });
-        // Tell the asker when a turn is dropped at the execution ceiling: the chain's end needs a signal, not just an
-        // operator log line.
-        const notifyDropped = (r) => {
-            const body = "⚠️ I couldn’t complete an earlier request — please ask again.";
-            const sent = r.previewId !== undefined
-                ? editMessageText(apiBaseUrl, botToken, targetOf(r), r.previewId, body, { html: false })
-                : sendMessage(apiBaseUrl, botToken, targetOf(r), body, { html: false }).then(() => { });
-            void sent.catch((e) => log.warn(`[telegram] could not notify a dropped turn (conversation=${r.conversation}): ${String(e)}`));
-        };
-        const runner = createTurnRunner({
-            label: "[telegram]",
-            store,
-            discussion: buffer,
-            toStored: ({ previewId: _live, ...intent }) => ({ ...intent, attempts: 0 }),
-            fromStored: ({ attempts: _a, ...intent }) => ({ ...intent, previewId: undefined }),
-            discussionKey: (rec) => rec.placeKey,
-            where: (rec) => `chat=${rec.chatId}${rec.threadId !== undefined ? ` thread=${rec.threadId}` : ""}`,
-            // Queue feedback: when this session already has a turn running/queued, a silent wait reads as "the bot ignored
-            // me" once the current turn runs long.
-            onQueuedBehind: (rec) => ({
-                done: sendMessage(apiBaseUrl, botToken, targetOf(rec), "⏳ Queued — I’ll start once the current task finishes.", {
-                    html: false,
-                }).then((id) => {
-                    if (id !== undefined)
-                        rec.previewId = id;
-                }, (e) => log.warn(`[telegram] queue notice failed (the turn still runs): ${String(e)}`)),
+        },
+        notifyDropped,
+        // `rec.previewId`: the ⏳ notice THIS process put up if the record waited behind another turn.
+        deliverAnswer: (rec, answer) => portJoin(() => deliverTelegramAnswer(apiBaseUrl, botToken, targetOf(rec), answer, rec.previewId)),
+        execute: (rec, discussion, onAnswered) => telegramReply(telegramTurnStream(agent, {
+            session: () => sessionFor(rec.conversation),
+            key: rec.id,
+            text: `${discussionBlock(discussion.text)}${rec.baseText}`,
+        }, { api: apiBaseUrl, botToken, chatId: rec.chatId, filesDir: attachmentsDir(stateHome) }, {
+            primary: { imageFileIds: rec.imageFileIds, fileIds: rec.fileIds },
+            buffered: collectAttachments(discussion.consumed, {
+                files: new Set(rec.fileIds),
+                images: new Set(rec.imageFileIds),
             }),
-            // Its ⏳ notice (if any) now falsely reads "Queued": delete it best-effort.
-            onDeferred: (rec) => {
-                if (rec.previewId !== undefined) {
-                    void callApi(apiBaseUrl, botToken, "deleteMessage", {
-                        chat_id: rec.chatId,
-                        message_id: rec.previewId,
-                    }).catch(() => { });
-                }
-            },
-            notifyDropped,
-            // `rec.previewId`: the ⏳ notice THIS process put up if the record waited behind another turn.
-            deliverAnswer: (rec, answer) => portJoin(() => deliverTelegramAnswer(apiBaseUrl, botToken, targetOf(rec), answer, rec.previewId)),
-            execute: (rec, discussion, onAnswered) => telegramReply(telegramTurnStream(agent, {
-                session: () => sessionFor(rec.conversation),
-                key: rec.id,
-                text: `${discussionBlock(discussion.text)}${rec.baseText}`,
-            }, { api: apiBaseUrl, botToken, chatId: rec.chatId, filesDir: attachmentsDir(stateHome) }, {
-                primary: { imageFileIds: rec.imageFileIds, fileIds: rec.fileIds },
-                buffered: collectAttachments(discussion.consumed, {
-                    files: new Set(rec.fileIds),
-                    images: new Set(rec.imageFileIds),
-                }),
-            }), apiBaseUrl, botToken, targetOf(rec), formatError, rec.previewId, onAnswered),
-        });
-        runner.recover();
+        }), apiBaseUrl, botToken, targetOf(rec), formatError, rec.previewId, onAnswered),
+    });
+    runner.recover();
+    const accept = (update) => {
+        // Decide whether/where to answer, then run the turn.
+        const m = pickMessage(update);
+        if (!m)
+            return;
+        const placeKey = telegramPlaceKey(m.chat.id, m.message_thread_id);
+        const r = decide(update);
+        if (!r) {
+            // Not summoned: in a group, record the message so a later summon has the discussion (needs privacy off to be
+            // delivered here at all).
+            const isGroup = m.chat.type === "group" || m.chat.type === "supergroup";
+            const content = messageText(m);
+            if (isGroup && content) {
+                // OWN attachments only: each message is its own buffer entry, so a reply's referenced attachment is already
+                // (or will be) the other entry's.
+                const fileIds = ownFiles(m);
+                const imageIds = ownImages(m);
+                // A captioned attachment renders as its caption.
+                const summary = attachmentSummary(m);
+                const bodyLine = summary && content !== summary ? `${content} ${summary}` : content;
+                buffer.push(placeKey, {
+                    sender: fromLabel(m.from) ?? "someone",
+                    body: bodyLine,
+                    messageId: m.message_id,
+                    replyTo: m.reply_to_message?.message_id,
+                    fileIds: fileIds.length ? fileIds : undefined,
+                    imageIds: imageIds.length ? imageIds : undefined,
+                });
+            }
+            return;
+        }
+        const conversation = r.conversation ?? 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.
+        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.
+        // `abort` waits until what it stopped has ended, so the update is acknowledged first.
+        if (telegramStop(update, { botUsername: mentionName, botId })) {
+            sideTasks.track(dispatchStop(agent, recordedSession(conversation), "[telegram]")
+                .then((feedback) => sendMessage(apiBaseUrl, botToken, { chatId, threadId, replyTo }, feedback, { html: false }))
+                .catch((e) => log.warn(`[telegram] stop feedback failed: ${String(e)}`)));
+            return;
+        }
+        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.
+            runner.submit({
+                id: `${update.update_id}`,
+                conversation,
+                placeKey,
+                baseText,
+                chatId,
+                threadId,
+                replyTo,
+                imageFileIds,
+                fileIds,
+            }, true);
+        }
+        return;
+    };
+    return { accept, turnsIdle: () => runner.idle() };
+}
+/** Build a Telegram bot channel that receives by webhook: policy options in, a {@link ChannelModule} out. */
+export function telegramChannel(options) {
+    const { secretToken, apiBaseUrl = TELEGRAM_API } = options;
+    return (ctx) => {
+        if (!secretToken) {
+            throw new Error("telegramChannel requires a non-empty secretToken (the webhook secret_token; an unset one accepts forged updates)");
+        }
+        const runtime = createTelegramRuntime({ ...options, apiBaseUrl }, ctx);
         const handler = async (req) => {
             if (req.method !== "POST")
                 return text("POST only\n", 405);
@@ -139,71 +211,26 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             catch {
                 return text("invalid json\n", 400);
             }
-            // Decide whether/where to answer, then run the turn.
-            const m = pickMessage(update);
-            if (!m)
-                return new Response(null, { status: 200 });
-            const placeKey = telegramPlaceKey(m.chat.id, m.message_thread_id);
-            const r = decide(update);
-            if (!r) {
-                // Not summoned: in a group, record the message so a later summon has the discussion (needs privacy off to be
-                // delivered here at all).
-                const isGroup = m.chat.type === "group" || m.chat.type === "supergroup";
-                const content = messageText(m);
-                if (isGroup && content) {
-                    // OWN attachments only: each message is its own buffer entry, so a reply's referenced attachment is already
-                    // (or will be) the other entry's.
-                    const fileIds = ownFiles(m);
-                    const imageIds = ownImages(m);
-                    // A captioned attachment renders as its caption.
-                    const summary = attachmentSummary(m);
-                    const bodyLine = summary && content !== summary ? `${content} ${summary}` : content;
-                    buffer.push(placeKey, {
-                        sender: fromLabel(m.from) ?? "someone",
-                        body: bodyLine,
-                        messageId: m.message_id,
-                        replyTo: m.reply_to_message?.message_id,
-                        fileIds: fileIds.length ? fileIds : undefined,
-                        imageIds: imageIds.length ? imageIds : undefined,
-                    });
-                }
-                return new Response(null, { status: 200 });
-            }
-            const conversation = r.conversation ?? 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.
-            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.
-            // `abort` waits until what it stopped has ended, so the update is acknowledged first.
-            if (telegramStop(update, { botUsername: mentionName, botId })) {
-                sideTasks.track(dispatchStop(agent, recordedSession(conversation), "[telegram]")
-                    .then((feedback) => 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.
-                runner.submit({
-                    id: `${update.update_id}`,
-                    conversation,
-                    placeKey,
-                    baseText,
-                    chatId,
-                    threadId,
-                    replyTo,
-                    imageFileIds,
-                    fileIds,
-                }, true);
-            }
+            runtime.accept(update);
             return new Response(null, { status: 200 });
         };
         // Test/observability seam: await the fire-and-forget turns this handler enqueues.
-        handler.turnsIdle = () => runner.idle();
+        handler.turnsIdle = runtime.turnsIdle;
         return { "POST /telegram": handler };
     };
 }
+/**
+ * Build a Telegram bot channel that receives by long polling: the process asks Telegram for updates, so no public URL
+ * and no webhook secret are involved. It takes the webhook away from the bot first (`getUpdates` does not work while
+ * one is set), so a bot is polled by one process or reached by one webhook, never both.
+ */
+export function telegramPollingChannel(options) {
+    const apiBaseUrl = options.apiBaseUrl ?? TELEGRAM_API;
+    return {
+        name: "telegram long polling",
+        connect(ctx, signal) {
+            const runtime = createTelegramRuntime({ ...options, apiBaseUrl }, ctx);
+            return pollTelegramUpdates({ apiBaseUrl, botToken: options.botToken, accept: runtime.accept }, signal);
+        },
+    };
+}

package/dist/channels/webhook-evidence.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether `address` is `<publicUrl><path>`: the scheme, the host and the channel's own path. A mount prefix is
+ * `publicUrl`'s, since an embedding app's router may strip it before the channel sees the request.
+ */
+export declare function addressedTo(address: string, publicUrl: string, path: string): boolean;
+/** Record that an authenticated request from the platform reached the channel whose state is `stateDir`. */
+export declare function recordReached(stateDir: string, request: Request): void;
+/** The address an authenticated request last reached the channel at, as recorded, if any. */
+export declare function readReached(stateDir: string): string | undefined;
+/** Hear each address recorded for `stateDir` from now on; the answer stops it. */
+export declare function onReached(stateDir: string, listener: (address: string) => void): () => void;

package/dist/channels/webhook-evidence.js

@@ -0,0 +1,71 @@
+/**
+ * What proves a platform reaches this instance at a URL only a person sets (Slack's Request URL; Lark's where its
+ * configuration API is missing): an authenticated request from it, and the address it was sent to (SPEC.md §8,
+ * channel-setup.md §5). A platform's signature or token proves who sent a request, not where, so the address is read
+ * from the request's host and forwarding headers. The first-party channel records it, durable in its own state
+ * directory, and a serve in this process hears it at once.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../atomic-write.js";
+import { log } from "../log.js";
+const EVIDENCE_FILE = "reached.json";
+/** Where the request was sent: its scheme, host and path, as the proxy in front of the server says it received them. */
+function requestAddress(request) {
+    const url = new URL(request.url);
+    const first = (value) => value?.split(",")[0]?.trim() || undefined;
+    const scheme = first(request.headers.get("x-forwarded-proto")) ?? url.protocol.replace(/:$/, "");
+    const host = first(request.headers.get("x-forwarded-host")) ?? request.headers.get("host") ?? url.host;
+    return `${scheme}://${host}${url.pathname}`;
+}
+/**
+ * Whether `address` is `<publicUrl><path>`: the scheme, the host and the channel's own path. A mount prefix is
+ * `publicUrl`'s, since an embedding app's router may strip it before the channel sees the request.
+ */
+export function addressedTo(address, publicUrl, path) {
+    const reached = new URL(address);
+    const expected = new URL(publicUrl);
+    return reached.protocol === expected.protocol && reached.host === expected.host && reached.pathname.endsWith(path);
+}
+const listeners = new Map();
+const recorded = new Map();
+/** Record that an authenticated request from the platform reached the channel whose state is `stateDir`. */
+export function recordReached(stateDir, request) {
+    const address = requestAddress(request);
+    if (recorded.get(stateDir) === address)
+        return;
+    recorded.set(stateDir, address);
+    try {
+        writeFileAtomic(join(stateDir, EVIDENCE_FILE), `${JSON.stringify({ address, at: new Date().toISOString() })}\n`);
+    }
+    catch (error) {
+        // The request is answered either way; a record not kept costs a `manual` after the next restart, said here.
+        log.warn(`[fastagent] could not record that ${address} was reached: ${String(error)}`);
+    }
+    for (const listener of listeners.get(stateDir) ?? [])
+        listener(address);
+}
+/** The address an authenticated request last reached the channel at, as recorded, if any. */
+export function readReached(stateDir) {
+    try {
+        const { address } = JSON.parse(readFileSync(join(stateDir, EVIDENCE_FILE), "utf8"));
+        return typeof address === "string" ? address : undefined;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        log.warn(`[fastagent] could not read ${join(stateDir, EVIDENCE_FILE)}: ${String(error)}`);
+        return undefined;
+    }
+}
+/** Hear each address recorded for `stateDir` from now on; the answer stops it. */
+export function onReached(stateDir, listener) {
+    const set = listeners.get(stateDir) ?? new Set();
+    set.add(listener);
+    listeners.set(stateDir, set);
+    return () => {
+        set.delete(listener);
+        if (set.size === 0)
+            listeners.delete(stateDir);
+    };
+}