@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/cli/add-feishu.js

@@ -0,0 +1,366 @@
+/**
+ * `fastagent add feishu|lark` app onboarding — the cloud-facing half of runAdd, kept out of cli.ts
+ * (which self-executes on import), mirroring models-view.ts/auth-view.ts. The POLICY already lives in
+ * testable modules (register-app.ts, bootstrap-token.ts, lark/onboard.ts); this layer is the terminal
+ * wiring: clack prompts, .env staging, browser opens, progress lines.
+ *
+ * Feishu (scan-to-create): the device flow creates the app and persists App ID/Secret at the
+ * irreversible boundary. WebSocket stops there; webhook additionally captures the Verification Token
+ * over a throwaway tunnel. Lark uses the unbound launcher + credential validation, then either stops
+ * for WebSocket or probes the same webhook/token bootstrap with the config-route-404 manual fallback.
+ */
+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 { cloudFor } from "../channels/feishu/cloud.js";
+import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError, } from "../channels/feishu/feishu-api.js";
+import { registerFeishuApp } from "../channels/feishu/register-app.js";
+import { onboardLarkApp } from "../channels/lark/onboard.js";
+import { dotEnvPath, parseEnvContent } from "../env.js";
+import { openExternalUrl } from "../open-url.js";
+import { appendChannelDotEnv } from "../scaffold/add-channel.js";
+import { startCloudflareTunnel } from "../tunnel.js";
+export async function configureGroupBehavior(input) {
+    const { kind, appId, apiBase, api, behavior, explicit } = input;
+    const note = input.note ?? ((message) => console.error(message));
+    const openUrl = input.openUrl ?? openExternalUrl;
+    let scopes;
+    let inspected = true;
+    try {
+        scopes = await api.listAppScopes();
+    }
+    catch (error) {
+        note(`[fastagent] warn: could not inspect ${kind} group-message permission: ${String(error)} — check Permissions & Scopes manually`);
+        inspected = false;
+        scopes = [];
+    }
+    const granted = (name) => scopes.some((scope) => scope.name === name && scope.grantStatus === 1 && (scope.type === undefined || scope.type === "tenant"));
+    // Same type filter as `granted`: a user-type entry is not the tenant scope this path needs, so
+    // treating one as "on the app" would report an approval that can never arrive and skip the PATCH
+    // that would actually add it.
+    const onApp = (name) => scopes.some((scope) => scope.name === name && (scope.type === undefined || scope.type === "tenant"));
+    // Both halves of the recommended path: delivery (the platform pushes un-mentioned group messages)
+    // and reading a quoted message (so a thread's opening ask carries what it replies to).
+    // The read capability has two spellings and `im:message` is the superset, so an app holding it needs
+    // nothing added — asking anyway would cost the author a second tenant-admin approval round.
+    const missing = FEISHU_CONTEXT_ONBOARDING_SCOPES.filter((entry) => !scopeSatisfied(entry, granted));
+    const missingNames = missing.map((entry) => entry.request);
+    if (behavior === "mentions") {
+        if (!inspected) {
+            const permissionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/permission`;
+            note(`[fastagent] mention-only scope state could not be verified — check Permissions before publishing. Opening ${permissionUrl}`);
+            openUrl(permissionUrl);
+            return { publishReady: false };
+        }
+        if (granted(FEISHU_GROUP_CONTEXT_SCOPE)) {
+            const permissionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/permission`;
+            note(`[fastagent] warn: mention-only was selected, but ${FEISHU_GROUP_CONTEXT_SCOPE} is already granted — remove it before publishing a new version to restore least-privilege platform delivery. Opening ${permissionUrl}`);
+            openUrl(permissionUrl);
+            return { publishReady: false };
+        }
+        note(`[fastagent] group behavior: mention-only — bare replies in the Agent's threads and group context buffering are disabled. ` +
+            `Add ${FEISHU_MESSAGE_READ_SCOPE} by hand if you want an @mention to carry the message it quotes`);
+        return { publishReady: true };
+    }
+    note(`[fastagent] group behavior: context-aware (recommended) — ${kind} will deliver all group messages; ` +
+        `FastAgent invokes @Agent, answers bare replies in threads it takes part in, and durably buffers ` +
+        `other discussion. ${FEISHU_GROUP_CONTEXT_SCOPE} (delivery) is required; ${FEISHU_MESSAGE_READ_SCOPE} ` +
+        `(reading a quoted message) is requested with it — without it a quoted message degrades to a marker`);
+    if (missing.length === 0) {
+        note(`[fastagent] ${FEISHU_CONTEXT_ONBOARDING_SCOPES.map((entry) => entry.request).join(" + ")} are already granted`);
+        return { publishReady: true };
+    }
+    const permissionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/permission`;
+    // A missing scope is in one of two states, and they need different actions: already on the app but
+    // not yet approved (nothing to add — wait for the admin), or absent from the draft entirely.
+    // Same superset rule as `missing`: a draft already requesting `im:message` is awaiting approval, not
+    // missing something to add.
+    const awaitingApproval = missing.filter((entry) => scopeSatisfied(entry, onApp)).map((entry) => entry.request);
+    const toRequest = missing.filter((entry) => !scopeSatisfied(entry, onApp)).map((entry) => entry.request);
+    if (toRequest.length === 0) {
+        note(`[fastagent] ${awaitingApproval.join(" + ")} awaiting approval — complete tenant-admin approval before publishing. Opening ${permissionUrl}`);
+        openUrl(permissionUrl);
+        return { publishReady: false };
+    }
+    if (!explicit) {
+        // Defaulted, not chosen: report the gap and how to opt in, but leave the app's requested
+        // permission set untouched (a scripted re-run must not silently escalate a mention-only app).
+        // Name what is ACTUALLY missing: the common upgrade has the delivery scope already granted and
+        // only the read scope absent, and pointing at a granted permission sends the author looking in
+        // the wrong place.
+        note(`[fastagent] ${missingNames.join(" + ")} not granted (or could not be verified) — group behavior was ` +
+            `defaulted, so nothing was requested. Re-run with --group-behavior context to add ${missing.length > 1 ? "them" : "it"} ` +
+            `to the app draft, or --group-behavior mentions to stay least-privilege: ${permissionUrl}`);
+        return { publishReady: false };
+    }
+    try {
+        await api.addAppScopes(appId, toRequest);
+        note(`[fastagent] added ${toRequest.join(" + ")} to the app draft — complete tenant-admin approval before publishing. Opening ${permissionUrl}`);
+    }
+    catch (error) {
+        note(`[fastagent] warn: could not add ${toRequest.join(" + ")} automatically: ${String(error)} — add it manually before publishing. Opening ${permissionUrl}`);
+    }
+    openUrl(permissionUrl);
+    return { publishReady: false };
+}
+/**
+ * Create or resume the platform app behind `add feishu` / `add lark`. `target` is the AGENT DIR;
+ * credentials land in its `.env` — whose real path is {@link dotEnvPath}, printed rather than spelled,
+ * because `FASTAGENT_SECRETS_DIR` moves it and a hardcoded `.secrets/.env` would name a file this run
+ * did not write. Returns credentials for the
+ * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
+ * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
+ * irreversible and must not wait for the caller). Throws on refusal (a non-interactive lark run);
+ * the caller surfaces that as a startup failure.
+ */
+export async function onboardFeishuCloudApp(target, kind, ingress = "webhook", groupBehavior = { behavior: "context", explicit: false }) {
+    const env = dotEnvPath(target); // the file actually written — never the default spelling
+    const { envPrefix, apiBase, capabilities } = cloudFor(kind);
+    const requiredNames = [
+        `${envPrefix}_APP_ID`,
+        `${envPrefix}_APP_SECRET`,
+        ...(ingress === "webhook" ? [`${envPrefix}_VERIFICATION_TOKEN`] : []),
+    ];
+    const existing = await activeDotEnvValues(target, requiredNames);
+    if (Object.keys(existing).length === requiredNames.length) {
+        console.error(`[fastagent] ${requiredNames.join("/")} already set in ${env} — keeping them`);
+        // WebSocket still needs its console mode/publish guidance. A complete webhook can skip the rest of
+        // onboarding, but group visibility must still be inspected/configured on every explicit re-run.
+        if (ingress === "webhook") {
+            const appId = existing[`${envPrefix}_APP_ID`];
+            const appSecret = existing[`${envPrefix}_APP_SECRET`];
+            await configureGroupBehavior({
+                kind,
+                appId,
+                apiBase,
+                api: createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret }),
+                behavior: groupBehavior.behavior,
+                explicit: groupBehavior.explicit,
+            });
+            return undefined;
+        }
+    }
+    if (capabilities.appCreation === "scan-to-create") {
+        await createFeishuAppFlow(target, existing, ingress, groupBehavior);
+        return undefined;
+    }
+    // guided-console (lark): the intl cloud cannot complete the bound device flow — collect + validate.
+    if (!(process.stdin.isTTY && process.stdout.isTTY) &&
+        !(existing[`${envPrefix}_APP_ID`] && existing[`${envPrefix}_APP_SECRET`])) {
+        throw new Error("`add lark` needs an interactive terminal to onboard the Lark app credentials — re-run it in a terminal");
+    }
+    const credentials = await onboardLarkApp({
+        openUrl: openExternalUrl,
+        note: (message) => clackLog.info(message),
+        async prompt(message, opts) {
+            const result = opts?.hidden ? await password({ message }) : await clackText({ message });
+            return isCancel(result) ? undefined : result;
+        },
+    }, {
+        existing,
+        ingress,
+        groupBehavior: groupBehavior.behavior,
+        verifyCredentials: async (appId, appSecret) => {
+            await createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret }).verifyCredentials();
+            console.error(`[fastagent] Lark App ID / Secret verified`);
+        },
+        bootstrapWebhook: async (appId, appSecret) => {
+            const api = createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret });
+            console.error(`[fastagent] trying Lark's webhook-mode + Verification-Token bootstrap (temporary tunnel)…`);
+            try {
+                const token = await bootstrapFeishuVerificationToken({
+                    api,
+                    appId,
+                    kind: "lark",
+                    startTunnel: (port) => startCloudflareTunnel(port),
+                    onTunnelReady: (url) => console.error(`[fastagent] temporary tunnel ready → ${url}; registering webhook mode now…`),
+                    onPatchRetry: ({ error, attempt, attempts, retryMs }) => console.error(`[fastagent] Lark could not validate the fresh tunnel yet (${String(error)}); retrying PATCH ${attempt + 1}/${attempts} in ${Math.round(retryMs / 1000)}s…`),
+                    // A route-level 404 is definitive, not edge weather: fall back immediately. Retry only
+                    // actual edge/network weather; scope/auth/config failures remain immediate.
+                    shouldRetryPatch: (error) => !isFeishuConfigApiMissing(error) && isTransientFeishuRegistrationError(error),
+                });
+                console.error(`[fastagent] Lark Verification Token captured; Subscription mode changed to webhook in the app draft`);
+                return { token };
+            }
+            catch (error) {
+                if (!isFeishuConfigApiMissing(error))
+                    throw error;
+                const manualReason = "This Lark app returned HTTP 404 for the application-config API, so automatic mode/token bootstrap is unavailable.";
+                console.error(`[fastagent] ${manualReason}`);
+                return { manualReason };
+            }
+        },
+    });
+    await configureGroupBehavior({
+        kind: "lark",
+        appId: credentials.LARK_APP_ID,
+        apiBase,
+        api: createFeishuApi({
+            kind: "lark",
+            baseUrl: apiBase,
+            appId: credentials.LARK_APP_ID,
+            appSecret: credentials.LARK_APP_SECRET,
+        }),
+        behavior: groupBehavior.behavior,
+        explicit: groupBehavior.explicit,
+    });
+    return Object.fromEntries(Object.entries(credentials).filter((entry) => typeof entry[1] === "string"));
+}
+/**
+ * The scan-to-create flow `add feishu` runs by default. The device-authorization grant
+ * creates a pre-configured agent app (bot capability, messaging scopes, event subscriptions) when the
+ * user confirms a link, then persists App ID/Secret at the irreversible boundary. That completes
+ * WebSocket credentials; webhook continues through challenge-captured Token persistence. The throwaway
+ * Request URL is later replaced by `dev --tunnel` / `deploy --run`.
+ *
+ * Feishu is the reference cloud and the only kind that runs this BOUND device flow. Lark is an explicit
+ * compatibility profile: its lagging control plane uses the unbound launcher + guided credentials,
+ * then probes the canonical token/mode bootstrap with a manual fallback.
+ */
+async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
+    const env = dotEnvPath(target); // the file actually written — never the default spelling
+    const { apiBase } = cloudFor("feishu");
+    let appId = existing.FEISHU_APP_ID;
+    let appSecret = existing.FEISHU_APP_SECRET;
+    if (appId && appSecret) {
+        console.error(ingress === "webhook"
+            ? `[fastagent] resuming Feishu app ${appId} from ${env} to capture its missing Verification Token`
+            : `[fastagent] reusing Feishu app ${appId} from ${env} for WebSocket ingress`);
+    }
+    else {
+        console.error(`[fastagent] creating the Feishu app (confirm in the app)…`);
+        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
+            // 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"] } },
+            },
+            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
+            },
+        });
+        console.error(`[fastagent] app created: ${app.appId}${app.tenantBrand ? ` (${app.tenantBrand} tenant)` : ""}`);
+        // A cross-brand confirmation should be impossible (each confirm page refuses the other brand's
+        // code) — but if the platform ever reports one, the credentials would land in the WRONG kind's env
+        // namespace and serve the wrong cloud. Fail visibly instead of writing them.
+        if (app.tenantBrand && app.tenantBrand !== "feishu") {
+            throw new Error(`the confirming account is a ${app.tenantBrand} tenant, but this is \`add feishu\` — run \`fastagent add ${app.tenantBrand}\` instead`);
+        }
+        appId = app.appId;
+        appSecret = app.appSecret;
+        // IRREVERSIBLE BOUNDARY: the remote app now exists and its one-time Secret is in memory. Persist
+        // both before any config read, temporary tunnel, or Token bootstrap can be interrupted. Partial old
+        // lines are overwritten because these newly-minted credentials are authoritative as one pair.
+        const staged = {
+            FEISHU_APP_ID: appId,
+            FEISHU_APP_SECRET: appSecret,
+            ...(ingress === "webhook" ? { FEISHU_VERIFICATION_TOKEN: "" } : {}),
+        };
+        await appendChannelDotEnv(target, "feishu", staged, Object.keys(staged), ingress);
+        console.error(ingress === "webhook"
+            ? `[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to ${env} before Token bootstrap`
+            : `[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to ${env}`);
+    }
+    const groupSetup = await configureGroupBehavior({
+        kind: "feishu",
+        appId,
+        apiBase,
+        api: createFeishuApi({ kind: "feishu", baseUrl: apiBase, appId, appSecret }),
+        behavior: groupBehavior.behavior,
+        explicit: groupBehavior.explicit,
+    });
+    if (ingress === "websocket") {
+        const versionUrl = `${apiBase}/app/${appId}/version`;
+        if (groupSetup.publishReady) {
+            console.error(`[fastagent] WebSocket ingress needs no Verification Token, Encrypt Key, Request URL, or tunnel. ` +
+                `Choose long connection in Events & Callbacks, then CREATE + PUBLISH a version. Opening ${versionUrl}`);
+            openExternalUrl(versionUrl);
+        }
+        else {
+            console.error(`[fastagent] WebSocket ingress needs no Verification Token, Encrypt Key, Request URL, or tunnel. ` +
+                `Choose long connection in Events & Callbacks, finish the permission work opened above, then CREATE + PUBLISH: ${versionUrl}`);
+        }
+        return;
+    }
+    // The webhook channel authenticates plaintext events by the platform-generated Verification Token.
+    // Try the cheap read first (the v6 detail MAY someday return `encryption`), then the real path: the
+    // token's only programmatic delivery is the url_verification challenge during registration — capture
+    // it over a throwaway tunnel (bootstrap-token.ts). Failing both is a one-line manual copy; the staged
+    // ID/Secret pair makes a re-run resume this App rather than mint another one.
+    const tokenVar = "FEISHU_VERIFICATION_TOKEN";
+    const api = createFeishuApi({ baseUrl: apiBase, appId, appSecret });
+    let token;
+    let webhookModeChanged = false;
+    try {
+        const cfg = await api.getAppConfig(appId);
+        token = cfg.verificationToken;
+    }
+    catch {
+        /* the read surface is best-effort — the bootstrap below is the real path */
+    }
+    if (!token) {
+        console.error(`[fastagent] capturing the Verification Token — a throwaway webhook registration delivers it (spinning up a temporary tunnel; can take a few minutes on a slow edge)…`);
+        try {
+            token = await bootstrapFeishuVerificationToken({
+                api,
+                appId,
+                startTunnel: (port) => startCloudflareTunnel(port),
+            });
+            webhookModeChanged = true;
+            console.error(`[fastagent] Verification Token captured`);
+        }
+        catch (e) {
+            // Transient tunnel weather is the usual cause. Do NOT suggest re-running `add feishu` as a new
+            // scan: the staged pair makes the re-run resume THIS app; manual copy completes it too.
+            console.error(`[fastagent] warn: could not capture the Verification Token: ${String(e)} — usually a transient tunnel issue; finish this app with the manual copy below`);
+        }
+    }
+    if (token) {
+        // Persist the second credential stage immediately too — opening the publish page and generic
+        // scaffold finalization happen only after the complete runtime credential set is durable.
+        const staged = await appendChannelDotEnv(target, "feishu", { [tokenVar]: token }, [tokenVar]);
+        console.error(`[fastagent] wrote ${staged.written.join(", ")} to ${env}`);
+    }
+    else {
+        console.error(`[fastagent] copy it manually: developer console → Events & Callbacks → Encryption Strategy → Verification Token → ${tokenVar} in ${env}`);
+    }
+    if (webhookModeChanged) {
+        // The bootstrap's PATCH flipped event mode in the DRAFT. It takes effect only after a version
+        // publish, which has no API; later dev/deploy runs change only the Request URL immediately.
+        const versionUrl = `${apiBase}/app/${appId}/version`;
+        if (groupSetup.publishReady) {
+            console.error(`[fastagent] one console click remains: CREATE + PUBLISH a version (self-approved) — the switch to webhook mode takes effect on publish. Opening ${versionUrl}`);
+            openExternalUrl(versionUrl);
+        }
+        else {
+            console.error(`[fastagent] after the permission work opened above, CREATE + PUBLISH a version — the switch to webhook mode takes effect on publish: ${versionUrl}`);
+        }
+    }
+}
+/** Active agent `.env` (`.secrets/.env`) values for the requested names — decided by THE .env
+ * parser, so this check can never disagree with what `loadEnvFile` reads. Empty/commented values are absent. */
+async function activeDotEnvValues(dir, names) {
+    let content;
+    try {
+        content = await readFile(dotEnvPath(dir), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return {};
+        throw e;
+    }
+    const parsed = parseEnvContent(content);
+    return Object.fromEntries(names.flatMap((name) => {
+        const value = parsed.get(name)?.trim();
+        return value ? [[name, value]] : [];
+    }));
+}

package/dist/cli/add-slack.d.ts

@@ -0,0 +1,11 @@
+import { type GroupBehaviorChoice } from "../scaffold/add-channel.ts";
+/** Interactive single-workspace internal-app creation + installation. Safe to re-run after interruption. */
+export declare function onboardSlackInternalApp(input: {
+    /** The AGENT DIR — credentials land in its `.env` ({@link dotEnvPath}: `FASTAGENT_SECRETS_DIR` moves
+     *  it, so messages print the resolved path rather than the default spelling). */
+    target: string;
+    stateRoot: string;
+    groupBehavior: GroupBehaviorChoice;
+    /** `--replace-config`: go straight to replacing the local App Configuration token pair. */
+    replaceConfig?: boolean;
+}): Promise<void>;

package/dist/cli/add-slack.js

@@ -0,0 +1,199 @@
+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";
+import { appendChannelDotEnv } from "../scaffold/add-channel.js";
+import { newSlackOnboardingState, onboardSlackApp } from "../channels/slack/onboard.js";
+import { readSlackOnboardingState, writeSlackOnboardingState } from "../channels/slack/onboarding-state.js";
+import { startSlackSetupServer } from "../channels/slack/setup-server.js";
+import { startCloudflareTunnel } from "../tunnel.js";
+const CONFIG_TOKEN_URL = "https://api.slack.com/apps";
+async function promptValue(message, hidden = false, initialValue) {
+    const result = hidden ? await password({ message }) : await clackText({ message, initialValue });
+    if (isCancel(result))
+        throw new Error("Slack onboarding cancelled");
+    const value = String(result).trim();
+    if (!value)
+        throw new Error(`${message}: value is required`);
+    return value;
+}
+/** Interactive single-workspace internal-app creation + installation. Safe to re-run after interruption. */
+export async function onboardSlackInternalApp(input) {
+    installProxyFetch();
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        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);
+    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. " +
+            "Run `fastagent add slack` to onboard, or update the Request URL manually in the Slack console");
+    }
+    if (state?.installedAt) {
+        const env = await readFile(dotEnvPath(input.target), "utf8")
+            .then(parseEnvContent)
+            .catch((error) => {
+            if (error.code === "ENOENT")
+                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() ?? ""));
+        if (missingRuntime.length > 0) {
+            throw new Error(`Slack app ${state.appId ?? "(unknown)"} is installed but ${dotEnvPath(input.target)} is missing ` +
+                `${missingRuntime.join(", ")} — ` +
+                "restore them from the Slack app console, or delete the app + onboarding state and create a new one");
+        }
+        if (input.groupBehavior.explicit && state.groupBehavior !== input.groupBehavior.behavior) {
+            throw new Error(`the onboarded Slack app uses group behavior ${state.groupBehavior}; changing an installed app's ` +
+                "OAuth scopes is a migration. Keep the existing choice, or remove the app + Slack onboarding state and create a new app");
+        }
+        let action = "replace-config";
+        if (!input.replaceConfig) {
+            const answer = await select({
+                message: `Slack app ${state.appId ?? "(unknown)"} is already installed${state.teamName ? ` in ${state.teamName}` : ""}`,
+                initialValue: "keep",
+                options: [
+                    { value: "keep", label: "Keep the installed app" },
+                    {
+                        value: "replace-config",
+                        label: "Replace App Configuration tokens",
+                        hint: "repair automatic dev/deploy Request URL updates",
+                    },
+                ],
+            });
+            if (isCancel(answer))
+                throw new Error("Slack onboarding cancelled");
+            action = answer;
+        }
+        if (action === "replace-config") {
+            console.error(`[fastagent] generate a fresh App Configuration Token pair at ${CONFIG_TOKEN_URL}`);
+            openExternalUrl(CONFIG_TOKEN_URL);
+            const configToken = await promptValue("Slack configuration access token (xoxe.xoxp-…)", true);
+            const configRefreshToken = await promptValue("Slack configuration refresh token (xoxe-…)", true);
+            if (!configToken.startsWith("xoxe.") || !configRefreshToken.startsWith("xoxe-")) {
+                throw new Error("invalid Slack configuration token prefix (expected xoxe. access + xoxe- refresh)");
+            }
+            await writeSlackOnboardingState(input.stateRoot, {
+                ...state,
+                configToken,
+                configRefreshToken,
+                configTokenExpiresAt: Date.now() + 11 * 60 * 60_000,
+            });
+            console.error("[fastagent] replaced local Slack App Configuration tokens; runtime app credentials are unchanged");
+        }
+        else {
+            console.error("[fastagent] keeping the installed Slack app and local configuration tokens");
+        }
+        return;
+    }
+    if (!state) {
+        const appName = await promptValue("Slack app name", false, `FastAgent ${basename(input.target)}`);
+        clackLog.info("Slack's configuration refresh token can manage apps owned by your user in this workspace. " +
+            "FastAgent stores it only in owner-readable local state; it is never deployed.");
+        console.error(`[fastagent] generate an App Configuration Token at ${CONFIG_TOKEN_URL}`);
+        openExternalUrl(CONFIG_TOKEN_URL);
+        const configToken = await promptValue("Slack configuration access token (xoxe.xoxp-…)", true);
+        const configRefreshToken = await promptValue("Slack configuration refresh token (xoxe-…)", true);
+        if (!configToken.startsWith("xoxe."))
+            throw new Error("Slack configuration access token must start with xoxe.");
+        if (!configRefreshToken.startsWith("xoxe-")) {
+            throw new Error("Slack configuration refresh token must start with xoxe-");
+        }
+        state = newSlackOnboardingState({
+            appName,
+            groupBehavior: input.groupBehavior.behavior,
+            configToken,
+            configRefreshToken,
+        });
+        await writeSlackOnboardingState(input.stateRoot, state);
+    }
+    else if (input.groupBehavior.explicit && !state.appId) {
+        state = { ...state, groupBehavior: input.groupBehavior.behavior };
+        await 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 — ` +
+            `inspect ${CONFIG_TOKEN_URL}; delete any incomplete app and ${input.stateRoot}/channels/slack/onboarding.json before retrying`);
+    }
+    // `--replace-config` also covers the created-but-not-installed state, where a revoked token would
+    // otherwise strand the resume (rotation fails and no menu offers replacement).
+    if (resumed && (!state.appId || input.replaceConfig)) {
+        let action = "replace-config";
+        if (!input.replaceConfig) {
+            const answer = await select({
+                message: "Resume Slack onboarding with which App Configuration tokens?",
+                initialValue: "keep",
+                options: [
+                    { value: "keep", label: "Use the saved token pair" },
+                    { value: "replace-config", label: "Paste a fresh token pair" },
+                ],
+            });
+            if (isCancel(answer))
+                throw new Error("Slack onboarding cancelled");
+            action = answer;
+        }
+        if (action === "replace-config") {
+            openExternalUrl(CONFIG_TOKEN_URL);
+            state = {
+                ...state,
+                configToken: await promptValue("Slack configuration access token (xoxe.xoxp-…)", true),
+                configRefreshToken: await promptValue("Slack configuration refresh token (xoxe-…)", true),
+                configTokenExpiresAt: Date.now() + 11 * 60 * 60_000,
+            };
+            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);
+        }
+    }
+    const server = await startSlackSetupServer();
+    const tunnel = await startCloudflareTunnel(server.port);
+    if (!tunnel) {
+        await server.close();
+        throw new Error("Slack onboarding needs a temporary HTTPS tunnel — install cloudflared and re-run");
+    }
+    const requestUrl = `${tunnel.url}${server.requestPath}`;
+    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");
+        }
+        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, }) => {
+                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) {
+                    await appendChannelDotEnv(input.target, "slack", values, Object.keys(values));
+                }
+            },
+        });
+        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");
+    }
+    finally {
+        tunnel.close();
+        await server.close().catch(() => { });
+    }
+}

package/dist/{cli-auth.d.ts → cli/auth-view.d.ts}

@@ -1,7 +1,7 @@
 /**
  * CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). Kept out of cli.ts —
  * which self-executes on import — so the expired-vs-missing DECISION is unit-testable without a real
- * credential round-trip, mirroring cli-models.ts.
+ * credential round-trip, mirroring models-view.ts.
  */
 /** A stored credential as `reportAuth` needs it: just its kind, for the status line. */
 export interface StoredCredentialInfo {

package/dist/{cli-auth.js → cli/auth-view.js}

@@ -1,7 +1,7 @@
 /**
  * CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). Kept out of cli.ts —
  * which self-executes on import — so the expired-vs-missing DECISION is unit-testable without a real
- * credential round-trip, mirroring cli-models.ts.
+ * credential round-trip, mirroring models-view.ts.
  */
 /**
  * Format the auth status for `spec`'s provider. `source` is {@link probeAuthSource}'s label (an env-var

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

@@ -2,6 +2,10 @@ 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;
+    replaceConfig?: boolean;
 }): Promise<void>;
 /** `fastagent add skill <source> [dir]`: vendor an Agent Skills skill into <dir>/skills/<name>/. */
 export declare function runAddSkill(source: string | undefined, dirArg: string, opts: {