@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/channels/feishu/setup.js

@@ -0,0 +1,197 @@
+/**
+ * What a Feishu or Lark app's setup asks for (channels/setup.ts). The two share one engine: the app's credentials come
+ * first (Feishu creates the app by scan-to-create and keeps what it returns; Lark's person creates it in its console and
+ * pastes them), then, for a webhook, the Verification Token, captured by a throwaway webhook registration when the app
+ * allows it and pasted when it does not. What is left to the person is the permission work and the publish, which
+ * depend on what the platform says about the app.
+ */
+import { pasteOne } from "../setup.js";
+import { bootstrapFeishuVerificationToken } from "./bootstrap-token.js";
+import { cloudFor } from "./cloud.js";
+import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError, } from "./feishu-api.js";
+import { registerFeishuApp } from "./register-app.js";
+import { FEISHU_APP_CONFIG_SCOPE, FEISHU_MESSAGE_RECEIVE_EVENT, feishuAppAddons, feishuAppScopes, feishuScopeRequestUrl, scopeSatisfied, } from "./setup-mode.js";
+const say = (message) => console.error(`[fastagent] ${message}`);
+/** The page of an app where its Verification Token is, and where the subscription mode is chosen. */
+const eventPage = (kind, appId) => `${cloudFor(kind).apiBase}/app/${encodeURIComponent(appId)}/event?tab=safe`;
+/**
+ * What the app holds of what an app of this way 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 linked pre-filled. Nothing is requested through
+ * the config API: that needs a scope of its own, which a tenant can withhold just the same.
+ */
+async function agentScopes(kind, way, appId, api) {
+    const apiBase = cloudFor(kind).apiBase;
+    const needed = feishuAppScopes(way);
+    const requested = needed.map((entry) => entry.request);
+    let scopes;
+    try {
+        scopes = await api.listAppScopes();
+    }
+    catch (error) {
+        return {
+            missing: [],
+            lines: [
+                `could not read the ${kind} app's permissions (${String(error)}): make sure it holds ${requested.join(", ")} ` +
+                    `before publishing: ${feishuScopeRequestUrl(apiBase, appId, requested)}`,
+            ],
+        };
+    }
+    // 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) {
+        say(`${kind} app permissions: ${requested.join(", ")} granted`);
+        return { missing: [], lines: [] };
+    }
+    // "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));
+    return {
+        missing: missing.map((entry) => entry.request),
+        lines: [
+            `the ${kind} app is not granted:${missing.map(describe).join("")}\n` +
+                `Tick and enable them at ${url} (one may already be awaiting a tenant admin's approval), before publishing`,
+        ],
+    };
+}
+/** The setup of a Feishu or Lark app whose credentials are `credentials`. */
+export function feishuEngine(kind, credentials, context) {
+    const { way, publicUrl, startTunnel } = context;
+    const { envPrefix, apiBase } = cloudFor(kind);
+    const idName = `${envPrefix}_APP_ID`;
+    const tokenName = `${envPrefix}_VERIFICATION_TOKEN`;
+    const idOf = (held) => held.get(idName);
+    const apiOf = (held) => createFeishuApi({
+        kind,
+        baseUrl: apiBase,
+        appId: idOf(held),
+        appSecret: held.get(`${envPrefix}_APP_SECRET`),
+    });
+    let scopes;
+    const scopesOf = (held) => (scopes ??= agentScopes(kind, way, idOf(held), apiOf(held)));
+    /** How the Verification Token came, when the setup went looking for it. */
+    let token;
+    async function capture(held) {
+        const appId = idOf(held);
+        const api = apiOf(held);
+        try {
+            const config = await api.getAppConfig(appId);
+            if (config.verificationToken) {
+                token = "read";
+                return config.verificationToken;
+            }
+        }
+        catch (error) {
+            if (isFeishuConfigApiMissing(error)) {
+                say(`this ${kind} app returned HTTP 404 for the application-config API, so its Verification Token cannot be captured automatically`);
+                token = "manual";
+                return undefined;
+            }
+            say(`could not read the app's Verification Token directly: ${error.message}`);
+        }
+        // The capture registers a Request URL through the config scope; without it every attempt is refused.
+        if ((await scopesOf(held)).missing.includes(FEISHU_APP_CONFIG_SCOPE)) {
+            say(`not capturing the Verification Token: the app is not granted ${FEISHU_APP_CONFIG_SCOPE}. Paste it from the ` +
+                `console, or have the permission approved and run \`${context.rerun}\` again`);
+            token = "pasted";
+            return undefined;
+        }
+        say("capturing the Verification Token: a throwaway webhook registration delivers it (a temporary tunnel; can take a few minutes on a slow edge)…");
+        try {
+            const captured = await bootstrapFeishuVerificationToken({
+                api,
+                appId,
+                kind,
+                startTunnel,
+                onTunnelReady: (url) => say(`temporary tunnel ready → ${url}; registering webhook mode now…`),
+                onPatchRetry: ({ error, attempt, attempts, retryMs }) => say(`${kind} could not validate the fresh tunnel yet (${String(error)}); retrying PATCH ${attempt + 1}/${attempts} in ${Math.round(retryMs / 1000)}s…`),
+                // Only edge weather is retried; a refusal (scope, auth, app under review) is reported as itself.
+                shouldRetryPatch: (error) => !isFeishuConfigApiMissing(error) && isTransientFeishuRegistrationError(error),
+            });
+            say("Verification Token captured; Subscription mode changed to webhook in the app draft");
+            token = "captured";
+            return captured;
+        }
+        catch (error) {
+            say(`warn: could not capture the Verification Token: ${String(error)}: paste it from the console`);
+            token = "pasted";
+            return undefined;
+        }
+    }
+    const values = [
+        credentials,
+        ...(way === "webhook"
+            ? [
+                pasteOne({
+                    name: tokenName,
+                    label: "Verification Token",
+                    guide: (held) => ({
+                        instructions: "Open Events & Callbacks → Encryption Strategy and copy the Verification Token.",
+                        url: eventPage(kind, idOf(held)),
+                    }),
+                    // The first signed event says whether it is right; nothing can be asked of the platform before.
+                    check: async () => undefined,
+                    capture,
+                }),
+            ]
+            : []),
+    ];
+    return {
+        values,
+        async finish(held) {
+            const appId = idOf(held);
+            const findings = await scopesOf(held);
+            const ready = findings.lines.length === 0;
+            const then = ready ? "" : "after the permission work above, ";
+            const publish = `CREATE + PUBLISH a version: ${apiBase}/app/${encodeURIComponent(appId)}/version`;
+            const lines = [...findings.lines];
+            if (way === "connection") {
+                // A Feishu app made by scan-to-create is on a long connection already, with the event subscribed (measured).
+                lines.push(kind === "feishu"
+                    ? `${then}${publish}`
+                    : `in Events & Callbacks choose long connection and make sure ${FEISHU_MESSAGE_RECEIVE_EVENT} is subscribed ` +
+                        `(no Verification Token, Request URL or tunnel is needed): ${eventPage(kind, appId)}; then ${then}${publish}`);
+            }
+            else if (token === "captured") {
+                lines.push(`the switch to webhook mode takes effect on publish: ${then}${publish}${kind === "feishu" ? " (self-approved)" : ""}`);
+            }
+            else if (token === "manual") {
+                lines.push(`this ${kind} app has no application-config API, so the instance cannot set its Request URL: choose webhook in ` +
+                    `Events & Callbacks and set the Request URL to ${publicUrl ?? "https://<where it is served>"}/${kind}, ` +
+                    `${then}${publish}, then run \`fastagent channels setup ${kind} --record-url --config <file>\``);
+            }
+            else if (token === "pasted") {
+                lines.push(`the instance sets the Subscription mode and Request URL itself when the app holds ${FEISHU_APP_CONFIG_SCOPE}; ` +
+                    `otherwise choose webhook in Events & Callbacks and set the Request URL to ` +
+                    `${publicUrl ?? "https://<where it is served>"}/${kind}, then ${then}${publish}`);
+            }
+            return lines;
+        },
+    };
+}
+export const feishuSetup = (context) => {
+    const { way, dev } = context;
+    return feishuEngine("feishu", {
+        kind: "create",
+        names: ["FEISHU_APP_ID", "FEISHU_APP_SECRET"],
+        async create(person) {
+            say("creating the Feishu app (confirm in the app)…");
+            const app = await registerFeishuApp({
+                name: dev ? "{user}'s agent" : "{user}'s production agent",
+                desc: "Served by fastagent",
+                // The agent template alone is not enough to SERVE, nor to hear a group (see feishuAppAddons).
+                addons: feishuAppAddons(way),
+                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();
+            say(`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") {
+                throw new Error(`the confirming account is a ${app.tenantBrand} tenant, but this is feishu: run \`fastagent channels setup ${app.tenantBrand}\` instead`);
+            }
+            return { FEISHU_APP_ID: app.appId, FEISHU_APP_SECRET: app.appSecret };
+        },
+    }, context);
+};

package/dist/channels/kit/abortable.d.ts

@@ -0,0 +1,8 @@
+/** Waiting that an abort ends: what a connection that retries and reconnects does between its attempts. */
+/**
+ * Run `fn` when `signal` aborts; the returned function stops listening. A listener that is never removed stays on a
+ * signal that lives as long as the connection, and Node warns past ten of them.
+ */
+export declare function whenAborted(signal: AbortSignal, fn: () => void): () => void;
+/** Wait `ms`, or until `signal` aborts. */
+export declare function pause(ms: number, signal: AbortSignal): Promise<void>;

package/dist/channels/kit/abortable.js

@@ -0,0 +1,22 @@
+/** Waiting that an abort ends: what a connection that retries and reconnects does between its attempts. */
+/**
+ * Run `fn` when `signal` aborts; the returned function stops listening. A listener that is never removed stays on a
+ * signal that lives as long as the connection, and Node warns past ten of them.
+ */
+export function whenAborted(signal, fn) {
+    signal.addEventListener("abort", fn, { once: true });
+    return () => signal.removeEventListener("abort", fn);
+}
+/** Wait `ms`, or until `signal` aborts. */
+export function pause(ms, signal) {
+    return new Promise((resolve) => {
+        const stopListening = whenAborted(signal, () => {
+            clearTimeout(timer);
+            resolve();
+        });
+        const timer = setTimeout(() => {
+            stopListening();
+            resolve();
+        }, ms);
+    });
+}

package/dist/channels/lark/lark.d.ts

@@ -1,7 +1,6 @@
 /** Lark-international compatibility adapter. */
 import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
 import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, type FeishuWebSocketChannelOptions, defaultFeishuRoute } from "../feishu/feishu.ts";
