@fastagent-sh/fastagent 0.20.0 → 0.21.1

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,11 +22,11 @@
  * 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, telegramStop, } from "./parse.js";
@@ -34,20 +34,13 @@ 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 { commitAnsweredTurn } from "../kit/turn-store.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, 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
@@ -111,152 +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);
-                if (decision === "exceeded") {
-                    // Started the ceiling's worth of times without finishing (turn-store.ts MAX_TURN_ATTEMPTS) —
-                    // tell the asker (reusing its ⏳ notice if any), drop it.
-                    notifyDropped(rec);
-                    return;
-                }
-                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;
+                }, (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(() => { });
                 }
-                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 = `${discussionBlock(recent)}${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,
-                    }, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey: 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);
@@ -331,7 +236,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             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({
+                runner.submit({
                     id: `${update.update_id}`,
                     session,
                     placeKey,
@@ -348,7 +253,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
         // 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";
@@ -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(", ")} — ` +
@@ -168,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) {
@@ -189,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;

package/dist/cli/commands/add.js

@@ -8,9 +8,9 @@ import { join, relative, resolve } from "node:path";
 import { isCancel, select } from "@clack/prompts";
 import { onboardFeishuCloudApp } from "../add-feishu.js";
 import { dotEnvPath, loadDotEnv } from "../../env.js";
-import { resolveStateRoot, SECRETS_DIRNAME, isUnderDir, displayPath, exists } from "../../paths.js";
+import { resolveStateRoot, SECRETS_DIRNAME, isUnderDir, displayPath } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
-import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, } from "../../scaffold/add-channel.js";
+import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, scaffoldCompanionTools, } from "../../scaffold/add-channel.js";
 import { vendorSkill } from "../../scaffold/vendor-skill.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 /** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */
@@ -33,41 +33,25 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     const inAgent = (p) => (agentFromCwd === undefined ? p : join(agentFromCwd, p));
     const envPath = dotEnvPath(target);
     const envLabel = isUnderDir(envPath, target) ? inAgent(relative(target, envPath)) : envPath;
-    // App creation is not a flag — it is what `add feishu` IS (the scan-to-create flow is the default
-    // and only path there). The retired --create-app spelling gets a pointer, not silence.
-    if (opts.createApp) {
-        if (channelKind === "feishu") {
-            console.error(`[fastagent] note: --create-app is retired — \`add feishu\` creates the app by default`);
-        }
-        else if (channelKind === "lark") {
-            failStartup(new Error("--create-app is retired — `add lark` now opens the developer console and guides credential setup by default"));
-        }
-        else {
-            failStartup(new Error("--create-app is retired — app creation is the default behavior of `add feishu`"));
-        }
-    }
-    // Preconditions before the write, so a refusal is side-effect-free. slack/feishu/lark are exceptions:
-    // their add is scaffold + ONBOARD THE APP, so an existing scaffold skips the write and continues (a
-    // failed/cancelled app or OAuth flow must be re-runnable without hand-deleting authored glue).
+    // An existing channel file is authored glue: kept, never rewritten. The add continues past it — the
+    // companion tools below are refreshed, and slack/feishu/lark resume a failed/cancelled app or OAuth
+    // flow — so re-running `add <kind>` never requires hand-deleting the glue.
     const file = join(target, "channels", `${channelKind}.ts`);
