@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/cli/add-feishu.js

@@ -5,137 +5,97 @@
 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, feishuAppAddons, scopeSatisfied, } from "../channels/feishu/setup-mode.js";
+import { FEISHU_APP_CONFIG_SCOPE, feishuAppAddons, feishuAppScopes, feishuScopeRequestUrl, 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 { LARK_CONSOLE_URL, onboardLarkApp } from "../channels/lark/onboard.js";
+import { dotEnvPath, loadEnvValues, parseEnvContent } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
+import { terminalPerson } from "./person.js";
+import { AGENT_ENVIRONMENT_ENV } from "../paths.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;
+/**
+ * Check that the app holds what an app of this ingress needs ({@link feishuAppScopes}). A created app asks for them on
+ * its confirm page, and a tenant may still withhold some (its approval policy, or an app made by hand): those are
+ * NAMED, with what each one costs, and the console page that requests them is opened pre-filled. Nothing is requested
+ * through the config API — that needs a scope of its own, which a tenant can withhold just the same.
+ */
+export async function checkAgentScopes(input) {
+    const { kind, appId, apiBase, api } = input;
     const note = input.note ?? ((message) => console.error(message));
-    const openUrl = input.openUrl ?? openExternalUrl;
+    const person = input.person ?? terminalPerson;
+    const needed = feishuAppScopes(input.ingress);
+    const requested = needed.map((entry) => entry.request);
     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).
-    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 };
+        const url = feishuScopeRequestUrl(apiBase, appId, requested);
+        note(`[fastagent] warn: could not read the ${kind} app's permissions: ${String(error)}`);
+        person.afterwards(`make sure the ${kind} app holds ${requested.join(", ")} before publishing`, url);
+        return { publishReady: false, missing: [] };
     }
-    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`);
+    // A user-type entry is not the tenant scope the app acts with.
+    const tenant = scopes.filter((scope) => scope.type === undefined || scope.type === "tenant");
+    const granted = (name) => tenant.some((scope) => scope.name === name && scope.grantStatus === 1);
+    const missing = needed.filter((entry) => !scopeSatisfied(entry, granted));
     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.
-    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).
-        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}`);
+        note(`[fastagent] ${kind} app permissions: ${requested.join(", ")} granted`);
+        return { publishReady: true, missing: [] };
     }
-    openUrl(permissionUrl);
-    return { publishReady: false };
+    // "Not granted", not "not requested": the list omits a scope still under review (measured), so the two look alike.
+    const describe = (entry) => `\n  ${entry.request}: without it ${entry.withoutIt}`;
+    const url = feishuScopeRequestUrl(apiBase, appId, missing.map((entry) => entry.request));
+    person.afterwards(`the ${kind} app is not granted:${missing.map(describe).join("")}\n` +
+        `Tick and enable them on that page (one may already be awaiting a tenant admin's approval), before publishing`, url);
+    return { publishReady: false, missing: missing.map((entry) => entry.request) };
 }
 /** Create or resume the platform app behind `add feishu` / `add lark`. */
