@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/channels/slack/socket.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Slack Socket Mode: how an app receives with no public URL. `apps.connections.open` (the app-level token) gives a
+ * short-lived `wss://` address; Slack sends `hello`, then every event as an envelope that must be acknowledged by its
+ * `envelope_id` within three seconds or Slack sends it again. Connections are refreshed every few hours: Slack says so
+ * with a `disconnect` (a `warning` about ten seconds ahead, then `refresh_requested`), and the app opens the next
+ * connection BEFORE the old one goes, so no event falls between them.
+ *
+ * What ends the connection and what does not follows what can be done about it. Before the first `hello`, any failure
+ * ends it: a start that cannot reach Slack, or is refused, is the operator's to see. After it, a lost socket, a
+ * refused `apps.connections.open` that can pass (rate limit, an outage) or a connection that stops answering pings is
+ * retried with a growing wait; a refused token and Socket Mode turned off for the app (`link_disabled`) end it with their
+ * reason, because retrying cannot fix them.
+ */
+import type { LongConnection } from "../../channel.ts";
+import type { SlackEventEnvelope } from "./parse.ts";
+/** The socket as this module uses it, so a test can stand in a fake and a runtime without pings still serves. */
+interface SlackSocket {
+    send(data: string): void;
+    close(): void;
+    /** Sends a ping frame, when the runtime can; its pong arrives as `handlers.pong`. */
+    ping?(): void;
+}
+export interface SlackSocketHandlers {
+    message(data: string): void;
+    pong(): void;
+    /** The socket ended, or could not be opened; `reason` says how. */
+    close(reason: string): void;
+}
+export type OpenSlackSocket = (url: string, handlers: SlackSocketHandlers) => SlackSocket;
+export interface SlackSocketOptions {
+    apiBaseUrl: string;
+    /** The app-level token (`xapp-…`). */
+    appToken: string;
+    /** Take an `event_callback` durably; a rejection leaves its envelope unacknowledged, so Slack sends it again. */
+    ingest(envelope: SlackEventEnvelope): Promise<void>;
+    /** Replaces the WebSocket and the waits, for tests. */
+    openSocket?: OpenSlackSocket;
+    timing?: {
+        retryFirstMs?: number;
+        retryCapMs?: number;
+        helloMs?: number;
+        pingEveryMs?: number;
+        pongWithinMs?: number;
+    };
+}
+/** A failure no retry can fix: the connection ends with it. */
+export declare class TerminalSocketError extends Error {
+}
+/**
+ * `apps.connections.open`: the address a connection is dialled at. A refusal that names the token (see
+ * {@link TERMINAL_OPEN_ERRORS}) is a {@link TerminalSocketError}; one that can pass (a rate limit, an outage) and an
+ * unreachable Slack are plain errors.
+ */
+export declare function openSlackConnection(apiBaseUrl: string, appToken: string, signal?: AbortSignal): Promise<string>;
+/** Hold a Socket Mode connection until `signal` aborts; `ready` settles at the first `hello`. */
+export declare function connectSlackSocket(options: SlackSocketOptions, signal: AbortSignal): LongConnection;
+export {};

package/dist/channels/slack/socket.js

