@fastagent-sh/fastagent 0.20.0 → 0.21.0

package/dist/channels/slack/slack.js

@@ -1,9 +1,10 @@
 /** First-party Slack HTTP Events API channel: signed ingress, durable turns/context, files, and edited previews. */
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { createHmac } from "node:crypto";
 import { isAbsolute, join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
+import { secretEquals } from "../secret.js";
 import { createSeenRing } from "../kit/seen.js";
 import { signatureIsFresh } from "../kit/signature.js";
 import { createThreadParticipants } from "../kit/thread-participants.js";
@@ -11,15 +12,15 @@ import { createTaskTracker } from "../kit/tasks.js";
 import { ensureStateHome } from "../kit/state.js";
 import { dispatchStop, isStopText } from "../kit/stop-command.js";
 import { codePointPrefix } from "../kit/text.js";
-import { createTurnQueue } from "../kit/turn-queue.js";
-import { commitAnsweredTurn, createTurnStore } from "../kit/turn-store.js";
+import { createTurnRunner } from "../kit/turn-runner.js";
+import { createTurnStore } from "../kit/turn-store.js";
 import { discussionBlock } from "../kit/context-buffer.js";
-import { createSlackBotTokenProvider } from "./bot-auth.js";
 import { collectSlackBufferedFiles, createSlackContextBuffer } from "./context-buffer.js";
 import { invokeSlackTurn } from "./invoke-turn.js";
 import { defaultSlackRoute, isSlackDirectMessage, isSlackGroupMessage, hasSlackMention, hasSlackUserMention, isSlackHumanMessage, mentionsSlackUser, stripSlackMentions, slackBufferText, slackEnvelope, slackFileIds, slackMessageText, slackPlaceKey, slackSenderLabel, slackTeamId, } from "./parse.js";
 import { defaultErrorMessage, settleSlackPreview, streamSlackReply, } from "./preview.js";
 import { resolveReactionEmojis, startSlackReaction } from "./reaction.js";
+import { registerSlackApi } from "./shared-api.js";
 import { createSlackApi } from "./slack-api.js";
 import { createWelcomedUsers } from "./welcomed.js";
 export { defaultSlackRoute, slackEnvelope };
@@ -53,9 +54,7 @@ export function verifySlackSignature(signingSecret, timestamp, signature, rawBod
     if (!signatureIsFresh(timestamp, MAX_SIGNATURE_AGE_S, nowMs))
         return false;
     const expected = `v0=${createHmac("sha256", signingSecret).update(`v0:${timestamp}:${rawBody}`).digest("hex")}`;
-    const actualBytes = Buffer.from(signature);
-    const expectedBytes = Buffer.from(expected);
-    return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+    return secretEquals(signature, expected);
 }
 /** The (channel, ts) of the user's triggering message, encoded in the logical turn id `team:channel:ts`
  *  (Slack ids never contain a colon, so a 3-part split is exact). Used to place the reaction ack. */
@@ -64,19 +63,7 @@ function messageRefOf(turnId) {
     return parts.length === 3 && parts[1] && parts[2] ? { channelId: parts[1], ts: parts[2] } : undefined;
 }
 export function slackChannel(options) {
-    const { botToken, signingSecret, botRefreshToken, clientId, clientSecret, botTokenExpiresAt, groupBehavior = "context", rendering = "native", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", } = options;
-    // The participant model derives placement instead of selecting it: Slack has no quote primitive, so
-    // answering in place means answering in a thread on the ask, whichever renderer draws it. An
-    // upgraded workspace still passing one of the removed modes would otherwise start fine and silently
-    // get a different placement AND a different memory boundary.
-    const removedModes = ["directMessageSession", "groupMessageSession"].filter((name) => options[name] !== undefined);
-    if (removedModes.length > 0) {
-        throw new Error(`slackChannel no longer accepts ${removedModes.join(" / ")}: an answer goes in a thread on the ask, and ` +
-            "that thread is the session — see docs/design/participant-model.md");
-    }
-    if (!["context", "mentions"].includes(groupBehavior)) {
-        throw new Error('slackChannel groupBehavior must be "context" or "mentions"');
-    }
+    const { botToken, signingSecret, rendering = "native", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", } = options;
     if (!["native", "classic"].includes(rendering)) {
         throw new Error('slackChannel rendering must be "native" or "classic"');
     }
@@ -95,16 +82,8 @@ export function slackChannel(options) {
         const formatError = onError ?? defaultErrorMessage;
         const stateHome = join(stateRoot, "channels", "slack");
         ensureStateHome(stateHome);
-        const currentBotToken = createSlackBotTokenProvider({
-            statePath: join(stateHome, "bot-auth.json"),
-            botToken,
-            botRefreshToken,
-            clientId,
-            clientSecret,
-            botTokenExpiresAt,
-            apiBaseUrl,
-        });
-        const api = createSlackApi({ botToken: currentBotToken, baseUrl: apiBaseUrl });
+        const api = createSlackApi({ botToken, baseUrl: apiBaseUrl });
+        registerSlackApi(stateRoot, api); // the send tool delivers through this one (shared-api.ts)
         let authenticatedTeamId;
         let botUserId;
         let authenticationState = "pending";
@@ -154,64 +133,66 @@ export function slackChannel(options) {
             order: (a, b) => a.seq - b.seq,
         });
         const decide = route ?? defaultSlackRoute;
-        const toStored = (turn) => {
-            const { previewTs: _preview, nativeQueueStatus: _status, ...intent } = turn;
-            return { ...intent, attempts: 0 };
-        };
         const targetOf = (turn) => ({
             channelId: turn.channelId,
             threadTs: turn.threadTs,
             recipientUserId: turn.requesterUserId,
             recipientTeamId: turn.teamId,
         });
-        const notices = new Map();
-        const queue = createTurnQueue({
+        const notifyDropped = (turn) => {
+            const target = targetOf(turn);
+            if (turn.nativeQueueStatus)
+                void api.setThreadStatus(target, "").catch(() => { });
+            void settleSlackPreview(api, target, turn.previewTs, "⚠️ I couldn’t complete an earlier request — please ask again.").catch((error) => log.warn(`${label} could not notify a dropped turn: ${String(error)}`));
+        };
+        const runner = createTurnRunner({
             label,
+            store,
+            buffer,
+            seen,
+            toStored: ({ previewTs: _preview, nativeQueueStatus: _status, ...intent }) => ({ ...intent, attempts: 0 }),
+            fromStored: ({ attempts: _attempts, ...intent }) => ({ ...intent }),
+            bufferKey: (turn) => turn.bufferKey,
+            where: (turn) => `channel=${turn.channelId}`,
             onQueuedBehind(turn) {
                 const nativeDmStatus = rendering === "native" && turn.threadTs && turn.channelId.startsWith("D");
                 if (nativeDmStatus)
                     turn.nativeQueueStatus = true;
-                notices.set(turn.id, authentication
-                    .then(() => nativeDmStatus
-                    ? api.setThreadStatus(targetOf(turn), "is queued behind an earlier request…")
-                    : api.postMessage(targetOf(turn), QUEUED_PLACEHOLDER).then((ts) => {
-                        turn.previewTs = ts;
-                    }))
-                    .catch((error) => log.warn(`${label} queue preview failed (the turn stays durable): ${String(error)}`)));
+                return {
+                    done: authentication
+                        .then(() => nativeDmStatus
+                        ? api.setThreadStatus(targetOf(turn), "is queued behind an earlier request…")
+                        : api.postMessage(targetOf(turn), QUEUED_PLACEHOLDER).then((ts) => {
+                            turn.previewTs = ts;
+                        }))
+                        .catch((error) => log.warn(`${label} queue preview failed (the turn stays durable): ${String(error)}`)),
+                };
             },
-            run: async (turn) => {
-                await notices.get(turn.id);
-                notices.delete(turn.id);
+            // Leave the intent untouched when Slack auth failed. A fixed token + restart replays it;
+            // running now would execute an Agent turn whose only customer-facing transport is known to be
+            // unavailable.
+            beforeRun: async (turn) => {
                 try {
                     await authentication;
+                    return true;
                 }
                 catch (error) {
-                    // Leave the intent untouched. A fixed token + restart replays it; running now would execute an
-                    // Agent turn whose only customer-facing transport is known to be unavailable.
                     log.error(`${label} deferring durable turn ${turn.id} because Slack authentication failed: ${String(error)}`);
-                    return;
+                    return false;
                 }
-                const attempt = store.startAttempt(turn.id);
-                if (attempt === "exceeded") {
-                    notifyDropped(turn);
-                    return;
+            },
+            onDeferred: (turn) => {
+                if (turn.nativeQueueStatus) {
+                    void api
+                        .setThreadStatus(targetOf(turn), "is delayed by a temporary system issue and will retry after restart…")
+                        .catch((error) => log.warn(`${label} could not update a deferred Agent status: ${String(error)}`));
                 }
-                if (attempt === "defer") {
-                    if (turn.nativeQueueStatus) {
-                        void api
-                            .setThreadStatus(targetOf(turn), "is delayed by a temporary system issue and will retry after restart…")
-                            .catch((error) => log.warn(`${label} could not update a deferred Agent status: ${String(error)}`));
-                    }
-                    else if (turn.previewTs) {
-                        void settleSlackPreview(api, targetOf(turn), turn.previewTs, DEFERRED_PLACEHOLDER).catch((error) => log.warn(`${label} could not update a deferred queue preview: ${String(error)}`));
-                    }
-                    return;
+                else if (turn.previewTs) {
+                    void settleSlackPreview(api, targetOf(turn), turn.previewTs, DEFERRED_PLACEHOLDER).catch((error) => log.warn(`${label} could not update a deferred queue preview: ${String(error)}`));
                 }
-                const startedAt = Date.now();
-                log.info(`${label} turn start: turn=${turn.id} session=${turn.session} channel=${turn.channelId}`);
-                const { text: recent, consumed } = buffer.peek(turn.bufferKey);
-                const prompt = `${discussionBlock(recent)}${turn.baseText}`;
-                const buffered = collectSlackBufferedFiles(consumed, new Set(turn.fileIds));
+            },
+            notifyDropped,
+            execute: async (turn, discussion, onCompleted) => {
                 const messageRef = messageRefOf(turn.id);
                 const reaction = reactionEmojis && messageRef
                     ? await startSlackReaction({
@@ -223,44 +204,25 @@ export function slackChannel(options) {
                     })
                     : undefined;
                 try {
-                    await streamSlackReply(invokeSlackTurn(agent, turn.session, prompt, { api, channelId: turn.channelId, filesDir: join(stateHome, "files"), label }, { primaryFileIds: turn.fileIds, buffered }, () => commitAnsweredTurn(store, buffer, { id: turn.id, bufferKey: turn.bufferKey, consumed })), api, targetOf(turn), formatError, {
+                    await streamSlackReply(invokeSlackTurn(agent, turn.session, `${discussionBlock(discussion.text)}${turn.baseText}`, { api, channelId: turn.channelId, filesDir: join(stateHome, "files"), label }, {
+                        primaryFileIds: turn.fileIds,
+                        buffered: collectSlackBufferedFiles(discussion.consumed, new Set(turn.fileIds)),
+                    }, onCompleted), api, targetOf(turn), formatError, {
                         rendering,
                         initialPreviewTs: turn.previewTs,
                         threadTitle: turn.threadTitle,
                         disclaimer: aiDisclaimer,
                         label,
                     });
-                    log.info(`${label} turn done: turn=${turn.id} session=${turn.session} (${Date.now() - startedAt}ms)`);
-                    await reaction?.complete();
                 }
                 catch (error) {
-                    log.error(`${label} turn failed: turn=${turn.id} session=${turn.session}: ${String(error)}`);
                     await reaction?.remove();
+                    throw error;
                 }
-                finally {
-                    store.remove(turn.id);
-                }
+                await reaction?.complete();
             },
         });
-        const notifyDropped = (turn) => {
-            const target = targetOf(turn);
-            if (turn.nativeQueueStatus)
-                void api.setThreadStatus(target, "").catch(() => { });
-            void settleSlackPreview(api, target, turn.previewTs, "⚠️ I couldn’t complete an earlier request — please ask again.").catch((error) => log.warn(`${label} could not notify a dropped turn: ${String(error)}`));
-        };
-        const submit = (turn, persist) => {
-            if (persist) {
-                store.add(toStored(turn));
-                seen.add(turn.id);
-            }
-            queue.accept(turn);
-        };
-        const recovered = store.recover();
-        if (recovered.length)
-            log.info(`${label} recovering ${recovered.length} unfinished turn(s) from a prior run`);
-        let seq = recovered.reduce((maximum, turn) => Math.max(maximum, turn.seq), 0);
-        for (const { attempts: _attempts, ...intent } of recovered)
-            submit({ ...intent }, false);
+        let seq = runner.recover().reduce((maximum, turn) => Math.max(maximum, turn.seq), 0);
         // Acceptance touches no network, so it stays synchronous inside Slack's ACK window and the
         // delivery dedup ring alone is enough — there is no await for a duplicate delivery to race
         // through. The minutes-long Agent turn remains fire-and-forget.
@@ -287,7 +249,7 @@ export function slackChannel(options) {
             // Listening is not speaking: every message the channel can see refines who takes part in its
             // thread, whether or not it is answered. Humans only — a bot's own posts are recorded where they
             // are known — this channel answering.
-            // Structural facts only, never `groupBehavior` or `route` — see thread-participants.ts. Slack
+            // Structural facts only, never `route` — see thread-participants.ts. Slack
             // adds no delta of its own here; its summon rule is the only consumer.
             if (group && event.thread_ts !== undefined) {
                 threadParticipants.merge(threadKey(teamId, event.channel, event.thread_ts), { humans: [event.user] });
@@ -309,7 +271,6 @@ export function slackChannel(options) {
             // structural: it reads who THIS message addresses, which is the one thing an observation-only
             // store cannot know about someone it has never heard.
             if (!routed &&
-                groupBehavior === "context" &&
                 route === undefined &&
                 group &&
                 event.thread_ts !== undefined &&
@@ -323,7 +284,7 @@ export function slackChannel(options) {
             if (!routed) {
                 if (route === undefined && group && botUserId === undefined && mightBeTheBot)
                     return;
-                if (groupBehavior === "context" && route === undefined && group) {
+                if (route === undefined && group) {
                     const body = slackBufferText(slackMessageText(event));
                     if (body) {
                         const fileIds = slackFileIds(event);
@@ -367,7 +328,7 @@ export function slackChannel(options) {
             const threadTitle = direct && event.thread_ts === undefined
                 ? codePointPrefix(stripSlackMentions(slackMessageText(event), "").replace(/\s+/g, " ").trim(), 80)
                 : undefined;
-            submit({
+            runner.submit({
                 id: logicalId,
                 seq: ++seq,
                 session: routed.session ?? defaultSession,
@@ -486,7 +447,7 @@ export function slackChannel(options) {
             acceptEvent(envelope);
             return new Response(null, { status: 200 });
         };
-        handler.turnsIdle = () => Promise.all([queue.idle(), sideTasks.drain()]).then(() => undefined);
+        handler.turnsIdle = () => Promise.all([runner.idle(), sideTasks.drain()]).then(() => undefined);
         return { "POST /slack": handler };
     };
 }

package/dist/channels/sse.d.ts

@@ -0,0 +1,4 @@
+/** 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 declare const SSE_HEARTBEAT_MS = 30000;
+export declare function sseResponse<T>(events: AsyncIterable<T>, project?: (event: T) => unknown): Response;

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/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";
 }