-export async function onboardFeishuCloudApp(target, kind, ingress = "webhook", groupBehavior = { behavior: "context", explicit: false }) {
+export async function onboardFeishuCloudApp(target, kind, ingress, 
+/** The command that continues an interrupted setup: the one that started it. */
+rerun = `fastagent add ${kind}${ingress === "webhook" ? " --ingress webhook" : ""}`, 
+/** Who takes the steps only a person can: at this terminal, or a coding agent's person through a ticket. */
+person = terminalPerson) {
     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 requiredNames = feishuAppSecretNames(kind, ingress);
     const existing = await activeDotEnvValues(target, requiredNames);
+    if (process.env[AGENT_ENVIRONMENT_ENV] === "production") {
+        assertIndependentFeishuApps(target, [kind], new Map(Object.entries(existing)));
+    }
     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.
         if (ingress === "webhook") {
             const appId = existing[`${envPrefix}_APP_ID`];
             const appSecret = existing[`${envPrefix}_APP_SECRET`];
-            await configureGroupBehavior({
+            await checkAgentScopes({
                 kind,
                 appId,
                 apiBase,
+                ingress,
                 api: createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret }),
-                behavior: groupBehavior.behavior,
-                explicit: groupBehavior.explicit,
+                person,
             });
             return undefined;
         }
     }
     if (capabilities.appCreation === "scan-to-create") {
-        await createFeishuAppFlow(target, existing, ingress, groupBehavior);
+        await createFeishuAppFlow(target, existing, ingress, rerun, person);
         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;
-        },
-    }, {
+    const credentials = await onboardLarkApp(person === terminalPerson ? larkAtTerminal : larkThrough(person, env, rerun), {
         existing,
         ingress,
-        groupBehavior: groupBehavior.behavior,
+        rerun,
         verifyCredentials: async (appId, appSecret) => {
+            if (process.env[AGENT_ENVIRONMENT_ENV] === "production") {
+                assertIndependentFeishuApps(target, ["lark"], new Map([["LARK_APP_ID", appId]]));
+            }
             await createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret }).verifyCredentials();
             console.error(`[fastagent] Lark App ID / Secret verified`);
         },
@@ -165,23 +125,48 @@ export async function onboardFeishuCloudApp(target, kind, ingress = "webhook", g
             }
         },
     });
-    await configureGroupBehavior({
+    await checkAgentScopes({
         kind: "lark",
         appId: credentials.LARK_APP_ID,
         apiBase,
+        ingress,
+        person,
         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"));
 }
+/** Lark's guided console at a terminal: what to open, and the values asked for there. */
+const larkAtTerminal = {
+    openUrl(url, action) {
+        clackLog.info(`${action}. Opening ${url}`);
+        openExternalUrl(url);
+    },
+    note: (message) => clackLog.info(message),
+    async prompt(message, opts) {
+        const result = opts?.hidden ? await password({ message }) : await clackText({ message });
+        return isCancel(result) ? undefined : result;
+    },
+};
+/**
+ * Lark's guided console through a coding agent's person: a page is a step left to them, with what they do there; a
+ * value it would ask for is theirs to set in the value file, and the setup continues when run again.
+ */
+function larkThrough(person, env, rerun) {
+    return {
+        note: (message) => console.error(`[fastagent] ${message}`),
+        openUrl: (url, action) => person.afterwards(action, url),
+        async prompt(message) {
+            throw new Error(`${message} is needed: ask the user to set it in ${env}, then run \`${rerun}\` again`);
+        },
+    };
+}
 /** The scan-to-create flow `add feishu` runs by default. */
-async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
+async function createFeishuAppFlow(target, existing, ingress, rerun, person) {
     const env = dotEnvPath(target); // the file actually written — never the default spelling
     const { apiBase } = cloudFor("feishu");
     let appId = existing.FEISHU_APP_ID;
@@ -194,15 +179,13 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
     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
+            name: process.env[AGENT_ENVIRONMENT_ENV] === "production" ? "{user}'s production agent" : "{user}'s agent",
             desc: "Served by fastagent",
-            // The agent template alone is not enough to SERVE (see feishuAppAddons).
-            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
-            },
+            // The agent template alone is not enough to SERVE, nor to hear a group (see feishuAppAddons).
+            addons: feishuAppAddons(ingress),
+            onVerificationUrl: ({ url, expiresInS }) => person.waitsOn(url, "confirm the new Feishu app (in a browser, or in Feishu, or as a QR code)", Date.now() + expiresInS * 1000),
         });
+        person.carriesOn();
         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).
         if (app.tenantBrand && app.tenantBrand !== "feishu") {
@@ -221,25 +204,22 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
             ? `[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({
+    const groupSetup = await checkAgentScopes({
         kind: "feishu",
         appId,
         apiBase,
+        ingress,
         api: createFeishuApi({ kind: "feishu", baseUrl: apiBase, appId, appSecret }),
-        behavior: groupBehavior.behavior,
-        explicit: groupBehavior.explicit,
+        person,
     });
     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}`);