@@ -0,0 +1,305 @@
+import { RuntimeWebSocket, pinger, watchPongs } from "../../runtime-websocket.js";
+import { log } from "../../log.js";
+import { pause, whenAborted } from "../kit/abortable.js";
+const RETRY_FIRST_MS = 1_000;
+const RETRY_CAP_MS = 30_000;
+/** How long a new connection may take to say `hello`. */
+const HELLO_MS = 15_000;
+/** A socket that stays silent is asked, with a ping, whether it is there: how often, and how long to wait for the pong. */
+const PING_EVERY_MS = 30_000;
+const PONG_WITHIN_MS = 10_000;
+/** What `apps.connections.open` says when the token is the problem: no retry will fix these. */
+const TERMINAL_OPEN_ERRORS = new Set([
+    "invalid_auth",
+    "not_authed",
+    "token_revoked",
+    "token_expired",
+    "account_inactive",
+    "not_allowed_token_type",
+    "missing_scope",
+    "no_permission",
+]);
+/** The runtime's own WebSocket, with the pings it can send; a runtime that offers none serves without them. */
+const openRuntimeSocket = (url, handlers) => {
+    const socket = new RuntimeWebSocket(url);
+    const stopPongs = watchPongs(socket, () => handlers.pong());
+    const ping = pinger(socket);
+    let closed = false;
+    const end = (reason) => {
+        if (closed)
+            return;
+        closed = true;
+        stopPongs();
+        handlers.close(reason);
+    };
+    socket.addEventListener("message", (event) => handlers.message(String(event.data)));
+    socket.addEventListener("error", (event) => end(`socket error${event.message ? `: ${event.message}` : ""}`));
+    socket.addEventListener("close", (event) => end(`closed (${event.code}${event.reason ? ` ${event.reason}` : ""})`));
+    return {
+        send: (data) => socket.send(data),
+        close: () => socket.close(),
+        ...(ping ? { ping } : {}),
+    };
+};
+/** A failure no retry can fix: the connection ends with it. */
+export class TerminalSocketError extends Error {
+}
+/**
+ * `apps.connections.open`: the address a connection is dialled at. A refusal that names the token (see
+ * {@link TERMINAL_OPEN_ERRORS}) is a {@link TerminalSocketError}; one that can pass (a rate limit, an outage) and an
+ * unreachable Slack are plain errors.
+ */
+export async function openSlackConnection(apiBaseUrl, appToken, signal) {
+    let response;
+    try {
+        response = await fetch(`${apiBaseUrl}/apps.connections.open`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${appToken}`, "content-type": "application/x-www-form-urlencoded" },
+            signal: AbortSignal.any([AbortSignal.timeout(15_000), ...(signal ? [signal] : [])]),
+        });
+    }
+    catch (error) {
+        throw new Error(`apps.connections.open could not be reached: ${String(error)}`, { cause: error });
+    }
+    const body = (await response.json().catch(() => ({})));
+    if (body.ok === true && typeof body.url === "string")
+        return body.url;
+    const reason = body.error ?? `HTTP ${response.status}`;
+    const message = `apps.connections.open failed: ${reason}`;
+    throw TERMINAL_OPEN_ERRORS.has(reason) ? new TerminalSocketError(message) : new Error(message);
+}
+/** Hold a Socket Mode connection until `signal` aborts; `ready` settles at the first `hello`. */
+export function connectSlackSocket(options, signal) {
+    const { apiBaseUrl, appToken, ingest } = options;
+    const openSocket = options.openSocket ?? openRuntimeSocket;
+    const retryFirstMs = options.timing?.retryFirstMs ?? RETRY_FIRST_MS;
+    const retryCapMs = options.timing?.retryCapMs ?? RETRY_CAP_MS;
+    const helloMs = options.timing?.helloMs ?? HELLO_MS;
+    const pingEveryMs = options.timing?.pingEveryMs ?? PING_EVERY_MS;
+    const pongWithinMs = options.timing?.pongWithinMs ?? PONG_WITHIN_MS;
+    const ready = Promise.withResolvers();
+    const closed = Promise.withResolvers();
+    let isReady = false;
+    const markReady = () => {
+        if (isReady)
+            return;
+        isReady = true;
+        ready.resolve();
+    };
+    const openUrl = () => openSlackConnection(apiBaseUrl, appToken, signal);
+    /** Acknowledge each event once it is taken; an event that cannot be taken is left for Slack to send again. */
+    const handleEnvelope = async (socket, envelope) => {
+        const id = envelope.envelope_id;
+        if (typeof id !== "string")
+            return;
+        if (envelope.type === "events_api") {
+            const payload = envelope.payload;
+            if (payload?.type === "event_callback") {
+                try {
+                    await ingest(payload);
+                }
+                catch (error) {
+                    log.error(`[slack] an event was not taken, so it is not acknowledged and Slack will send it again: ${String(error)}`);
+                    return;
+                }
+            }
+        }
+        else {
+            // Interactivity and slash commands are not what this channel serves: acknowledged, so Slack does not resend them.
+            log.debug(`[slack] ignoring a Socket Mode "${String(envelope.type)}" envelope`);
+        }
+        try {
+            socket.send(JSON.stringify({ envelope_id: id }));
+        }
+        catch (error) {
+            // The connection went while the event was taken (a refresh closes the old one): Slack sends it again, and the
+            // delivery ring in the channel recognises it.
+            log.debug(`[slack] could not acknowledge an event on a closed connection: ${String(error)}`);
+        }
+    };
+    /** Dial `url` and resolve at its `hello`; the connection then answers events until it ends. */
+    const dial = (url) => new Promise((resolve, reject) => {
+        const ended = Promise.withResolvers();
+        let outcome;
+        let helloed = false;
+        let pingTimer;
+        let pongTimer;
+        const stop = () => {
+            clearTimeout(pingTimer);
+            clearTimeout(pongTimer);
+        };
+        const finish = (value) => {
+            if (outcome !== undefined)
+                return;
+            outcome = value;
+            stop();
+            ended.resolve(value);
+        };
+        const fail = (error) => {
+            stop();
+            stopWatching();
+            socket.close();
+            if (!helloed)
+                reject(error);
+            else if (error instanceof TerminalSocketError) {
+                // Only the connection still in service ends the channel with it: one already let go has nothing to tell.
+                if (outcome === undefined) {
+                    outcome = "lost";
+                    ended.reject(error);
+                }
+            }
+            else
+                finish("lost");
+        };
+        const helloTimer = setTimeout(() => fail(new Error(`no hello from Slack within ${helloMs / 1000}s`)), helloMs);
+        // Until it says hello, the connection is only a socket being opened: an abort ends it at once, and `run` reads
+        // the rejection as the cancellation it is.
+        const stopWatching = whenAborted(signal, () => {
+            clearTimeout(helloTimer);
+            fail(new Error("cancelled"));
+        });
+        const ping = () => {
+            if (socket.ping === undefined)
+                return;
+            pingTimer = setTimeout(() => {
+                socket.ping?.();
+                pongTimer = setTimeout(() => {
+                    log.warn(`[slack] Socket Mode connection stopped answering pings; reconnecting`);
+                    fail(new Error("no pong"));
+                }, pongWithinMs);
+            }, pingEveryMs);
+        };
+        const socket = openSocket(url, {
+            message: (data) => {
+                let envelope;
+                try {
+                    envelope = JSON.parse(data);
+                }
+                catch {
+                    log.warn("[slack] ignoring a Socket Mode message that is not JSON");
+                    return;
+                }
+                if (envelope.type === "hello") {
+                    clearTimeout(helloTimer);
+                    stopWatching();
+                    helloed = true;
+                    ping();
+                    const info = envelope.connection_info;
+                    resolve({
+                        socket,
+                        hello: {
+                            ...(typeof info?.app_id === "string" ? { appId: info.app_id } : {}),
+                            ...(typeof envelope.num_connections === "number" ? { connections: envelope.num_connections } : {}),
+                        },
+                        ended: ended.promise,
+                        close: () => {
+                            finish("lost");
+                            socket.close();
+                        },
+                    });
+                }
+                else if (envelope.type === "disconnect") {
+                    const reason = String(envelope.reason);
+                    if (reason === "link_disabled") {
+                        fail(new TerminalSocketError("Slack Socket Mode is turned off for this app (link_disabled)"));
+                    }
+                    else if (reason === "warning" || reason === "refresh_requested") {
+                        finish("refresh");
+                    }
+                    else {
+                        log.warn(`[slack] Slack asked this Socket Mode connection to go (${reason})`);
+                        finish("lost");
+                    }
+                }
+                else {
+                    void handleEnvelope(socket, envelope);
+                }
+            },
+            pong: () => {
+                clearTimeout(pongTimer);
+                clearTimeout(pingTimer);
+                ping();
+            },
+            close: (reason) => {
+                clearTimeout(helloTimer);
+                stopWatching();
+                fail(new Error(`Socket Mode connection ${reason}`));
+            },
+        });
+    });
+    /**
+     * Slack answers `apps.connections.open` and says `hello` whether or not Socket Mode is on for the app, and sends
+     * events only while it is, so a connection that is "ready" can be deaf with nothing to say so. The first `hello` is
+     * where to say which app this is and what it depends on. Slack also splits an app's events among its connections, so
+     * another one open at the start (another process, another developer) takes some of them.
+     */
+    const announce = ({ appId, connections }) => {
+        log.info(`[slack] Socket Mode connected${appId ? ` to app ${appId}` : ""}; events arrive only while Socket Mode is on in ` +
+            "the app's settings");
+        if (connections !== undefined && connections > 1) {
+            log.warn(`[slack] ${connections} connections are open for this app, and Slack splits its events between them: ` +
+                "another process uses the same app-level token, so this one will miss some messages");
+        }
+    };
+    const run = async () => {
+        let current;
+        let waitMs = retryFirstMs;
+        try {
+            while (!signal.aborted) {
+                let next;
+                try {
+                    next = await dial(await openUrl());
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        break;
+                    if (error instanceof TerminalSocketError || !isReady)
+                        throw error;
+                    log.warn(`[slack] Socket Mode connection failed, retrying in ${waitMs / 1000}s: ${String(error)}`);
+                    await pause(waitMs, signal);
+                    waitMs = Math.min(waitMs * 2, retryCapMs);
+                    continue;
+                }
+                // Both receive until the old one is let go, so an event sent in between is taken by one of them.
+                current?.close();
+                current = next;
+                waitMs = retryFirstMs;
+                if (!isReady)
+                    announce(next.hello);
+                markReady();
+                const outcome = await new Promise((resolve, reject) => {
+                    const stopWatching = whenAborted(signal, () => resolve("lost"));
+                    next.ended.then((value) => {
+                        stopWatching();
+                        resolve(value);
+                    }, (error) => {
+                        stopWatching();
+                        reject(error);
+                    });
+                });
+                if (signal.aborted)
+                    break;
+                if (outcome === "lost") {
+                    current = undefined;
+                    await pause(retryFirstMs, signal);
+                }
+            }
+        }
+        finally {
+            // However it ends, including with a failure no retry can fix: a channel that has ended takes no more events.
+            current?.close();
+        }
+    };
+    run().then(() => {
+        markReady();
+        closed.resolve();
+    }, (error) => {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        if (!isReady) {
+            isReady = true;
+            ready.reject(failure);
+        }
+        closed.reject(failure);
+    });
+    return { ready: ready.promise, closed: closed.promise };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Telegram long polling: how a bot receives with no public URL. The process asks `getUpdates` for what is new, hands
+ * each update to the channel, and confirms it by asking again past its id (Telegram holds what is not confirmed).
+ *
+ * Failures are told apart by what can be done about them. Before the first answer, anything but a conflict ends the
+ * connection: a start that cannot reach Telegram or is refused by it is the operator's to see. After it, a lost network
+ * or a 5xx is weather and is retried with a growing wait, while a refused token, a webhook someone set under the poll,
+ * and a second process polling the same bot end the connection with their reason, because retrying cannot fix them (and
+ * the last would only take turns with the other process).
+ */
+import type { LongConnection } from "../../channel.ts";
+import type { TelegramUpdate } from "./parse.ts";
+export interface TelegramPollingOptions {
+    apiBaseUrl: string;
+    botToken: string;
+    /** The channel's `accept`: durable before it returns, a throw means the update was not taken. */
+    accept(update: TelegramUpdate): void;
+    /** Waits in milliseconds, for tests. */
+    timing?: {
+        longPollS?: number;
+        retryFirstMs?: number;
+        retryCapMs?: number;
+        conflictWaitMs?: number;
+    };
+}
+/** Poll until `signal` aborts; `ready` settles after the first answer, `closed` when the poll ends or cannot go on. */
+export declare function pollTelegramUpdates(options: TelegramPollingOptions, signal: AbortSignal): LongConnection;

package/dist/channels/telegram/polling.js

@@ -0,0 +1,105 @@
+import { log } from "../../log.js";
+import { pause } from "../kit/abortable.js";
+import { TelegramApiError, callApi } from "./telegram-api.js";
+/** How long Telegram may hold a poll open with nothing to say. */
+const LONG_POLL_S = 30;
+/** Retry waits for a failure that can pass: doubling from the first, never past the last. */
+const RETRY_FIRST_MS = 1_000;
+const RETRY_CAP_MS = 30_000;
+/** A 409 from another process polling this bot: how often to ask again, and how many answers before giving up. */
+const CONFLICT_WAIT_MS = 5_000;
+const CONFLICT_RETRIES = 3;
+const isApiError = (error) => error instanceof TelegramApiError;
+/** Poll until `signal` aborts; `ready` settles after the first answer, `closed` when the poll ends or cannot go on. */
+export function pollTelegramUpdates(options, signal) {
+    const { apiBaseUrl, botToken, accept } = options;
+    const longPollS = options.timing?.longPollS ?? LONG_POLL_S;
+    const retryFirstMs = options.timing?.retryFirstMs ?? RETRY_FIRST_MS;
+    const retryCapMs = options.timing?.retryCapMs ?? RETRY_CAP_MS;
+    const conflictWaitMs = options.timing?.conflictWaitMs ?? CONFLICT_WAIT_MS;
+    const ready = Promise.withResolvers();
+    const closed = Promise.withResolvers();
+    let isReady = false;
+    const markReady = () => {
+        if (isReady)
+            return;
+        isReady = true;
+        ready.resolve();
+    };
+    /** `getUpdates` does not work while a webhook is set, so a bot that polls is a bot with none. */
+    const takeWebhookAway = async () => {
+        const info = await callApi(apiBaseUrl, botToken, "getWebhookInfo", {}, { signal });
+        if (!info.url)
+            return;
+        await callApi(apiBaseUrl, botToken, "deleteWebhook", {}, { signal });
+        log.info(`[telegram] deleted the bot's webhook (${info.url}) so it can receive by long polling`);
+    };
+    const run = async () => {
+        await takeWebhookAway();
+        let offset;
+        let waitMs = retryFirstMs;
+        let conflicts = 0;
+        while (!signal.aborted) {
+            let updates;
+            try {
+                updates = await callApi(apiBaseUrl, botToken, "getUpdates", 
+                // The first call answers at once: readiness is "Telegram accepts this token and nobody else polls", which a
+                // poll held open for a quiet bot could not say for half a minute.
+                { ...(offset === undefined ? {} : { offset }), timeout: isReady ? longPollS : 0 }, { retries: 0, timeoutMs: (longPollS + 15) * 1000, signal });
+            }
+            catch (error) {
+                if (signal.aborted)
+                    break;
+                if (isApiError(error) && error.status === 409) {
+                    if (/webhook/i.test(error.description)) {
+                        throw new Error(`a webhook was set for this bot while it polls, so another instance receives by webhook (${error.description})`);
+                    }
+                    if (++conflicts > CONFLICT_RETRIES) {
+                        throw new Error(`another process polls this bot (${error.description})`);
+                    }
+                    log.warn(`[telegram] another process is polling this bot; asking again in ${conflictWaitMs / 1000}s (${conflicts}/${CONFLICT_RETRIES})`);
+                    await pause(conflictWaitMs, signal);
+                    continue;
+                }
+                if (!isReady || (isApiError(error) && (error.status === 401 || error.status === 403 || error.status === 404))) {
+                    throw error;
+                }
+                log.warn(`[telegram] getUpdates failed, retrying in ${waitMs / 1000}s: ${String(error)}`);
+                await pause(waitMs, signal);
+                waitMs = Math.min(waitMs * 2, retryCapMs);
+                continue;
+            }
+            conflicts = 0;
+            waitMs = retryFirstMs;
+            markReady();
+            for (const update of updates) {
+                try {
+                    accept(update);
+                }
+                catch (error) {
+                    // Left unconfirmed it would come back for ever, and every update behind it with it: said, and passed.
+                    log.error(`[telegram] update ${update.update_id} was not taken, and is skipped: ${String(error)}`);
+                }
+                offset = update.update_id + 1;
+            }
+        }
+    };
+    run().then(() => {
+        markReady(); // an abort before the first answer: ready settles, and resolving it means cancelled
+        closed.resolve();
+    }, (error) => {
+        if (signal.aborted) {
+            // A call cut short by the abort is the cancellation, not a failure of the connection.
+            markReady();
+            closed.resolve();
+            return;
+        }
+        const failure = error instanceof Error ? error : new Error(String(error));
+        if (!isReady) {
+            isReady = true;
+            ready.reject(failure);
+        }
+        closed.reject(failure);
+    });
+    return { ready: ready.promise, closed: closed.promise };
+}

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

@@ -1,35 +1,55 @@
-import { needs } from "@fastagent-sh/fastagent";
-import { telegramChannel } from "@fastagent-sh/fastagent/telegram";
+import { byIngress, needs } from "@fastagent-sh/fastagent";
+import {
+  type TelegramChannelOptions,
+  telegramChannel,
+  telegramPollingChannel,
+} from "@fastagent-sh/fastagent/telegram";
 
 // A channel = a third-party ADAPTER (telegramChannel: verify + run + reply) configured with YOUR policy.
-// fastagent registers this file from src/channels/, mounts POST /telegram, and hands the adapter the
-// agent, its sessions and a directory of its own; this file holds only policy. Setup:
-//   1. @BotFather → /newbot → put the bot token in TELEGRAM_BOT_TOKEN
-//   2. pick a random TELEGRAM_SECRET_TOKEN (verifies that inbound updates really come from Telegram)
-//   3. register the webhook once, pointing Telegram at POST /telegram with that secret:
-//        curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
-//          -d url=https://your.host/telegram -d secret_token=$TELEGRAM_SECRET_TOKEN
+// fastagent registers this file from src/channels/ and hands the adapter the agent, its sessions and a directory of
+// its own; this file holds only policy.
 //
-// `needs` declares the env vars this channel reads: fastagent carries them to a deployed box and
-// refuses to serve while one is unset.
-export default needs(["TELEGRAM_BOT_TOKEN", "TELEGRAM_SECRET_TOKEN"], (secrets) =>
-  telegramChannel({
-    secretToken: secrets.TELEGRAM_SECRET_TOKEN, // verifies inbound updates really come from Telegram
-    botToken: secrets.TELEGRAM_BOT_TOKEN, // used to send the agent's reply back to the chat
-    // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
-    // 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, 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" }) && { conversation: `user:${u.message?.from?.id}` },
-    //   route: (u) => defaultTelegramRoute(u, { botUsername: "my_bot" }) && { text: `${telegramEnvelope(u.message!)}\n[extra]` },
-  }),
-);
+// How it receives is the instance's choice, `channels.telegram.ingress` in its fastagent.json (webhook | connection).
+// Unset, `fastagent dev` polls Telegram (no public URL, no tunnel), and everything else — `fastagent start`, every
+// deployment — receives by webhook at POST /telegram, the way a host that wakes on a request is reached. A bot is
+// polled by ONE process or reached by one webhook: polling takes the bot's webhook away first.
+//
+// Setup: @BotFather → /newbot → put the bot token in TELEGRAM_BOT_TOKEN. For webhook, also pick a random
+// TELEGRAM_SECRET_TOKEN (verifies that inbound updates really come from Telegram); the instance sets the webhook
+// itself when it serves at a public URL (`http.publicUrl`), or by hand:
+//   curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
+//     -d url=https://your.host/telegram -d secret_token=$TELEGRAM_SECRET_TOKEN
+
+// Your policy, the same whichever way the channel receives.
+const policy: Pick<TelegramChannelOptions, "onError" | "route" | "botUsername"> = {
+  // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
+  // 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, 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" }) && { conversation: `user:${u.message?.from?.id}` },
+  //   route: (u) => defaultTelegramRoute(u, { botUsername: "my_bot" }) && { text: `${telegramEnvelope(u.message!)}\n[extra]` },
+};
+
+// Each way's `needs` declares the env vars it reads: an instance is asked only for its way's, and refused to serve
+// while a required one is unset.
+export default byIngress({
+  webhook: needs(["TELEGRAM_BOT_TOKEN", "TELEGRAM_SECRET_TOKEN"], (secrets) =>
+    telegramChannel({
+      botToken: secrets.TELEGRAM_BOT_TOKEN, // used to send the agent's reply back to the chat
+      secretToken: secrets.TELEGRAM_SECRET_TOKEN, // verifies inbound updates really come from Telegram
+      ...policy,
+    }),
+  ),
+  connection: needs(["TELEGRAM_BOT_TOKEN"], (secrets) =>
+    telegramPollingChannel({ botToken: secrets.TELEGRAM_BOT_TOKEN, ...policy }),
+  ),
+});

package/dist/channels/telegram/scaffold/telegram-send.ts

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { Type } from "@earendil-works/pi-ai";
+import { bool, num, obj, opt, str, union } from "@earendil-works/pi-schema";
 import { defineTool } from "@earendil-works/pi-durable";
 import { needs } from "@fastagent-sh/fastagent";
 import { telegramTransport } from "@fastagent-sh/fastagent/telegram";
@@ -26,14 +26,14 @@ export default needs(["TELEGRAM_BOT_TOKEN"], ({ TELEGRAM_BOT_TOKEN }) =>
       "from the [telegram: chat …] context line in a chat turn; a scheduled or woken message has no context " +
       "line, so name the destination in your instruction. What you send is shown to you in that chat's " +
       "next turn.",
-    parameters: Type.Object({
-      chatId: Type.Union([Type.String(), Type.Number()], { description: "target chat id" }),
-      text: Type.Optional(Type.String({ description: "message text to send" })),
-      path: Type.Optional(Type.String({ description: "absolute path of the local file to send" })),
-      caption: Type.Optional(Type.String({ description: "file caption (file mode only)" })),
-      asPhoto: Type.Optional(Type.Boolean({ description: "send the file as a photo (inline) instead of a document" })),
-      messageThreadId: Type.Optional(
-        Type.Number({ description: "thread to reply into (from the context line), if any" }),
+    parameters: obj({
+      chatId: union([str(), num()], { description: "target chat id" }),
+      text: opt(str({ description: "message text to send" })),
+      path: opt(str({ description: "absolute path of the local file to send" })),
+      caption: opt(str({ description: "file caption (file mode only)" })),
+      asPhoto: opt(bool({ description: "send the file as a photo (inline) instead of a document" })),
+      messageThreadId: opt(
+        num({ description: "thread to reply into (from the context line), if any" }),
       ),
     }),
     execute: async ({ chatId, text, path, caption, asPhoto, messageThreadId }) => {

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

@@ -0,0 +1,2 @@
+import { type ChannelSetup } from "../setup.ts";
+export declare const telegramSetup: ChannelSetup;