@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/{cli-add-feishu.js → cli/add-feishu.js}

@@ -1,27 +1,88 @@
 /**
  * `fastagent add feishu|lark` app onboarding — the cloud-facing half of runAdd, kept out of cli.ts
- * (which self-executes on import), mirroring cli-models.ts/cli-auth.ts. The POLICY already lives in
+ * (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; App ID/Secret are persisted at the
- * irreversible creation boundary, then the Verification Token is captured over a throwaway tunnel and
- * persisted as a second stage — a re-run RESUMES the app instead of minting another. Lark
- * (guided-console): open the unbound launcher, validate entered credentials, probe the same
- * webhook/token bootstrap, and fall back to a manual token prompt on the definitive config-route 404.
+ * 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 { join } from "node:path";
 import { isCancel, log as clackLog, password, text as clackText } from "@clack/prompts";
-import { bootstrapFeishuVerificationToken } from "./channels/feishu/bootstrap-token.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 { parseEnvContent } from "./env.js";
-import { openExternalUrl } from "./open-url.js";
-import { appendChannelDotEnv } from "./scaffold/add-channel.js";
-import { startCloudflareTunnel } from "./tunnel.js";
+import { bootstrapFeishuVerificationToken } from "../channels/feishu/bootstrap-token.js";
+import { FEISHU_GROUP_CONTEXT_SCOPE, } 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 { 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 groupScope = scopes.find((scope) => scope.name === FEISHU_GROUP_CONTEXT_SCOPE && (scope.type === undefined || scope.type === "tenant"));
+    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 (groupScope?.grantStatus === 1) {
+            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 managed-thread replies and group context buffering are disabled`);
+        return { publishReady: true };
+    }
+    note(`[fastagent] group behavior: context-aware (recommended) — ${kind} will deliver all group messages; ` +
+        `FastAgent invokes @Agent + bare managed-thread replies and durably buffers other discussion`);
+    if (groupScope?.grantStatus === 1) {
+        note(`[fastagent] ${FEISHU_GROUP_CONTEXT_SCOPE} is already granted`);
+        return { publishReady: true };
+    }
+    const permissionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/permission`;
+    if (groupScope) {
+        note(`[fastagent] ${FEISHU_GROUP_CONTEXT_SCOPE} is 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).
+        note(`[fastagent] ${FEISHU_GROUP_CONTEXT_SCOPE} is not granted (or could not be verified) — group behavior was ` +
+            `defaulted, so it was not requested. Re-run with --group-behavior context to add it to the app draft, ` +
+            `or --group-behavior mentions to stay least-privilege: ${permissionUrl}`);
+        return { publishReady: false };
+    }
+    try {
+        await api.addAppScopes(appId, [FEISHU_GROUP_CONTEXT_SCOPE]);
+        note(`[fastagent] added ${FEISHU_GROUP_CONTEXT_SCOPE} to the app draft — complete tenant-admin approval before publishing. Opening ${permissionUrl}`);
+    }
+    catch (error) {
+        note(`[fastagent] warn: could not add ${FEISHU_GROUP_CONTEXT_SCOPE} 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`. Returns credentials for the
  * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
@@ -29,7 +90,7 @@ import { startCloudflareTunnel } from "./tunnel.js";
  * irreversible and must not wait for the caller). Throws on refusal (a committable .env, a
  * non-interactive lark run); the caller surfaces that as a startup failure.
  */