-    const slackToolFile = join(target, "tools", "slack-send.ts");
-    const slackToolExisted = channelKind === "slack" ? await exists(slackToolFile) : false;
     const existsAlready = await channelExists(target, channelKind).catch(failStartup);
     const ingress = await resolveIngress(channelKind, file, existsAlready, opts.ingress);
     const groupBehavior = await resolveGroupBehavior(channelKind, opts.groupBehavior);
     if (existsAlready) {
-        if (channelKind !== "slack" && channelKind !== "feishu" && channelKind !== "lark") {
-            failStartup(new Error(`${relative(target, file)} already exists — edit it, or remove it to re-scaffold`));
-        }
         console.error(`[fastagent] ${relative(target, file)} already exists — keeping it`);
     }
     else {
         await assertChannelReady(target).catch(failStartup);
-        await scaffoldChannel(target, channelKind, { ingress, groupBehavior: groupBehavior.behavior }).catch(failStartup);
+        await scaffoldChannel(target, channelKind, { ingress }).catch(failStartup);
         console.error(`[fastagent] created ${relative(target, file)}`);
-        if (channelKind === "slack") {
-            console.error(`[fastagent] ${slackToolExisted ? "kept existing" : "created"} ${relative(target, slackToolFile)}`);
-        }
+    }
+    // Companion tools are the package's, not authored glue: written on every add, so an upgraded
+    // package reaches an existing agent by re-running `add <kind>` (slack: `--no-onboard` skips the prompts).
+    for (const tool of await scaffoldCompanionTools(target, channelKind).catch(failStartup)) {
+        console.error(`[fastagent] wrote ${relative(target, tool)}`);
     }
     if (await appendChannelEnv(target, channelKind, ingress).catch(failStartup)) {
         console.error(`[fastagent] added ${channelKind} env vars to ${inAgent(join(SECRETS_DIRNAME, ".env.example"))}`);
@@ -93,9 +77,9 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     const env = setup.env;
     const steps = channelKind === "slack" && opts.onboard !== false
         ? [
-            `Slack internal app created/configured/installed through OAuth; runtime credentials are in ${envLabel}`,
-            "run fastagent dev --tunnel to replace the temporary Events API URL automatically",
-            "invite the app to every channel it should read",
+            // No line about the Request URL: the `dev --tunnel` line below is the whole instruction, and
+            // FastAgent sets that URL itself when the agent first runs.
+            "invite the app to each channel it should read",
             "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
         ]
         : setup.steps;
@@ -137,7 +121,7 @@ export async function runAddChannel(channelKind, dirArg, opts) {
         console.error(`    fastagent dev            # no public URL or tunnel required`);
     }
     else if (channelKind === "slack") {
-        console.error(`    fastagent dev --tunnel   # serve locally; ${opts.onboard === false ? "print the Request URL for manual Slack setup" : "auto-update the onboarded Slack Request URL"}`);
+        console.error(`    fastagent dev --tunnel   # ${opts.onboard === false ? "serve locally + print the URL to paste into the Slack app's Event Subscriptions" : "start the agent — then message it in Slack"}`);
     }
     else if (channelKind === "github") {
         console.error(`    fastagent dev --tunnel   # serve locally + print the URL for manual GitHub webhook setup`);
@@ -183,16 +167,20 @@ async function resolveIngress(kind, file, existsAlready, raw) {
     }
     const answer = await select({
         message: `How should ${kind === "feishu" ? "Feishu" : "Lark"} deliver events?`,
+        // The default must match the non-interactive branch above. Webhook is the cheaper side to be
+        // wrong on: its credentials are a superset of websocket's (App ID/Secret plus the Verification
+        // Token), and that token has no read API — a websocket app moving to webhook must re-acquire it.
+        initialValue: "webhook",
         options: [
-            {
-                value: "websocket",
-                label: "WebSocket long connection",
-                hint: "no public URL; requires an always-on process",
-            },
             {
                 value: "webhook",
                 label: "Webhook endpoint",
-                hint: "supports scale-to-zero; requires a public HTTPS URL",
+                hint: "works on every deploy target; supports scale-to-zero; requires a public HTTPS URL",
+            },
+            {
+                value: "websocket",
+                label: "WebSocket long connection",
+                hint: "no public URL; needs an always-on process (not on AgentCore)",
             },
         ],
     });

package/dist/cli/commands/chat.js

@@ -1,17 +1,11 @@
 /** `fastagent chat [dir]`: open the SAME assembled agent in pi's interactive TUI. */
-import { resolve } from "node:path";
-import { loadDotEnv } from "../../env.js";
-import { installProxyFetch } from "../../proxy.js";
-import { failStartup, placementOrExit } from "../fail.js";
-import { resolveFirstRunModel } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { enterAgentCommand } from "../shared.js";
 export async function runChat(dirArg, opts) {
-    const placement = placementOrExit(resolve(dirArg));
-    loadDotEnv(placement.agentDir);
-    installProxyFetch(); // model calls (and the login dialog) must go through the proxy too
-    // First-run funnel, FULL picker: chat authenticates through fastagent's credential store like every
-    // other command (the shared session builder injects it — see engines/pi/session-builder.ts), so the
-    // credential-annotated catalog and inline login apply here too.
-    await resolveFirstRunModel(placement.agentDir, { model: opts.model, authPath: opts.authPath });
+    // Chat authenticates through fastagent's credential store like every other command (the shared
+    // session builder injects it — see engines/pi/session-builder.ts), so the first-run picker and its
+    // inline login apply here too.
+    const placement = await enterAgentCommand(dirArg, opts);
     // Run the chat process AT the workspace: pi resolves a session's cwd as `header.cwd ?? process.cwd()`,
     // so aligning process.cwd() with the workspace keeps a cwd-less session on it. Paths are absolute.
     process.chdir(placement.workspace);

package/dist/cli/commands/deploy/agentcore.d.ts

@@ -0,0 +1,2 @@
+import { type HostDeploy } from "./shared.ts";
+export declare const agentcoreHost: HostDeploy;