-        }
+        const choose = "WebSocket ingress needs no Verification Token, Encrypt Key, Request URL, or tunnel: choose long connection in " +
+            "Events & Callbacks";
+        if (groupSetup.publishReady)
+            person.afterwards(`${choose}, then CREATE + PUBLISH a version`, versionUrl);
+        else
+            person.afterwards(`${choose}, finish the permission work above, then CREATE + PUBLISH a version: ${versionUrl}`);
         return;
     }
     // The webhook channel authenticates plaintext events by the platform-generated Verification Token.
@@ -256,20 +236,29 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         // it was needed would otherwise be invisible.
         console.error(`[fastagent] could not read the app's Verification Token directly: ${error.message}`);
     }
-    if (!token) {
+    // The bootstrap registers a Request URL through the config scope; without it every attempt is refused, so it is not
+    // tried, and the reason is the one the permission check above already named.
+    const configWithheld = groupSetup.missing.includes(FEISHU_APP_CONFIG_SCOPE);
+    if (!token && configWithheld) {
+        console.error(`[fastagent] not capturing the Verification Token: the app is not granted ${FEISHU_APP_CONFIG_SCOPE}. Choose webhook ` +
+            `in Events & Callbacks and set the Request URL there yourself (dev --tunnel and deploy --run cannot ` +
+            `either), or have the permission approved and re-run \`${rerun}\`.`);
+    }
+    else 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),
+                // Only edge weather is retried; a refusal (scope, auth, app under review) is reported as itself.
+                shouldRetryPatch: isTransientFeishuRegistrationError,
             });
             webhookModeChanged = true;
             console.error(`[fastagent] Verification Token captured`);
         }
         catch (e) {
-            // Transient tunnel weather is the usual cause.
-            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`);
+            console.error(`[fastagent] warn: could not capture the Verification Token: ${String(e)} — finish this app with the manual copy below`);
         }
     }
     if (token) {
@@ -278,20 +267,47 @@ async function createFeishuAppFlow(target, existing, ingress, groupBehavior) {
         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}`);
