@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/channels/sse.js

@@ -0,0 +1,66 @@
+/** Shared SSE response lifecycle for invoke and session observation. Fetch-only, with no Node dependencies. */
+/** The remote client's idle watchdog allows three missed heartbeats. */
+export const SSE_HEARTBEAT_MS = 30_000;
+const encoder = new TextEncoder();
+const heartbeat = encoder.encode(": ping\n\n");
+export function sseResponse(events, project = (event) => event) {
+    const iterator = events[Symbol.asyncIterator]();
+    // Subscribe before headers; synchronous startup errors belong to the HTTP error boundary.
+    let pending = Promise.resolve(iterator.next());
+    // pull() surfaces asynchronous failures. Observe rejection even if the caller cancels before that pull.
+    pending.catch(() => { });
+    let closed = false;
+    let timer;
+    const stop = () => {
+        closed = true;
+        clearInterval(timer);
+    };
+    const cancel = async () => {
+        if (closed)
+            return;
+        stop();
+        await iterator.return?.();
+    };
+    const stream = new ReadableStream({
+        start(controller) {
+            timer = setInterval(() => controller.enqueue(heartbeat), SSE_HEARTBEAT_MS);
+        },
+        async pull(controller) {
+            try {
+                const next = await (pending ?? iterator.next());
+                pending = undefined;
+                // Cancellation can settle a pending next(); its value no longer has a reader.
+                if (closed)
+                    return;
+                if (next.done) {
+                    stop();
+                    controller.close();
+                }
+                else {
+                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(project(next.value))}\n\n`));
+                }
+            }
+            catch (error) {
+                if (closed)
+                    return;
+                // Errored streams never call cancel(), so iterator and timer cleanup belongs here too.
+                try {
+                    await cancel();
+                }
+                catch (cleanupError) {
+                    controller.error(new AggregateError([error, cleanupError], "SSE source and cleanup failed", { cause: error }));
+                    return;
+                }
+                controller.error(error);
+            }
+        },
+        cancel,
+    });
+    return new Response(stream, {
+        headers: {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+        },
+    });
+}

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

@@ -139,12 +139,32 @@ export declare function messageText(m: TelegramMessage): string;
  * `text: `${telegramEnvelope(m)}\n\n[extra]``. The channel still appends downloaded attachments.
  */
 export declare function telegramEnvelope(m: TelegramMessage): string;
+/**
+ * Whether the update is a `/stop` ADDRESSED TO THIS BOT — the one question the channel asks about a
+ * stop, because an unaddressed one is not a command it may act on. Four ways to address it, all
+ * equivalent: a bare `/stop` in a private chat (no one else is there), `/stop@thisbot`, an `@thisbot`
+ * mention beside the command, and a bare `/stop` replying to one of this bot's messages.
+ *
+ * A BARE `/stop` in a group is deliberately NOT one of them. Telegram hands it to every bot in the
+ * chat — and only promises to deliver it at all when this bot spoke last — so it names no one: acting
+ * on it lets a bystander's ask for a different bot abort this bot's run, and answering it lets that
+ * bystander make this bot talk. It stays ordinary discussion, which is what the group sees anyway.
+ *
+ * Takes the UPDATE, like `route` itself, so a custom route can ask it directly — that route is the
+ * gate a stop must pass, and one that refuses this update silences the command.
+ */
+export declare function telegramStop(update: TelegramUpdate, options?: {
+    botUsername?: string;
+    botId?: number;
+}): boolean;
 /**
  * The default routing policy (used when `route` is omitted; exported so a custom route can reuse it):
  * answer private chats always; a group only on a reply to THIS bot (by `botId`) or a `mention` entity
  * naming it (when `botUsername` is supplied — telegramChannel parses the id from the token and resolves
  * the username via getMe). A bare or directed slash command does NOT summon in a group (that was noisy;
- * a bot author who wants commands adds a custom route). Returns `{}` (act; the channel fills
+ * a bot author who wants commands adds a custom route) — except a `/stop` ADDRESSED to this bot, which
+ * must reach the run it stops rather than sit in the buffer behind it (see {@link telegramStop}; a
+ * bare group `/stop` addresses no one and stays ordinary discussion). Returns `{}` (act; the channel fills
  * session/target/prompt from the message) or `null` (ignore).
  */
 export declare function defaultTelegramRoute(update: TelegramUpdate, options?: {

package/dist/channels/telegram/parse.js

@@ -108,20 +108,66 @@ function botName(botUsername) {
     return s || undefined;
 }
 /**
- * Whether the message @mentions the bot — read from the `mention` ENTITIES Telegram's server already
- * parsed, not a regex over the raw text. The entity type excludes by construction what a text scan
- * false-matches: `@bot` inside a code block or a URL is not a `mention` entity, a glued `/cmd@bot` is a
- * `bot_command` — and slicing the exact offset/length range makes `@fast` vs `@fastagent` confusion
- * impossible. (Offsets are UTF-16 code units = native JS string indexing.) No text fallback: mention
- * entities are produced server-side, so their absence means there is no mention.
+ * The `mention` ENTITIES naming THIS bot — read from what Telegram's server already parsed, not a
+ * regex over the raw text. The entity type excludes by construction what a text scan false-matches:
+ * `@bot` inside a code block or a URL is not a `mention` entity, a glued `/cmd@bot` is a `bot_command`
+ * — and slicing the exact offset/length range makes `@fast` vs `@fastagent` confusion impossible.
+ * (Offsets are UTF-16 code units = native JS string indexing.) No text fallback: mention entities are
+ * produced server-side, so their absence means there is no mention. Empty when the bot does not know
+ * its own username — "which of these names me?" has no answer then, and guessing would mis-summon.
  */
-function mentionsBot(m, botUsername) {
+function botMentions(m, botUsername) {
     const name = botName(botUsername);
     if (!name)
-        return false;
+        return [];
     const text = m.text ?? m.caption ?? "";
     const entities = (m.text !== undefined ? m.entities : m.caption_entities) ?? [];
-    return entities.some((e) => e.type === "mention" && text.slice(e.offset, e.offset + e.length).toLowerCase() === `@${name}`);
+    return entities.filter((e) => e.type === "mention" && text.slice(e.offset, e.offset + e.length).toLowerCase() === `@${name}`);
+}
+/** Whether the message @mentions the bot. */
+function mentionsBot(m, botUsername) {
+    return botMentions(m, botUsername).length > 0;
+}
+/** The message text with THIS bot's mentions cut out, so a command addressed to it reads as the bare
+ *  command. Only its own: a message that names someone else (`@otherbot /stop`) must keep that name,
+ *  or cutting it would turn an ask aimed elsewhere into this bot's command. Cut from the end so the
+ *  earlier offsets stay valid (they are UTF-16 code units = native JS indexing). */
+function textWithoutBotMentions(m, botUsername) {
+    const text = m.text ?? m.caption ?? "";
+    return botMentions(m, botUsername)
+        .sort((a, b) => b.offset - a.offset)
+        .reduce((out, e) => out.slice(0, e.offset) + out.slice(e.offset + e.length), text)
+        .trim();
+}
+/**
+ * Whether the update is a `/stop` ADDRESSED TO THIS BOT — the one question the channel asks about a
+ * stop, because an unaddressed one is not a command it may act on. Four ways to address it, all
+ * equivalent: a bare `/stop` in a private chat (no one else is there), `/stop@thisbot`, an `@thisbot`
+ * mention beside the command, and a bare `/stop` replying to one of this bot's messages.
+ *
+ * A BARE `/stop` in a group is deliberately NOT one of them. Telegram hands it to every bot in the
+ * chat — and only promises to deliver it at all when this bot spoke last — so it names no one: acting
+ * on it lets a bystander's ask for a different bot abort this bot's run, and answering it lets that
+ * bystander make this bot talk. It stays ordinary discussion, which is what the group sees anyway.
+ *
+ * Takes the UPDATE, like `route` itself, so a custom route can ask it directly — that route is the
+ * gate a stop must pass, and one that refuses this update silences the command.
+ */
+export function telegramStop(update, options) {
+    const m = pickMessage(update);
+    if (!m)
+        return false;
+    // This bot's own mentions are cut out before matching: `@thisbot /stop` is the same command as
+    // `/stop@thisbot`. Anyone else's stays in the text, so `@otherbot /stop` never reduces to a command
+    // here — not even when it also replies to this bot.
+    const match = /^\/stop(?:@([A-Za-z0-9_]+))?$/i.exec(textWithoutBotMentions(m, options?.botUsername));
+    if (!match)
+        return false;
+    // `/stop@name` states its addressee: ours only when the name is ours, and never when this bot does
+    // not know its own username (fail closed — the same rule reply/mention summon follows).
+    if (match[1] !== undefined)
+        return match[1].toLowerCase() === botName(options?.botUsername);
+    return m.chat.type === "private" || mentionsBot(m, options?.botUsername) || repliesToBot(m, options);
 }
 /** Whether the message replies to THIS bot — not just any bot: in a multi-bot group, replying to
  *  another bot must not summon ours. Identity is the bot's numeric id (stable; a username is a mutable
@@ -143,13 +189,21 @@ function repliesToBot(m, options) {
  * answer private chats always; a group only on a reply to THIS bot (by `botId`) or a `mention` entity
  * naming it (when `botUsername` is supplied — telegramChannel parses the id from the token and resolves
  * the username via getMe). A bare or directed slash command does NOT summon in a group (that was noisy;
- * a bot author who wants commands adds a custom route). Returns `{}` (act; the channel fills
+ * a bot author who wants commands adds a custom route) — except a `/stop` ADDRESSED to this bot, which
+ * must reach the run it stops rather than sit in the buffer behind it (see {@link telegramStop}; a
+ * bare group `/stop` addresses no one and stays ordinary discussion). Returns `{}` (act; the channel fills
  * session/target/prompt from the message) or `null` (ignore).
  */
 export function defaultTelegramRoute(update, options) {
     const m = pickMessage(update);
     if (!m)
         return null;
-    const summoned = m.chat.type === "private" || repliesToBot(m, options) || mentionsBot(m, options?.botUsername);
+    const summoned = m.chat.type === "private" ||
+        repliesToBot(m, options) ||
+        mentionsBot(m, options?.botUsername) ||
+        // Adds exactly ONE case to the three above: the `/stop@thisbot` suffix form. Every other way to
+        // address a stop (private, mention, reply) is already a summon on its own — telegramStop repeats
+        // those three by design, since it must answer "addressed to me?" without a route to lean on.
+        telegramStop(update, options);
     return summoned ? {} : null;
 }

package/dist/channels/telegram/register-webhook.d.ts

@@ -1,16 +1,13 @@
-import type { RegistrationOutcome } from "../registration.ts";
+import { type RegistrationOutcome } from "../registration.ts";
 /**
- * Register `<baseUrl>/telegram` as the bot's webhook (with the .env secret). Waits for the server to be
- * REACHABLE first — polling `<baseUrl>/health` — because Telegram VERIFIES the URL when you set it, and a
- * fresh deploy's container (healthcheck + routing) or a fresh tunnel's DNS is not routable for some
- * seconds after the deploy/tunnel command returns. Tracking real readiness (not a fixed timer) is what
- * fixes the race that made the first real deploy need a manual `setWebhook`. Missing tokens print the
- * manual instruction instead of failing. `opts` (timeouts) exist for tests; production uses the defaults.
+ * Register `<baseUrl>/telegram` as the bot's webhook (with the .env secret). Missing tokens print the
+ * manual instruction instead of failing. `opts` carries the attempt budget: `--tunnel` takes the
+ * default, `deploy --run` passes `DEPLOY_REGISTRATION_ATTEMPTS` (a host starts slower than a tunnel),
+ * and tests shrink it.
  *
  * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
 export declare function registerTelegramWebhook(baseUrl: string, opts?: {
-    readyTimeoutMs?: number;
-    readyIntervalMs?: number;
+    attempts?: number;
     retryMs?: number;
 }): Promise<RegistrationOutcome>;

package/dist/channels/telegram/register-webhook.js

@@ -2,18 +2,36 @@
  * Telegram webhook registration — the TELEGRAM-domain step both `--tunnel` (dev, tunnel.ts) and
  * `deploy … --run` (the host runners' post-deploy step) invoke. What "registering telegram" means lives
  * here, beside the channel it serves; it reads the same .env tokens the channel uses.
+ *
+ * READINESS IS setWebhook'S OWN VERDICT, not a local probe. Telegram VERIFIES the URL during the call,
+ * from Telegram's network — which is the only network that has to reach it. This used to poll
+ * `<baseUrl>/health` from here first, and that probe answered a different question badly: a freshly
+ * minted hostname (a quick tunnel, a fresh deploy) is routinely unreachable from the machine running
+ * the CLI for a minute or more — behind a proxy, or while its own resolver still says ENOTFOUND — long
+ * after Telegram can reach it (#421). So the retry loop below IS the wait: Telegram's reachability
+ * verdicts ("Failed to resolve host", "Wrong response from the webhook") are retried, and only a
+ * configuration error the operator must fix is reported once.
  */
-import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "../../log.js";
-import { waitForHealth } from "../wait-health.js";
+import { retryWhile } from "../registration.js";
 import { callApi } from "./telegram-api.js";
 /**
- * Register `<baseUrl>/telegram` as the bot's webhook (with the .env secret). Waits for the server to be
- * REACHABLE first — polling `<baseUrl>/health` — because Telegram VERIFIES the URL when you set it, and a
- * fresh deploy's container (healthcheck + routing) or a fresh tunnel's DNS is not routable for some
- * seconds after the deploy/tunnel command returns. Tracking real readiness (not a fixed timer) is what
- * fixes the race that made the first real deploy need a manual `setWebhook`. Missing tokens print the
- * manual instruction instead of failing. `opts` (timeouts) exist for tests; production uses the defaults.
+ * Whether a setWebhook failure is the URL still warming up rather than a configuration error. Two
+ * families: transport failures reaching Telegram at all, and Telegram's own verdict after it fails to
+ * reach the webhook — which carries its connection layer's words verbatim (`Bad Request: bad webhook:
+ * Connection timed out` / `Connection refused` for a host whose DNS answers before anything listens,
+ * `Wrong response from the webhook: 530` for a tunnel edge without its origin). This is the ONLY gate
+ * between "spend the caller's retry budget" and "fail now", so it is wide on the reachability side.
+ * A permanent "bad webhook" — an http:// URL, an unsupported port — matches nothing here and is reported.
+ */
+function isTransientRegistrationError(error) {
+    return /resolve host|getaddrinfo|ENOTFOUND|fetch failed|ECONNRESET|timeout|timed out|connection refused|can't connect|connection to the host|wrong response from the webhook/i.test(error);
+}
+/**
+ * Register `<baseUrl>/telegram` as the bot's webhook (with the .env secret). Missing tokens print the
+ * manual instruction instead of failing. `opts` carries the attempt budget: `--tunnel` takes the
+ * default, `deploy --run` passes `DEPLOY_REGISTRATION_ATTEMPTS` (a host starts slower than a tunnel),
+ * and tests shrink it.
  *
  * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
@@ -25,40 +43,24 @@ export async function registerTelegramWebhook(baseUrl, opts = {}) {
         log.info(`[fastagent] telegram: set TELEGRAM_BOT_TOKEN + TELEGRAM_SECRET_TOKEN in .env, then re-run to auto-register. Webhook URL: ${webhookUrl}`);
         return "manual";
     }
-    // Align registration with the server actually serving. Don't setWebhook against a URL Telegram can't
-    // yet reach — it would fail, and a fixed retry window guesses the readiness delay (the deploy race).
-    log.info(`[fastagent] telegram: waiting for ${baseUrl} to be reachable before registering the webhook…`);
-    const ready = await waitForHealth(`${baseUrl}/health`, opts.readyTimeoutMs ?? 120_000, opts.readyIntervalMs ?? 3_000);
-    if (!ready) {
-        // Terminal for this run (registration will not be retried) — error, not warn: the webhook is NOT
-        // registered and the operator must act. Same taxonomy as the permanent setWebhook failure below.
-        log.error(`[fastagent] telegram: ${baseUrl}/health did not come up in time — the app may still be starting. ` +
-            `Register the webhook manually once it's up: curl "https://api.telegram.org/bot<token>/setWebhook" -d url=${webhookUrl} -d secret_token=<secret>`);
-        return "failed";
+    log.info(`[fastagent] telegram: registering the webhook — Telegram verifies ${webhookUrl} as it does…`);
+    try {
+        await retryWhile(() => callApi("https://api.telegram.org", botToken, "setWebhook", { url: webhookUrl, secret_token: secret }), (error) => isTransientRegistrationError(String(error)), {
+            attempts: opts.attempts,
+            retryMs: opts.retryMs,
+            onRetry: ({ attempt, attempts }) => log.info(`[fastagent] telegram: Telegram cannot reach ${webhookUrl} yet (attempt ${attempt}/${attempts}); retrying…`),
+        });
+        log.info(`[fastagent] telegram: webhook registered → ${webhookUrl}`);
+        return "registered";
     }
-    // Reachable → register. A short retry backstops Telegram's resolver lagging /health by a moment; only
-    // network-transient errors retry (a permanent "bad webhook" config error is reported, not retried).
-    let lastTransientError = "unknown transport error";
-    for (let attempt = 0; attempt < 3; attempt++) {
-        if (attempt > 0)
-            await sleep(opts.retryMs ?? 2000);
-        try {
-            await callApi("https://api.telegram.org", botToken, "setWebhook", { url: webhookUrl, secret_token: secret });
-            log.info(`[fastagent] telegram: webhook registered → ${webhookUrl}`);
-            return "registered";
-        }
-        catch (e) {
-            const error = String(e);
-            if (!/resolve host|getaddrinfo|ENOTFOUND|fetch failed|ECONNRESET|timeout/i.test(error)) {
-                log.error(`[fastagent] telegram: setWebhook failed (${error}). Register manually with url=${webhookUrl}`);
-                return "failed";
-            }
-            lastTransientError = error;
-        }
+    catch (e) {
+        // Both endings leave the webhook unregistered and the operator with work to do, so both are ERROR;
+        // they differ only in what to do about it.
+        const error = String(e);
+        log.error(isTransientRegistrationError(error)
+            ? `[fastagent] telegram: Telegram could not reach ${webhookUrl} after retries (last error: ${error}). ` +
+                `Once it is up, register manually: curl "https://api.telegram.org/bot<token>/setWebhook" -d url=${webhookUrl} -d secret_token=<secret>`
+            : `[fastagent] telegram: setWebhook failed (${error}). Register manually with url=${webhookUrl}`);
+        return "failed";
     }
-    // Exhausted retries end in the same state as a permanent error (webhook not registered, manual
-    // action required) — report at the same level.
-    log.error(`[fastagent] telegram: setWebhook still failing after retries (last error: ${lastTransientError}). ` +
-        `Register manually with url=${webhookUrl}`);
-    return "failed";
 }

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

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

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

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

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

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