@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/channels/telegram/telegram.js

@@ -9,7 +9,7 @@
  * Every other concern lives in its own module, each owning its invariants:
  *   - parse.ts          pure message parsing: field extraction, prompt envelope, summon/route policy
  *   - invoke-turn.ts    run one turn: assemble inputs (resolve attachments) + stream `agent.invoke`
- *   - turn-queue.ts     in-memory per-session serial execution (FIFO; one turn at a time per session)
+ *   - kit/turn-runner.ts the durable-turn lifecycle (accept → dequeue → execute → end) over the queue + store
  *   - turn-store.ts     durable turn intent (L1): pre-ACK persist, replay a crash-surviving turn
  *   - context-buffer.ts un-summoned group discussion, folded into the next answered turn
  *   - preview.ts        the live-preview pump ("💭 Thinking…" → edits → final answer) + terminal writes
@@ -22,40 +22,25 @@
  * Authored against the public `@fastagent-sh/fastagent` surface only (the contract + the channel-authoring
  * kit: readBodyCapped / text), so it is exactly what a third-party `fastagent-channel-*` package would write.
  */
-import { timingSafeEqual } 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 { invokeTurn } from "./invoke-turn.js";
 import { collectAttachments, createContextBuffer } from "./context-buffer.js";
-import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, } from "./parse.js";
+import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, telegramStop, } from "./parse.js";
 import { defaultErrorMessage, streamReply } from "./preview.js";
 import { ensureStateHome } from "../kit/state.js";
 import { dispatchStop } from "../kit/stop-command.js";
 import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
-import { createTurnQueue } from "../kit/turn-queue.js";
+import { createTurnRunner } from "../kit/turn-runner.js";
+import { discussionBlock } from "../kit/context-buffer.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 };
-/** Execution ceiling: a turn that has STARTED running this many times without finishing is dropped
- *  rather than run again (a poison turn must not loop forever under a restart policy). Counted per turn
- *  at dequeue, so a never-run turn queued behind a poison one keeps its full budget.
- *
- *  Known limitation: `startAttempt` cannot tell a self-inflicted process crash from an external SIGTERM
- *  (no graceful drain), so a legitimately LONG turn interrupted by this many successive deploys is
- *  dropped ("please ask again") as if it were poison. Accepted: catching SIGTERM to spare it would
- *  reintroduce the drain the design refuses, and a turn outliving this many deploy cycles is an outlier
- *  — raise this constant if such turns are expected. */
-const MAX_TURN_ATTEMPTS = 3;
+export { defaultTelegramRoute, telegramEnvelope, telegramStop };
 /** Update body cap — Telegram updates are small JSON; 1 MiB is generous and guards a public endpoint. */
 const MAX_UPDATE_BYTES = 1 << 20;