-import { type FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
 export type LarkChannelOptions = FeishuChannelOptions;
 export type LarkWebSocketChannelOptions = FeishuWebSocketChannelOptions;
 export type LarkFailure = FeishuFailure;
@@ -11,6 +10,4 @@ export type LarkRoute = FeishuRoute;
 export declare const defaultLarkRoute: typeof defaultFeishuRoute;
 export declare function larkEnvelope(event: LarkMessageEvent): string;
 export declare function larkChannel(opts: LarkChannelOptions): ChannelModule;
-/** How this process receives the Lark channel: `LARK_INGRESS`, else WebSocket under `dev` and webhook otherwise. */
-export declare function larkIngress(): FeishuSubscriptionMode;
 export declare function larkWebSocketChannel(opts: LarkWebSocketChannelOptions): LongConnectionChannelModule;

package/dist/channels/lark/lark.js

@@ -1,7 +1,6 @@
 import { LARK_COMPAT_CLOUD } from "../feishu/cloud.js";
 import { buildFeishuChannel, buildFeishuWebSocketChannel, defaultFeishuRoute, } from "../feishu/feishu.js";
 import { cloudEnvelope } from "../feishu/parse.js";
-import { feishuIngressFor } from "../feishu/setup-mode.js";
 export const defaultLarkRoute = defaultFeishuRoute;
 export function larkEnvelope(event) {
     return cloudEnvelope(event, "lark");
@@ -9,10 +8,6 @@ export function larkEnvelope(event) {
 export function larkChannel(opts) {
     return buildFeishuChannel(LARK_COMPAT_CLOUD, opts, larkChannel.name);
 }
-/** How this process receives the Lark channel: `LARK_INGRESS`, else WebSocket under `dev` and webhook otherwise. */
-export function larkIngress() {
-    return feishuIngressFor("lark");
-}
 export function larkWebSocketChannel(opts) {
     return buildFeishuWebSocketChannel(LARK_COMPAT_CLOUD, opts, larkWebSocketChannel.name);
 }

package/dist/channels/lark/scaffold/channel.ts

@@ -1,22 +1,19 @@
-import { needs } from "@fastagent-sh/fastagent";
-import {
-  type LarkChannelOptions,
-  larkChannel,
-  larkIngress,
-  larkWebSocketChannel,
-} from "@fastagent-sh/fastagent/lark";
+import { byIngress, needs } from "@fastagent-sh/fastagent";
+import { type LarkChannelOptions, larkChannel, larkWebSocketChannel } from "@fastagent-sh/fastagent/lark";
 
 // The branded Lark adapter over fastagent's canonical Feishu engine (verify + run + reply), configured
 // with YOUR policy. Lark international (open.larksuite.com) only; a Feishu tenant uses `fastagent add
 // feishu` instead.
 //
-// How it receives is LARK_INGRESS (webhook | websocket). Unset, `fastagent dev` connects OUT by
-// WebSocket (no public URL, no tunnel), and everything else — `fastagent start`, every deployment —
-// receives by webhook at POST /lark. Dev reads .secrets/.env; production reads
-// .secrets/production/.env. Interactive `deploy --run` guides creation of a separate production app;
-// if Lark refuses its config API, set the Request URL in the console once.
+// How it receives is the instance's choice, `channels.lark.ingress` in its fastagent.json (webhook |
+// connection). Unset, `fastagent dev` opens a long connection OUT (no public URL, no tunnel), and everything
+// else — `fastagent start`, every deployment — receives by webhook at POST /lark, the way a host that
+// wakes on a request is reached.
+// Dev reads .secrets/.env; production reads .secrets/production/.env. Interactive `deploy --run`
+// guides creation of a separate production app; if Lark refuses its config API, set the Request URL
+// in the console once.
 //
-// `fastagent add lark` guides the console setup and validates the credentials. In the developer
+// `fastagent channels setup lark` guides the console setup and validates the credentials. In the developer
 // console:
 //   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
 //   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
@@ -47,25 +44,26 @@ const policy: Pick<LarkChannelOptions, "onError" | "route"> = {
   //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { text: `${larkEnvelope(e)}\n[extra]` },
 };
 
-// `needs` declares the env vars this channel reads: fastagent carries them to a deployed box and
-// refuses to serve while a required one is unset. LARK_ENCRYPT_KEY is optional.
-export default larkIngress() === "webhook"
-  ? needs(
-      [
-        "LARK_APP_ID",
-        "LARK_APP_SECRET",
-        "LARK_VERIFICATION_TOKEN",
-        { name: "LARK_ENCRYPT_KEY", description: "when set, plaintext events are refused", optional: true },
-      ],
-      (secrets) =>
-        larkChannel({
-          appId: secrets.LARK_APP_ID,
-          appSecret: secrets.LARK_APP_SECRET,
-          verificationToken: secrets.LARK_VERIFICATION_TOKEN, // authenticates inbound events
-          encryptKey: secrets.LARK_ENCRYPT_KEY,
-          ...policy,
-        }),
-    )
-  : needs(["LARK_APP_ID", "LARK_APP_SECRET"], (secrets) =>
-      larkWebSocketChannel({ appId: secrets.LARK_APP_ID, appSecret: secrets.LARK_APP_SECRET, ...policy }),
-    );
+// Each way's `needs` declares the env vars it reads: an instance is asked only for its way's, and
+// refused to serve while a required one is unset. LARK_ENCRYPT_KEY is optional.
+export default byIngress({
+  webhook: needs(
+    [
+      "LARK_APP_ID",
+      "LARK_APP_SECRET",
+      "LARK_VERIFICATION_TOKEN",
+      { name: "LARK_ENCRYPT_KEY", description: "when set, plaintext events are refused", optional: true },
+    ],
+    (secrets) =>
+      larkChannel({
+        appId: secrets.LARK_APP_ID,
+        appSecret: secrets.LARK_APP_SECRET,
+        verificationToken: secrets.LARK_VERIFICATION_TOKEN, // authenticates inbound events
+        encryptKey: secrets.LARK_ENCRYPT_KEY,
+        ...policy,
+      }),
+  ),
+  connection: needs(["LARK_APP_ID", "LARK_APP_SECRET"], (secrets) =>
+    larkWebSocketChannel({ appId: secrets.LARK_APP_ID, appSecret: secrets.LARK_APP_SECRET, ...policy }),
+  ),
+});

package/dist/channels/lark/scaffold/lark-send.ts

@@ -1,4 +1,4 @@
-import { Type } from "@earendil-works/pi-ai";
+import { obj, opt, str } from "@earendil-works/pi-schema";
 import { defineTool } from "@earendil-works/pi-durable";
 import { needs } from "@fastagent-sh/fastagent";
 import { larkTransport } from "@fastagent-sh/fastagent/lark";
@@ -18,10 +18,10 @@ export default needs(["LARK_APP_ID", "LARK_APP_SECRET"], (secrets) =>
       "or memory); the [lark: chat …] context line only identifies the chat you are answering, the " +
       "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
       "`markdown` (rendered as a card: headings, bold, code blocks, links).",
-    parameters: Type.Object({
-      chatId: Type.String({ description: "target chat id (oc_…)" }),
-      text: Type.Optional(Type.String({ description: "plain text message to send" })),
-      markdown: Type.Optional(Type.String({ description: "markdown to send as a card" })),
+    parameters: obj({
+      chatId: str({ description: "target chat id (oc_…)" }),
+      text: opt(str({ description: "plain text message to send" })),
+      markdown: opt(str({ description: "markdown to send as a card" })),
     }),
     execute: async ({ chatId, text, markdown }) => {
       if ((text === undefined) === (markdown === undefined)) {

package/dist/channels/lark/scaffold/lark-threads.ts

@@ -1,4 +1,4 @@
-import { Type } from "@earendil-works/pi-ai";
+import { obj, opt, str } from "@earendil-works/pi-schema";
 import { defineTool } from "@earendil-works/pi-durable";
 import { sessionIdOf } from "@fastagent-sh/fastagent";
 import { larkThreads } from "@fastagent-sh/fastagent/lark";
@@ -14,8 +14,8 @@ export default defineTool({
     "it when a question here concerns something discussed in a thread, such as whether a problem raised there was " +
     "resolved: the answer is often what a person wrote in the thread. Only this chat's threads can be read, and " +
     "only in a group chat turn.",
-  parameters: Type.Object({
-    threadId: Type.Optional(Type.String({ description: "a thread id from the list (omt_…); omit it to list" })),
+  parameters: obj({
+    threadId: opt(str({ description: "a thread id from the list (omt_…); omit it to list" })),
   }),
   execute: async ({ threadId }, api, context) => {
     const threads = larkThreads(await sessionIdOf(api, context));

package/dist/channels/lark/setup.d.ts

@@ -0,0 +1,9 @@
+import { type ChannelSetup, type SetupWay } from "../setup.ts";
+/**
+ * Lark's one-click launcher, where the person creates the app. The launcher is unbound (the bound confirm page is broken
+ * on the international cloud), but it merges the `addons` query parameter onto the app it creates, as Feishu's does: the
+ * scopes and the event the channel needs arrive with the app, so nothing is ticked in the console afterwards. A tenant
+ * may still withhold a scope; the permission check that follows creation names it.
+ */
+export declare function larkLauncherUrl(way: SetupWay): string;
+export declare const larkSetup: ChannelSetup;

package/dist/channels/lark/setup.js

@@ -0,0 +1,57 @@
+/**
+ * What a Lark app's setup asks for (channels/setup.ts). Lark's international cloud cannot complete the bound
+ * scan-to-create flow, so its person creates the app on the one-click launcher and pastes the App ID and App Secret,
+ * which Lark checks as a pair; the rest is the Feishu engine's.
+ */
+import { encodeAddons } from "../feishu/register-app.js";
+import { createFeishuApi, isFeishuCredentialsRefused } from "../feishu/feishu-api.js";
+import { feishuEngine } from "../feishu/setup.js";
+import { feishuAppAddons } from "../feishu/setup-mode.js";
+import { SetupRefused } from "../setup.js";
+import { cloudFor } from "../feishu/cloud.js";
+/**
+ * Lark's one-click launcher, where the person creates the app. The launcher is unbound (the bound confirm page is broken
+ * on the international cloud), but it merges the `addons` query parameter onto the app it creates, as Feishu's does: the
+ * scopes and the event the channel needs arrive with the app, so nothing is ticked in the console afterwards. A tenant
+ * may still withhold a scope; the permission check that follows creation names it.
+ */
+export function larkLauncherUrl(way) {
+    const url = new URL("https://open.larksuite.com/page/launcher");
+    url.searchParams.set("from", "backend_oneclick");
+    url.searchParams.set("addons", encodeAddons(feishuAppAddons(way)));
+    return url.toString();
+}
+export const larkSetup = (context) => feishuEngine("lark", {
+    kind: "paste",
+    label: "App ID and App Secret",
+    guide: {
+        instructions: "Create the app on Lark's one-click launcher (it comes with the scopes and the event the channel needs), " +
+            "then copy its App ID and App Secret from Credentials & Basic Info.",
+        url: larkLauncherUrl(context.way),
+    },
+    fields: [
+        { name: "LARK_APP_ID", label: "App ID", secret: false },
+        { name: "LARK_APP_SECRET", label: "App Secret" },
+    ],
+    async check(values) {
+        const api = createFeishuApi({
+            kind: "lark",
+            baseUrl: cloudFor("lark").apiBase,
+            appId: values.LARK_APP_ID,
+            appSecret: values.LARK_APP_SECRET,
+        });
+        try {
+            await api.verifyCredentials();
+            return undefined;
+        }
+        catch (error) {
+            // Only a known credential refusal is a wrong pair; the network and the platform being down end the setup.
+            if (!isFeishuCredentialsRefused(error))
+                throw error;
+            throw new SetupRefused("Lark refused that App ID or Secret.", {
+                fix: "Copy both again from Credentials & Basic Info.",
+                why: `Lark said: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    },
+}, context);

package/dist/channels/setup.d.ts

@@ -0,0 +1,112 @@
+/**
+ * What setting up a channel's platform app asks of a person (channel-setup.md §2): the values only they have, where
+ * to find each one, and how to tell a wrong one from a right one before it is kept. A channel's own module says it
+ * (`channels/<kind>/setup.ts`); `cli/channel-setup.ts` asks, in a terminal or on a page, and writes what is accepted.
+ */
+/** How a channel receives (SPEC.md §8): which values its app needs depends on it. */
+export type SetupWay = "webhook" | "connection";
+/** Where a value is found: what to do, and the page to do it on. */
+export interface SetupGuide {
+    instructions: string;
+    url?: string;
+}
+/** The values of this setup so far: what the value file held and what each step has since kept. */
+export type HeldValues = ReadonlyMap<string, string>;
+/** One variable a pasted step asks for. */
+interface PasteField {
+    name: string;
+    /** What the platform calls it, so the person need not map one name to another. */
+    label: string;
+    /** Whether it is hidden as typed; every value is unless it is only an identifier (default true). */
+    secret?: boolean;
+}
+/**
+ * Values the person pastes: one step, its fields asked together and checked together (a Lark App ID is only right
+ * with its Secret).
+ */
+export interface PastedValues {
+    kind: "paste";
+    /** What the step is called on a page: "Bot User OAuth Token". */
+    label: string;
+    /** Where to find them; a function when the page depends on what an earlier step kept (an app's own console page). */
+    guide: SetupGuide | ((held: HeldValues) => SetupGuide);
+    fields: PasteField[];
+    /**
+     * Confirm `values` with the platform. Resolves with a note on what they are ("bot @acme_bot"), throws {@link
+     * SetupRefused} for values the platform refuses, and any other error for a check that could not be made (the
+     * network, the platform down), which ends the setup instead of re-asking for a value that may be right.
+     */
+    check(values: Record<string, string>): Promise<string | undefined>;
+    /**
+     * A way to get the value without asking (one field only): tried first, and the person is asked only when it
+     * resolves undefined, having said why. Not tried for a value that is already held.
+     */
+    capture?(held: HeldValues): Promise<string | undefined>;
+}
+/** One pasted variable, checked on its own. */
+export declare function pasteOne(input: {
+    name: string;
+    label: string;
+    secret?: boolean;
+    guide: PastedValues["guide"];
+    check(value: string): Promise<string | undefined>;
+    capture?: PastedValues["capture"];
+}): PastedValues;
+/** Values the platform makes when an app is created, which setup makes happen: all of them, or none. */
+interface CreatedValues {
+    kind: "create";
+    names: string[];
+    /** Create the app. `person` takes the step only they can (confirming it in the platform's own app). */
+    create(person: SetupPerson): Promise<Record<string, string>>;
+}
+/** What a creation waits on a person for; the parts of a `cli/person.ts` Person it uses. */
+interface SetupPerson {
+    waitsOn(url: string, instructions: string, until?: number): void;
+    carriesOn(): void;
+}
+/** A value setup makes itself. */
+interface MadeValue {
+    kind: "make";
+    name: string;
+    make(): string;
+}
+export type SetupValue = PastedValues | CreatedValues | MadeValue;
+/** What a channel needs to say its values: facts about the instance it is set up for. */
+interface SetupContext {
+    way: SetupWay;
+    /** A name for an app created for it (the agent's directory). */
+    appName: string;
+    /** Whether it is the development instance. */
+    dev: boolean;
+    /** Where the platform will reach it, when the configuration names one. */
+    publicUrl?: string;
+    /** The command that runs this setup again, for what a person is told to do before it. */
+    rerun: string;
+    /** A public URL for a local port, for a setup the platform must reach while it runs (a challenge to answer). */
+    startTunnel(port: number): Promise<{
+        url: string;
+        close(): void;
+    } | undefined>;
+}
+/**
+ * What a channel's setup asks for, in order, and what is left to the person once it is done (`finish`, told every
+ * value the instance now holds: what is left can depend on what the platform said about the app).
+ */
+interface SetupPlan {
+    values: SetupValue[];
+    finish(held: HeldValues): Promise<string[]> | string[];
+}
+export type ChannelSetup = (context: SetupContext) => SetupPlan;
+/**
+ * A pasted value the platform refuses. `fix` is what to do about it; `why` is the platform's own words, for someone
+ * who has to look it up.
+ */
+export declare class SetupRefused extends Error {
+    readonly fix: string | undefined;
+    readonly why: string | undefined;
+    constructor(headline: string, options?: {
+        fix?: string;
+        why?: string;
+    });
+}
+export {};

package/dist/channels/setup.js

@@ -0,0 +1,31 @@
+/**
+ * What setting up a channel's platform app asks of a person (channel-setup.md §2): the values only they have, where
+ * to find each one, and how to tell a wrong one from a right one before it is kept. A channel's own module says it
+ * (`channels/<kind>/setup.ts`); `cli/channel-setup.ts` asks, in a terminal or on a page, and writes what is accepted.
+ */
+/** One pasted variable, checked on its own. */
+export function pasteOne(input) {
+    const { name, label, secret, guide, check, capture } = input;
+    return {
+        kind: "paste",
+        label,
+        guide,
+        fields: [{ name, label, ...(secret === undefined ? {} : { secret }) }],
+        check: (values) => check(values[name]),
+        ...(capture === undefined ? {} : { capture }),
+    };
+}
+/**
+ * A pasted value the platform refuses. `fix` is what to do about it; `why` is the platform's own words, for someone
+ * who has to look it up.
+ */
+export class SetupRefused extends Error {
+    fix;
+    why;
+    constructor(headline, options = {}) {
+        super(headline);
+        this.name = "SetupRefused";
+        this.fix = options.fix;
+        this.why = options.why;
+    }
+}

package/dist/channels/slack/history.js

@@ -186,7 +186,7 @@ export function createSlackPlaceHistory(deps) {
             names.scopeMissing = true;
             if (!scopeWarned) {
                 scopeWarned = true;
-                log.warn(`${deps.label} users:read is not granted, so people are shown by user id — add it under the Slack app's OAuth & Permissions → Bot Token Scopes (an app \`fastagent add slack\` created gets it with the next \`dev --tunnel\` or \`deploy --run\`), then Reinstall to Workspace; names appear within 10 minutes, or after a restart if the reinstall issued a new Bot Token`);
+                log.warn(`${deps.label} users:read is not granted, so people are shown by user id — add it under the Slack app's OAuth & Permissions → Bot Token Scopes (an app \`fastagent channels setup slack\` creates has it), then Reinstall to Workspace; names appear within 10 minutes, or after a restart if the reinstall issued a new Bot Token`);
             }
         }
         else if (failures.length > 0) {

package/dist/channels/slack/manifest.d.ts

@@ -26,11 +26,10 @@ export interface SlackAppManifest {
         scopes: {
             bot: string[];
         };
-        redirect_urls?: string[];
     };
     settings: {
-        event_subscriptions?: {
-            request_url: string;
+        event_subscriptions: {
+            request_url?: string;
             bot_events: string[];
         };
         org_deploy_enabled: boolean;
@@ -38,9 +37,20 @@ export interface SlackAppManifest {
         token_rotation_enabled: boolean;
     };
 }
-export declare function slackBotScopes(): string[];
+/**
+ * What an app is created for: a Socket Mode app receives over a socket it opens and has no Request URL; one that
+ * receives by webhook needs one, because Slack refuses a manifest that subscribes to events without it. Slack creates
+ * the app whether or not that URL answers yet (it shows "Your URL didn't respond" and a Retry), so a placeholder stands
+ * in until a person sets the real one on the Event Subscriptions page.
+ */
+export type SlackManifestWay = {
+    ingress: "connection";
+} | {
+    ingress: "webhook";
+    requestUrl: string;
+};
 export declare function buildSlackManifest(input: {
     name: string;
-    requestUrl?: string;
-    redirectUrl?: string;
-}): SlackAppManifest;
+} & SlackManifestWay): SlackAppManifest;
+/** The page that creates an app from `manifest`, filled in: the person picks a workspace and clicks Create. */
+export declare function slackManifestLink(manifest: SlackAppManifest): string;