+        person.afterwards(`copy the Verification Token: developer console → Events & Callbacks → Encryption Strategy → Verification ` +
+            `Token → ${tokenVar} in ${env}`);
     }
     if (webhookModeChanged) {
         // The bootstrap's PATCH flipped event mode in the DRAFT.
         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}`);
-        }
+        const publish = "CREATE + PUBLISH a version (self-approved): the switch to webhook mode takes effect on publish";
+        if (groupSetup.publishReady)
+            person.afterwards(publish, versionUrl);
+        else
+            person.afterwards(`after the permission work above, ${publish}: ${versionUrl}`);
     }
 }
+/**
+ * Lark's app credentials, which only the person can get, from the app they create in Lark's console: with no one at a
+ * terminal to type them, the report naming where they set them (the selected environment's file), when either is
+ * absent. `again` is the command that continues once they have.
+ */
+export async function larkCredentialsNeeded(agentDir, again) {
+    const held = await activeDotEnvValues(agentDir, ["LARK_APP_ID", "LARK_APP_SECRET"]);
+    if (held.LARK_APP_ID && held.LARK_APP_SECRET)
+        return undefined;
+    const valueFile = dotEnvPath(agentDir);
+    return {
+        json: {
+            status: "need_user_action",
+            url: LARK_CONSOLE_URL,
+            variables: ["LARK_APP_ID", "LARK_APP_SECRET"],
+            value_file: valueFile,
+            check_command: `${again} --json`,
+            agent_next_steps: "Give the URL to the user so they can create the Lark app there, and ask them to set LARK_APP_ID and " +
+                `LARK_APP_SECRET (from its Credentials & Basic Info) in ${valueFile} themselves, not in this ` +
+                "conversation. Once they say they have, run check_command.",
+        },
+        text: [
+            `need_user_action: create the Lark app at ${LARK_CONSOLE_URL}`,
+            `  and set LARK_APP_ID and LARK_APP_SECRET in ${valueFile}`,
+            `then run: ${again}`,
+        ],
+    };
+}
 /**
  * Active agent `.env` (`.secrets/.env`) values for the requested names — decided by THE .env parser, so this check can
  * never disagree with what `loadDotEnv` reads.
@@ -312,3 +328,40 @@ async function activeDotEnvValues(dir, names) {
         return value ? [[name, value]] : [];
     }));
 }
+export function feishuAppSecretNames(kind, ingress) {
+    const prefix = cloudFor(kind).envPrefix;
+    return [
+        `${prefix}_APP_ID`,
+        `${prefix}_APP_SECRET`,
+        ...(ingress === "webhook" ? [`${prefix}_VERIFICATION_TOKEN`] : []),
+    ];
+}
+export function unpreparedFeishuApps(channels, values) {
+    return ["feishu", "lark"].flatMap((kind) => {
+        const channel = channels.find((entry) => entry.name === kind);
+        if (!channel)
+            return [];
+        const ingress = channel.ingress === "webhook" ? "webhook" : "websocket";
+        return feishuAppSecretNames(kind, ingress).some((name) => !values.get(name)?.trim()) ? [{ kind, ingress }] : [];
+    });
+}
+export function assertIndependentFeishuApps(agentDir, kinds, values) {
+    const devFile = dotEnvPath(agentDir, {});
+    const devValues = loadEnvValues(devFile);
+    for (const kind of kinds) {
+        const name = `${cloudFor(kind).envPrefix}_APP_ID`;
+        const appId = values.get(name)?.trim();
+        if (appId && appId === devValues.get(name)?.trim()) {
+            throw new Error(`${kind}: dev and production use the same app (${name}) — create a separate production app in ` +
+                `${dotEnvPath(agentDir)}; copying dev credentials would take its messages away`);
+        }
+    }
+}
+export async function prepareFeishuApps(agentDir, apps, rerun, person, onboard = onboardFeishuCloudApp) {
+    for (const { kind, ingress } of apps) {
+        console.error(`[fastagent] ${kind}: preparing the production app for ${ingress} in ${dotEnvPath(agentDir)}`);
+        const created = await onboard(agentDir, kind, ingress, rerun, person);
+        if (created)
+            await appendChannelDotEnv(agentDir, kind, created, Object.keys(created), ingress);
+    }
+}

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

@@ -1,5 +1,5 @@
-import { type GroupBehaviorChoice } from "../scaffold/add-channel.ts";
-/** Interactive single-workspace internal-app creation + installation. */
+import type { Person } from "./person.ts";
+/** Single-workspace internal-app creation + installation. */
 export declare function onboardSlackInternalApp(input: {
     /**
      * The AGENT DIR — credentials land in its `.env` ({@link dotEnvPath}: `FASTAGENT_SECRETS_DIR` moves it, so messages
@@ -7,7 +7,12 @@ export declare function onboardSlackInternalApp(input: {
      */
     target: string;
     stateRoot: string;
-    groupBehavior: GroupBehaviorChoice;
     /** `--replace-config`: go straight to replacing the local App Configuration token pair. */
     replaceConfig?: boolean;
+    /**
+     * A coding agent's person, through a ticket: nothing is asked at a terminal. The token pair is pasted on a page the
+     * setup server shows, which then takes the browser on to Slack's install page; the app takes its default name, and
+     * a saved pair is kept. Absent: the terminal asks.
+     */
+    person?: Person;
 }): Promise<void>;