-/** Constant-time compare so the secret-token check leaks no timing signal. */
-function tokenMatches(header, secret) {
-    const a = Buffer.from(header);
-    const b = Buffer.from(secret);
-    return a.length === b.length && timingSafeEqual(a, b);
-}
 /**
  * Build a Telegram bot channel: policy options in, a {@link ChannelModule} out. The framework (or an
  * embedder) mounts it with the context — `telegramChannel(opts)` in `channels/telegram.ts` is the whole
@@ -77,9 +62,10 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             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, 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.
+        // 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)
@@ -88,7 +74,11 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 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.");
             }
-        }, (e) => log.warn(`[telegram] getMe failed; @mention summon + privacy check skipped: ${String(e)}`));
+        }, 
+        // Name every capability the missing username costs, so "the bot ignores /stop@name" is
+        // diagnosable from this ONE line — the alternative, a warn per undecidable message, repeats a
+        // single startup fact on every update.
+        (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).
         // Every real token parses; one that doesn't (a mock/test token) degrades visibly: reply summon stays
@@ -114,159 +104,64 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
         // 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. See turn-store.ts for the at-least-once semantics.
         const store = createTurnStore(join(stateHome, "turns.json"));
-        const toStored = (r) => {
-            const { previewId: _live, ...intent } = r; // drop the live-only field; TS enforces the rest is complete
-            return { ...intent, attempts: 0 };
+        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. Take over the ⏳ "Queued" notice in place if the turn had one (else send
+        // fresh) — leaving it pinned at "Queued" while sending a separate failure would double-post. Best-
+        // effort, like the queue notices.
+        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 (session=${r.session}): ${String(e)}`));
         };
-        // In-memory: the in-flight "⏳ queued" notice per turn, awaited at dequeue so the turn reliably takes
-        // the notice message over (rec.previewId) instead of racing it and orphaning a late-arriving notice.
-        const notices = new Map();
-        const queue = createTurnQueue({
+        const runner = createTurnRunner({
             label: "[telegram]",
+            store,
+            buffer,
+            toStored: ({ previewId: _live, ...intent }) => ({ ...intent, attempts: 0 }),
+            fromStored: ({ attempts: _a, ...intent }) => ({ ...intent, previewId: undefined }),
+            bufferKey: (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 — tell the asker NOW (reply-quoted, so it is
             // clear whose ask is queued). Best-effort and post-ACK: a failed notice is a log line, never a
-            // failed update. The turn's live preview then edits this same message in place.
-            onQueuedBehind: (rec) => {
-                const target = {
-                    chatId: rec.chatId,
-                    threadId: rec.threadId,
-                    replyTo: rec.replyTo,
-                };
-                notices.set(rec.id, sendMessage(apiBaseUrl, botToken, target, "⏳ Queued — I’ll start once the current task finishes.", {
+            // failed update. The turn's live preview then edits this same message in place. The runner holds
+            // this same `rec` object, so mutating it here (awaited at dequeue) hands the turn its preview id.
+            onQueuedBehind: (rec) => ({
+                done: sendMessage(apiBaseUrl, botToken, targetOf(rec), "⏳ Queued — I’ll start once the current task finishes.", {
                     html: false,
-                }).then(
-                // The runner holds this same `rec` object, so mutating it here (gated by the notices await at
-                // dequeue below) is what hands the turn its preview message id.
-                (id) => {
+                }).then((id) => {
                     if (id !== undefined)
                         rec.previewId = id;
-                }, (e) => log.warn(`[telegram] queue notice failed (the turn still runs): ${String(e)}`)));
-            },
-            run: async (rec) => {
-                // Runs at DEQUEUE time (serialized), so the lifecycle log and engine turn reflect the actual
-                // execution order rather than arrival.
-                // Settle the queue notice (if any) so rec.previewId is final. NOT free: a slow (not failed)
-                // notice delays this turn's start by up to the API timeout — accepted, because racing it would
-                // orphan the ⏳ message and double-post a placeholder; in the common path the notice resolved
-                // while the previous turn was still running, so this await is instant. BEFORE the ceiling check
-                // so a dropped turn's notice is settled/cleared too (rec.previewId lets notifyDropped take it over).
-                await notices.get(rec.id);
-                notices.delete(rec.id);
-                // Count this execution against the durable record (poison-turn ceiling) before running it again.
-                const decision = store.startAttempt(rec.id, MAX_TURN_ATTEMPTS);
-                if (decision === "exceeded") {
-                    // Started MAX_TURN_ATTEMPTS times without finishing — tell the asker (reusing its ⏳ notice if
-                    // any), drop it.
-                    notifyDropped(rec);
-                    return;
+                }, (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 — the eventual replay
+            // sends a fresh preview, and leaving it would orphan a stale message above that.
+            onDeferred: (rec) => {
+                if (rec.previewId !== undefined) {
+                    void callApi(apiBaseUrl, botToken, "deleteMessage", {
+                        chat_id: rec.chatId,
+                        message_id: rec.previewId,
+                    }).catch(() => { });
                 }
-                if (decision === "defer") {
-                    // Couldn't record the attempt (disk failure): skip this cycle. A restart replays it, so no notify
-                    // (telling the asker to re-ask would double-answer once the deferred turn runs). Two accepted
-                    // edges of this rare disk-failure corner: (1) the session chain proceeds to the next queued turn,
-                    // so a deferred turn can replay AFTER its successors — a per-session FIFO reorder; (2) its ⏳ notice
-                    // (if it was queued behind another turn) now falsely reads "Queued", so delete it best-effort — the
-                    // eventual replay sends a fresh preview, and leaving it would orphan a stale message above that.
-                    if (rec.previewId !== undefined) {
-                        void callApi(apiBaseUrl, botToken, "deleteMessage", {
-                            chat_id: rec.chatId,
-                            message_id: rec.previewId,
-                        }).catch(() => { });
-                    }
-                    return;
-                }
-                const startedAt = Date.now();
-                const where = `chat=${rec.chatId}${rec.threadId !== undefined ? ` thread=${rec.threadId}` : ""}`;
-                log.info(`[telegram] turn start: turn=${rec.id} session=${rec.session} ${where}`);
-                // Fold the un-summoned discussion since the last answered turn into the prompt; it is cleared
-                // only when the turn COMPLETES (then it lives in the session).
-                const { text: recent, consumed } = buffer.peek(rec.placeKey);
-                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${rec.baseText}` : rec.baseText;
-                const buffered = collectAttachments(consumed, {
+            },
+            notifyDropped,
+            execute: (rec, discussion, onCompleted) => streamReply(invokeTurn(agent, rec.session, `${discussionBlock(discussion.text)}${rec.baseText}`, { api: apiBaseUrl, botToken, chatId: rec.chatId, filesDir: join(stateHome, "files") }, {
+                primary: { imageFileIds: rec.imageFileIds, fileIds: rec.fileIds },
+                buffered: collectAttachments(discussion.consumed, {
                     files: new Set(rec.fileIds),
                     images: new Set(rec.imageFileIds),
-                });
-                const target = {
-                    chatId: rec.chatId,
-                    threadId: rec.threadId,
-                    replyTo: rec.replyTo,
-                };
-                try {
-                    await streamReply(invokeTurn(agent, rec.session, prompt, {
-                        api: apiBaseUrl,
-                        botToken,
-                        chatId: rec.chatId,
-                        filesDir: join(stateHome, "files"),
-                    }, {
-                        primary: {
-                            imageFileIds: rec.imageFileIds,
-                            fileIds: rec.fileIds,
-                        },
-                        buffered,
-                    }, () => {
-                        // On completed, ORDER the two durable clears so a crash between them can't replay a
-                        // context-stripped turn: drop the intent FIRST (a crash after this won't replay it), THEN
-                        // commit the context buffer (a crash before this just re-folds the same context into the
-                        // next summon — harmless and additive). The reverse order would leave intent+no-context.
-                        store.remove(rec.id);
-                        buffer.commit(rec.placeKey, consumed);
-                    }), apiBaseUrl, botToken, target, formatError, rec.previewId);
-                    log.info(`[telegram] turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
-                }
-                catch (error) {
-                    log.error(`[telegram] turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error)}`);
-                }
-                finally {
-                    // Fallback removal for the caught-error paths (a `failed` event or a transport throw): those
-                    // never reach the completed hook above, which is where a completed turn removes its intent in
-                    // order. Idempotent — a second remove after the completed hook is a no-op. Only an INTERRUPTED run
-                    // (this finally never runs — a crash or a SIGTERM deploy, no graceful drain) leaves the record for
-                    // replay; a transport throw is dropped, not retried (safe retry needs an L2 delivery key).
-                    store.remove(rec.id);
-                }
-            },
+                }),
+            }, onCompleted), apiBaseUrl, botToken, targetOf(rec), formatError, rec.previewId),
         });
-        // Accept a turn: persist its intent before the ACK (durable), then enqueue it. Recovery re-enqueues a
-        // crash-surviving turn WITHOUT re-persisting (it is already on disk with a bumped attempt count).
-        const submit = (rec, persist) => {
-            if (persist)
-                store.add(toStored(rec)); // pre-ACK: a failed write throws → webhook 500 → redeliver
-            queue.accept(rec);
-        };
-        // 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. Take over the ⏳ "Queued" notice in place if the turn had one (else send
-        // fresh) — leaving it pinned at "Queued" while sending a separate failure would double-post. Best-
-        // effort, like the queue notices.
-        const notifyDropped = (r) => {
-            const body = "⚠️ I couldn’t complete an earlier request — please ask again.";
-            const target = {
-                chatId: r.chatId,
-                threadId: r.threadId,
-                replyTo: r.replyTo,
-            };
-            const sent = r.previewId !== undefined
-                ? editMessageText(apiBaseUrl, botToken, target, r.previewId, body, {
-                    html: false,
-                })
-                : sendMessage(apiBaseUrl, botToken, target, body, {
-                    html: false,
-                }).then(() => { });
-            void sent.catch((e) => log.warn(`[telegram] could not notify a dropped turn (session=${r.session}): ${String(e)}`));
-        };
-        // Re-enqueue turns a prior crash left mid-flight (ACKed but unfinished). Synchronous at construction:
-        // the queue runs them on the next tick, once this factory returns and the event loop turns. The
-        // execution ceiling is enforced per turn at dequeue (run), not here — a never-run turn keeps its budget.
-        const recovered = store.recover();
-        if (recovered.length > 0)
-            log.info(`[telegram] recovering ${recovered.length} unfinished turn(s) from a prior run`);
-        for (const { attempts: _a, ...intent } of recovered)
-            submit({ ...intent, previewId: undefined }, false);
+        runner.recover();
         const handler = async (req) => {
             if (req.method !== "POST")
                 return text("POST only\n", 405);
             // Fail closed: a missing/wrong secret token is 401, never routed.
-            if (!tokenMatches(req.headers.get("x-telegram-bot-api-secret-token") ?? "", secretToken)) {
+            if (!secretEquals(req.headers.get("x-telegram-bot-api-secret-token"), secretToken)) {
                 return text("invalid secret token\n", 401);
             }
             const body = await readBodyCapped(req, MAX_UPDATE_BYTES);
@@ -313,54 +208,52 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 }
                 return new Response(null, { status: 200 });
             }
-            {
-                const session = r.session ?? 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. Only when the RESOLVED target is the message's own chat+thread: a route that
-                // redirects elsewhere must not carry a reply_parameters that resolves in the wrong place (fail, or
-                // quote a same-id message there). Compare VALUES, not whether the route touched the field — a route
-                // that explicitly returns the same chat/thread still quotes.
-                const threadId = r.threadId ?? m.message_thread_id;
-                const sameTarget = String(chatId) === String(m.chat.id) && threadId === m.message_thread_id;
-                // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the
-                // run it stops. `/stop@otherbot` is not ours; a bare `/stop` always is. Awaited before the ACK:
-                // dispatch + one sendMessage is fast, and a delivery failure logs instead of failing the webhook.
-                const stopMatch = /^\/stop(?:@([A-Za-z0-9_]+))?$/i.exec(messageText(m).trim());
-                if (stopMatch && (!stopMatch[1] || stopMatch[1].toLowerCase() === mentionName?.toLowerCase())) {
-                    const feedback = await dispatchStop(control, session, "[telegram]");
-                    const target = {
-                        chatId,
-                        threadId,
-                        replyTo: m.chat.type !== "private" && sameTarget ? m.message_id : undefined,
-                    };
-                    await sendMessage(apiBaseUrl, botToken, target, 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.
-                    submit({
-                        id: `${update.update_id}`,
-                        session,
-                        placeKey,
-                        baseText,
-                        chatId,
-                        threadId,
-                        replyTo: m.chat.type !== "private" && sameTarget ? m.message_id : undefined,
-                        imageFileIds,
-                        fileIds,
-                    }, true);
-                }
+            const session = r.session ?? 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. Only when the RESOLVED target is the message's own chat+thread: a route that
+            // redirects elsewhere must not carry a reply_parameters that resolves in the wrong place (fail, or
+            // quote a same-id message there). Compare VALUES, not whether the route touched the field — a route
+            // that explicitly returns the same chat/thread still quotes.
+            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. Awaited before the ACK: dispatch + one sendMessage is fast, and a delivery failure
+            // logs instead of failing the webhook. Read AFTER the route, on the route's own session: the route
+            // is both the gate (a route that ignores this chat must not have the bot abort or answer in it) and
+            // the session authority (a route that remaps `session` would otherwise have its stop abort a
+            // session nobody runs). The default route summons an ADDRESSED `/stop` in a group for this reason:
+            // the general slash-command refusal would leave it buffered as discussion while the run kept going.
+            // An unaddressed one is not a command at all (see telegramStop) and never reaches here.
+            if (telegramStop(update, { botUsername: mentionName, botId })) {
+                const feedback = await dispatchStop(control, session, "[telegram]");
+                await 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}`,
+                    session,
+                    placeKey,
+                    baseText,
+                    chatId,
+                    threadId,
+                    replyTo,
+                    imageFileIds,
+                    fileIds,
+                }, true);
             }
             return new Response(null, { status: 200 });
         };
         // Test/observability seam: await the fire-and-forget turns this handler enqueues. Inert in production
         // (nothing reads it; the runtime never drains — see turn-queue), it lets a test await a turn
         // deterministically instead of polling for side effects to settle.
-        handler.turnsIdle = () => queue.idle();
+        handler.turnsIdle = () => runner.idle();
         return { "POST /telegram": handler };
     };
 }

package/dist/channels/wait-health.js

@@ -1,8 +1,11 @@
 /**
- * Readiness probe shared by the webhook registrars (telegram setWebhook, lark config PATCH): both
- * platforms VERIFY the URL at registration time, and a fresh deploy's container or a fresh tunnel's
- * DNS is not routable for some seconds — registering before the server actually serves would fail.
- * Tracking real readiness (not a fixed timer) is what fixes that race.
+ * Readiness probe for a server THIS process can reach directly — the local port `deploy docker --run`
+ * just published, and the live probes' own origins.
+ *
+ * NOT a probe for a public URL a platform must reach: a freshly minted hostname (a quick tunnel, a
+ * fresh deploy) is routinely unreachable from here for a minute or more while the platform reaches it
+ * fine, and polling it hard from t+0 makes that worse (#421). The webhook registrars therefore let the
+ * platform's own URL verification be the probe, retried, instead of gating on this.
  */
 import { setTimeout as sleep } from "node:timers/promises";
 /**

package/dist/cli/add-feishu.js

@@ -12,7 +12,7 @@
 import { readFile } from "node:fs/promises";
 import { isCancel, log as clackLog, password, text as clackText } from "@clack/prompts";
 import { bootstrapFeishuVerificationToken } from "../channels/feishu/bootstrap-token.js";
-import { FEISHU_GROUP_CONTEXT_SCOPE, FEISHU_CONTEXT_ONBOARDING_SCOPES, FEISHU_MESSAGE_READ_SCOPE, scopeSatisfied, } from "../channels/feishu/setup-mode.js";
+import { FEISHU_GROUP_CONTEXT_SCOPE, FEISHU_CONTEXT_ONBOARDING_SCOPES, FEISHU_MESSAGE_READ_SCOPE, feishuAppAddons, scopeSatisfied, } from "../channels/feishu/setup-mode.js";
 import { cloudFor } from "../channels/feishu/cloud.js";
 import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError, } from "../channels/feishu/feishu-api.js";
 import { registerFeishuApp } from "../channels/feishu/register-app.js";
@@ -233,16 +233,9 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         const app = await registerFeishuApp({
             name: "{user}'s agent", // the platform expands {user} to the confirming user's name; editable on the page
             desc: "Served by fastagent",
-            // The agent template alone is not enough to SERVE: v7 config PATCHes (webhook registration and
-            // context-aware group scope setup) demand application:application:patch, and the app must subscribe
-            // the receive event. Addons merge those BASE capabilities onto the confirm page; sensitive group
+            // The agent template alone is not enough to SERVE (see feishuAppAddons). Sensitive group
             // permission approval and version publishing remain explicit console work.
-            addons: {
-                ...(ingress === "webhook" || (groupBehavior.behavior === "context" && groupBehavior.explicit)
-                    ? { scopes: { tenant: ["application:application:patch"] } }
-                    : {}),
-                events: { items: { tenant: ["im.message.receive_v1"] } },
-            },
+            addons: feishuAppAddons(),
             onVerificationUrl: ({ url, expiresInS }) => {
                 console.error(`\n  Opening the confirmation link in your browser (or open it in Feishu / render it as a QR code) — valid for ${Math.round(expiresInS / 60)} minutes:\n\n    ${url}\n\n  waiting for confirmation… (keep this running — the credentials are delivered here)`);
                 openExternalUrl(url); // best-effort, like `login` — the URL above is the fallback

package/dist/cli/add-slack.js

@@ -1,7 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
-import { waitForHealth } from "../channels/wait-health.js";
 import { dotEnvPath, parseEnvContent } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
 import { installProxyFetch } from "../proxy.js";
@@ -27,7 +26,7 @@ export async function onboardSlackInternalApp(input) {
         throw new Error("`add slack` needs an interactive terminal for internal-app creation and OAuth — " +
             "re-run in a terminal, or pass --no-onboard to scaffold only");
     }
-    let state = await readSlackOnboardingState(input.stateRoot);
+    let state = readSlackOnboardingState(input.stateRoot);
     const resumed = state !== undefined;
     if (input.replaceConfig && !state) {
         throw new Error("--replace-config found no local Slack onboarding state on this machine — nothing to replace. " +
@@ -41,14 +40,7 @@ export async function onboardSlackInternalApp(input) {
                 return new Map();
             throw error;
         });
-        const missingRuntime = [
-            "SLACK_BOT_TOKEN",
-            "SLACK_BOT_REFRESH_TOKEN",
-            "SLACK_BOT_TOKEN_EXPIRES_AT",
-            "SLACK_CLIENT_ID",
-            "SLACK_CLIENT_SECRET",
-            "SLACK_SIGNING_SECRET",
-        ].filter((name) => !((process.env[name] ?? env.get(name))?.trim() ?? ""));
+        const missingRuntime = ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"].filter((name) => !((process.env[name] ?? env.get(name))?.trim() ?? ""));
         if (missingRuntime.length > 0) {
             throw new Error(`Slack app ${state.appId ?? "(unknown)"} is installed but ${dotEnvPath(input.target)} is missing ` +
                 `${missingRuntime.join(", ")} — ` +
@@ -84,7 +76,7 @@ export async function onboardSlackInternalApp(input) {
             if (!configToken.startsWith("xoxe.") || !configRefreshToken.startsWith("xoxe-")) {
                 throw new Error("invalid Slack configuration token prefix (expected xoxe. access + xoxe- refresh)");
             }
-            await writeSlackOnboardingState(input.stateRoot, {
+            writeSlackOnboardingState(input.stateRoot, {
                 ...state,
                 configToken,
                 configRefreshToken,
@@ -116,11 +108,11 @@ export async function onboardSlackInternalApp(input) {
             configToken,
             configRefreshToken,
         });
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
     }
     else if (input.groupBehavior.explicit && !state.appId) {
         state = { ...state, groupBehavior: input.groupBehavior.behavior };
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
     }
     if (state.createAttemptedAt && !state.appId) {
         throw new Error(`a prior Slack app creation attempt at ${state.createAttemptedAt} returned no app ID — ` +
@@ -144,6 +136,7 @@ export async function onboardSlackInternalApp(input) {
             action = answer;
         }
         if (action === "replace-config") {
+            console.error(`[fastagent] generate a fresh App Configuration Token pair at ${CONFIG_TOKEN_URL}`);
             openExternalUrl(CONFIG_TOKEN_URL);
             state = {
                 ...state,
@@ -154,7 +147,7 @@ export async function onboardSlackInternalApp(input) {
             if (!state.configToken.startsWith("xoxe.") || !state.configRefreshToken.startsWith("xoxe-")) {
                 throw new Error("invalid Slack configuration token prefix (expected xoxe. access + xoxe- refresh)");
             }
-            await writeSlackOnboardingState(input.stateRoot, state);
+            writeSlackOnboardingState(input.stateRoot, state);
         }
     }
     const server = await startSlackSetupServer();
@@ -167,20 +160,16 @@ export async function onboardSlackInternalApp(input) {
     const redirectUrl = `${tunnel.url}${server.redirectPath}`;
     console.error(`[fastagent] temporary Slack setup tunnel ready → ${tunnel.url}`);
     try {
-        if (!(await waitForHealth(`${tunnel.url}/health`, 45_000, 500))) {
-            throw new Error("the temporary Slack setup tunnel did not become reachable; no app was created");
-        }
+        // No local readiness probe: Slack challenges requestUrl from ITS network during app creation, and
+        // that is the reachability that matters (#421) — this machine often cannot reach a fresh tunnel
+        // hostname for a minute. onboardSlackApp retries the create while Slack cannot verify it yet.
         await onboardSlackApp({ stateRoot: input.stateRoot, state, requestUrl, redirectUrl }, {
             note: (message) => clackLog.info(message),
             openUrl: openExternalUrl,
             waitForOAuth: () => server.waitForOAuth(),
-            writeRuntimeSecrets: async ({ botToken, botRefreshToken, botTokenExpiresAt, clientId, clientSecret, signingSecret, }) => {
+            writeRuntimeSecrets: async ({ botToken, signingSecret }) => {
                 const values = {
                     ...(botToken ? { SLACK_BOT_TOKEN: botToken } : {}),
-                    ...(botRefreshToken ? { SLACK_BOT_REFRESH_TOKEN: botRefreshToken } : {}),
-                    ...(botTokenExpiresAt ? { SLACK_BOT_TOKEN_EXPIRES_AT: String(botTokenExpiresAt) } : {}),
-                    ...(clientId ? { SLACK_CLIENT_ID: clientId } : {}),
-                    ...(clientSecret ? { SLACK_CLIENT_SECRET: clientSecret } : {}),
                     ...(signingSecret ? { SLACK_SIGNING_SECRET: signingSecret } : {}),
                 };
                 if (Object.keys(values).length > 0) {
@@ -188,9 +177,8 @@ export async function onboardSlackInternalApp(input) {
                 }
             },
         });
-        console.error(`[fastagent] Slack app installed; rotating bot credentials and Signing Secret written to ${dotEnvPath(input.target)}`);
-        console.error(`[fastagent] run \`fastagent dev --tunnel\` next — FastAgent will rotate the config token and ` +
-            "replace the temporary Events API URL automatically");
+        // What happened, once. What to do next is `add`'s "next steps" block.
+        console.error(`[fastagent] Slack app installed; credentials written to ${dotEnvPath(input.target)}`);
     }
     finally {
         tunnel.close();

package/dist/cli/commands/add.d.ts

@@ -1,7 +1,6 @@
 import { type ChannelKind } from "../../scaffold/add-channel.ts";
 /** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */
 export declare function runAddChannel(channelKind: ChannelKind, dirArg: string, opts: {
-    createApp?: boolean;
     ingress?: string;
     groupBehavior?: string;
     onboard?: boolean;