-export async function onboardFeishuCloudApp(target, kind, envIgnored) {
+export async function onboardFeishuCloudApp(target, kind, envIgnored, ingress = "webhook", groupBehavior = { behavior: "context", explicit: false }) {
     const { envPrefix, apiBase, capabilities } = cloudFor(kind);
     // The CLI must never materialize a real credential into a committable file — refuse, don't warn.
     if (!envIgnored) {
@@ -37,24 +98,40 @@ export async function onboardFeishuCloudApp(target, kind, envIgnored) {
             ? "`add feishu` creates an app and writes real credentials to .env — add .env to .gitignore/.fastagentignore first, then re-run"
             : "`add lark` writes real app credentials to .env — add .env to .gitignore/.fastagentignore first, then re-run");
     }
-    const existing = await activeDotEnvValues(target, [
+    const requiredNames = [
         `${envPrefix}_APP_ID`,
         `${envPrefix}_APP_SECRET`,
-        `${envPrefix}_VERIFICATION_TOKEN`,
-    ]);
-    if (Object.keys(existing).length === 3) {
-        console.error(`[fastagent] ${envPrefix}_APP_ID/SECRET/VERIFICATION_TOKEN already set in .env — keeping them`);
-        return undefined;
+        ...(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);
+        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)) {
+    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");
     }
-    return onboardLarkApp({
+    const credentials = await onboardLarkApp({
         openUrl: openExternalUrl,
         note: (message) => clackLog.info(message),
         async prompt(message, opts) {
@@ -63,6 +140,8 @@ export async function onboardFeishuCloudApp(target, kind, envIgnored) {
         },
     }, {
         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`);
@@ -94,37 +173,54 @@ export async function onboardFeishuCloudApp(target, kind, envIgnored) {
             }
         },
     });
+    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 in the app, and hands back the credentials; App ID/Secret are persisted at that
- * irreversible boundary before the platform-generated Verification Token is captured from the
- * registration challenge (bootstrap-token.ts). The Token is persisted as a second stage, so .env is
- * complete before the one remaining version-publish action. The event Request URL is NOT left pointing at the throwaway
- * tunnel for long: `dev --tunnel` / `deploy --run` re-register it against the live URL.
+ * 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) {
+async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
     const { apiBase } = cloudFor("feishu");
     let appId = existing.FEISHU_APP_ID;
     let appSecret = existing.FEISHU_APP_SECRET;
     if (appId && appSecret) {
-        console.error(`[fastagent] resuming Feishu app ${appId} from .env to capture its missing Verification Token`);
+        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: the v7 config PATCH (webhook auto-registration
-            // in `dev --tunnel` / `deploy --run`) demands application:application:patch, and the app must
-            // subscribe the receive event. Addons merge both onto the confirm page — no manual app setup.
+            // 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: {
-                scopes: { tenant: ["application:application:patch"] },
+                ...(ingress === "webhook" || (groupBehavior.behavior === "context" && groupBehavior.explicit)
+                    ? { scopes: { tenant: ["application:application:patch"] } }
+                    : {}),
                 events: { items: { tenant: ["im.message.receive_v1"] } },
             },
             onVerificationUrl: ({ url, expiresInS }) => {
@@ -144,14 +240,36 @@ async function createFeishuAppFlow(target, existing) {
         // 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.
-        await appendChannelDotEnv(target, "feishu", {
+        const staged = {
             FEISHU_APP_ID: appId,
             FEISHU_APP_SECRET: appSecret,
-            // A Token from a partial OLD credential set belongs to another App. Clear it at the same
-            // boundary; successful bootstrap below replaces the empty line with this App's Token.
-            FEISHU_VERIFICATION_TOKEN: "",
-        }, ["FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_VERIFICATION_TOKEN"]);
-        console.error(`[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to .env before Token bootstrap`);
+            ...(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
@@ -199,8 +317,13 @@ async function createFeishuAppFlow(target, existing) {
         // 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`;
-        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);
+        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 run-root `.env` values for the requested names — decided by THE .env parser, so this

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

@@ -0,0 +1,10 @@
+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: {
+    target: string;
+    stateRoot: string;
+    envIgnored: boolean;
+    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,204 @@
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
+import { waitForHealth } from "../channels/wait-health.js";
+import { ensureStateRootSelfIgnored } from "../engines/pi/definition.js";
+import { 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 (!input.envIgnored) {
+        throw new Error("`add slack` onboarding creates an app and writes real credentials to .env — " +
+            "add .env to .gitignore/.fastagentignore first, then re-run");
+    }
+    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");
+    }
+    await ensureStateRootSelfIgnored(input.target, input.stateRoot);
+    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(join(input.target, ".env"), "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 .env 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 .env");
+        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

@@ -0,0 +1,13 @@
+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: {
+    update?: boolean;
+}): Promise<void>;