@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/channels/agentcore-service.js

@@ -1,6 +1,6 @@
 import { fromForwarder } from "./agentcore-protocol.js";
 import { log } from "../log.js";
-import { routesFor, serviceOver, startSchedules, } from "../service.js";
+import { routesFor, serviceOver, startSchedules, webhooksOf, } from "../service.js";
 import { agentcoreRoutes, agentcorePing } from "./agentcore.js";
 import * as Effect from "effect/Effect";
 import { fireScheduleOnce } from "../schedule/scheduler.js";
@@ -99,9 +99,10 @@ export async function mountAgentcoreService(opened) {
     // recurring schedule the container sets (`armAlarms`), ONE path per instant, so the reply to that delivery says
     // whether it ran. The clock still pumps wake-ups; a redelivered fire claims its slot once.
     const mirror = armAlarms(stateRoot, () => schedules);
+    const webhooks = webhooksOf(opened);
     const scheduled = startSchedules(agent, stateRoot, schedules, { localClock: false });
     const lazyChannels = async () => {
-        const lazy = routesFor(agent, stateRoot, opened.channels);
+        const lazy = routesFor(agent, stateRoot, opened.channels, webhooks.list);
         if (lazy.longConnections.length > 0) {
             throw new Error(`long-connection channel(s) ${lazy.longConnections.map((c) => c.name).join(", ")} cannot serve on ` +
                 `AgentCore (scale-to-zero severs resident connections) — use the channel's webhook form`);
@@ -113,13 +114,21 @@ export async function mountAgentcoreService(opened) {
         stateRoot,
         schedules: () => schedules,
         ...(mirror ? { onStateReady: mirror } : {}),
+        webhooks: {
+            list: webhooks.list,
+            // A custom domain the operator named in the configuration is where the platforms reach it, not the Function URL.
+            point: (forwarderUrl) => webhooks.register(opened.config.http?.publicUrl ?? forwarderUrl),
+        },
         channels: lazyChannels,
     });
     const handler = router(adapterRoutes);
     log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
     return {
         // Nothing to open: no port of its own, no resident connections.
-        ...serviceOver(handler, Promise.resolve(), async () => scheduled.stop()),
+        ...serviceOver(handler, Promise.resolve(), async () => {
+            webhooks.dispose();
+            await scheduled.stop();
+        }),
         // The adapter IS the surface here; the channel routes arrive lazily BEHIND it.
         routes: adapterRoutes,
         agentDir,
@@ -135,7 +144,7 @@ export async function mountAgentcoreService(opened) {
  * surface (channels/agentcore.ts).
  */
 export function mountAgentcore(options) {
-    const { agent, stateRoot, schedules, onStateReady, channels } = options;
+    const { agent, stateRoot, schedules, onStateReady, channels, webhooks } = options;
     // OCCURRENCE SEMANTICS, because this host's clock is ours: the container set the recurring schedule that names this
     // instant and the forwarder relays it behind the ingress secret, so a claim means something (dedup across
     // EventBridge's redeliveries, a fire history, the overlap policy).
@@ -172,6 +181,7 @@ export function mountAgentcore(options) {
         ingressSecret: process.env.FASTAGENT_INGRESS_SECRET,
         onStateReady,
         fireSchedule,
+        ...(webhooks ? { webhooks } : {}),
     });
 }
 /**

package/dist/channels/agentcore.d.ts

@@ -1,4 +1,5 @@
 import type { ChannelHandler, Routes } from "../channel.ts";
+import type { WebhookRegistration } from "./webhooks.ts";
 /**
  * What the lazy factory hands back: the CHANNELS' routes, and nothing else.
  *
@@ -33,6 +34,14 @@ export interface AgentcoreAdapterOptions {
     ingressSecret?: string;
     /** Runs once on activation, after accepting the current forwarder callback URL. */
     onStateReady?: () => void;
+    /**
+     * The webhook channels this container points at the forwarder: `point` is called once, on the first trusted
+     * envelope that constructed the channels, with the URL that envelope names; `list` is what a probe reports.
+     */
+    webhooks?: {
+        point(forwarderUrl: string): Promise<unknown>;
+        list(): readonly WebhookRegistration[];
+    };
 }
 export declare function agentcoreRoutes(options: AgentcoreAdapterOptions): Routes;
 export declare function agentcorePing(isBusy: () => boolean): ChannelHandler;

package/dist/channels/agentcore.js

@@ -41,8 +41,28 @@ function createActivation(deps) {
     };
 }
 export function agentcoreRoutes(options) {
-    const { channels, stateRoot, isBusy, fireSchedule, ingressSecret, onStateReady } = options;
+    const { channels, stateRoot, isBusy, fireSchedule, ingressSecret, onStateReady, webhooks } = options;
     const activation = createActivation({ stateRoot, onStateReady, channels });
+    // Under the process's busy signal: AgentCore reclaims a microVM with nothing in flight, and a registration is a
+    // call to the platform that must end.
+    let pointed = false;
+    const pointWebhooks = (url) => {
+        if (webhooks === undefined || pointed)
+            return;
+        pointed = true;
+        void (async () => {
+            const done = beginWork();
+            try {
+                await webhooks.point(url);
+            }
+            catch (error) {
+                log.error(`[agentcore] could not point the webhook channels at ${url}: ${String(error)}`);
+            }
+            finally {
+                done();
+            }
+        })();
+    };
     const carried = (request) => {
         const { method, path, query, headers, bodyB64 } = request;
         return new Request(`http://agentcore.local${path}${typeof query === "string" && query !== "" ? `?${query}` : ""}`, {
@@ -103,6 +123,8 @@ export function agentcoreRoutes(options) {
                 log.error(`[agentcore] channel construction failed: ${constructionError}`);
             }
         }
+        if (dispatch && typeof envelope.wake?.url === "string")
+            pointWebhooks(envelope.wake.url);
         switch (envelope.kind) {
             case "webhook": {
                 const { bodyB64 } = envelope;
@@ -160,9 +182,12 @@ export function agentcoreRoutes(options) {
             case "probe": {
                 // The structured verdict (transport-200 — see the envelope doc). From the IAM door (untrusted) nothing was
                 // activated, so `ok` says only that the definition opened; channel construction is the forwarder probe's.
-                return json(constructionError === undefined
-                    ? { ok: true }
-                    : { ok: false, error: `channel construction failed: ${constructionError}` }, 200);
+                if (constructionError !== undefined) {
+                    return json({ ok: false, error: `channel construction failed: ${constructionError}` }, 200);
+                }
+                return json(trusted
+                    ? { ok: true, webhooks: (webhooks?.list() ?? []).map((w) => ({ channel: w.channel, outcome: w.outcome })) }
+                    : { ok: true }, 200);
             }
             default:
                 return text(`unknown envelope kind "${envelope.kind}"\n`, 400);

package/dist/channels/context.d.ts

@@ -1,4 +1,6 @@
 import type { Agent } from "../agent-api.ts";
 import type { ChannelContext } from "../channel.ts";
+/** The directory of the channel `name`'s own state under `stateRoot`: its context's `stateDir`. */
+export declare function channelStateDir(stateRoot: string, name: string): string;
 /** The context of the channel `name` (its file's name under `src/channels/`), its state under `stateRoot`. */
 export declare function channelContext(agent: Agent, stateRoot: string, name: string): ChannelContext;

package/dist/channels/context.js

@@ -10,11 +10,15 @@ import { portError, portJoin } from "../effect-port.js";
 import { log } from "../log.js";
 import { ensureStateHome } from "../state-file.js";
 import { createTurnQueue } from "./turn-queue.js";
+/** The directory of the channel `name`'s own state under `stateRoot`: its context's `stateDir`. */
+export function channelStateDir(stateRoot, name) {
+    return join(stateRoot, "channels", name);
+}
 /** The context of the channel `name` (its file's name under `src/channels/`), its state under `stateRoot`. */
 export function channelContext(agent, stateRoot, name) {
     if (!isAbsolute(stateRoot))
         throw new Error(`a channel's state root must be absolute, got "${stateRoot}"`);
-    const stateDir = join(stateRoot, "channels", name);
+    const stateDir = channelStateDir(stateRoot, name);
     ensureStateHome(stateDir);
     const sessions = conversationSessions(join(stateDir, "sessions.json"));
     const turns = createTurnQueue({

package/dist/channels/feishu/feishu-api.d.ts

@@ -61,7 +61,7 @@ export interface FeishuListedMessage {
         sender_type?: string;
     };
 }
-export interface FeishuAppScope {
+interface FeishuAppScope {
     name: string;
     grantStatus: number;
     type?: "user" | "tenant";
@@ -177,3 +177,4 @@ export interface FeishuApi {
 /** Split text into chunks whose UTF-8 size fits the message cap, preferring a newline boundary. */
 export declare function chunkFeishuText(text: string, maxBytes?: number): string[];
 export declare function createFeishuApi(opts: FeishuApiOptions): FeishuApi;
+export {};

package/dist/channels/feishu/feishu.d.ts

@@ -1,6 +1,5 @@
 import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
 import { type FeishuCloudProfile } from "./cloud.ts";
-import { type FeishuSubscriptionMode } from "./setup-mode.ts";
 import { type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute, feishuEnvelope } from "./parse.ts";
 import { type FeishuFailure } from "./preview.ts";
 import { connectFeishuWs } from "./ws-ingress.ts";
@@ -31,8 +30,6 @@ export type FeishuWebSocketChannelOptions = FeishuChannelBaseOptions & {
 };
 /** Build the canonical Feishu Request-URL webhook channel. */
 export declare function feishuChannel(opts: FeishuChannelOptions): ChannelModule;
-/** How this process receives the Feishu channel: `FEISHU_INGRESS`, else WebSocket under `dev` and webhook otherwise. */
-export declare function feishuIngress(): FeishuSubscriptionMode;
 /** Build the canonical Feishu WebSocket long-connection channel. */
 export declare function feishuWebSocketChannel(opts: FeishuWebSocketChannelOptions): LongConnectionChannelModule;
 /** Internal compatibility seams: protocol behavior comes from Feishu; the profile binds cloud edges. */

package/dist/channels/feishu/feishu.js

@@ -2,6 +2,7 @@
  * Canonical Feishu bot-channel engine: verified webhook or official-SDK WebSocket → dedup → route → persist → enqueue
  * → stream a live card.
  */
+import { recordReached } from "../webhook-evidence.js";
 import { join } from "node:path";
 import { Effect } from "effect";
 import { log } from "../../log.js";
@@ -27,7 +28,7 @@ import { feishuTurnStream } from "./invoke-turn.js";
 import { createFeishuApi } from "./feishu-api.js";
 import { normalizeFeishuMessage } from "./normalize.js";
 import { createThreadParticipants } from "../kit/thread-participants.js";
-import { FEISHU_AGENT_SCOPES, feishuIngressFor, scopeSatisfied } from "./setup-mode.js";
+import { FEISHU_AGENT_SCOPES, scopeSatisfied } from "./setup-mode.js";
 import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderId, } from "./parse.js";
 import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, feishuReply, } from "./preview.js";
 import { connectFeishuWs } from "./ws-ingress.js";
@@ -75,10 +76,6 @@ function isStoredFeishuTurn(t) {
 export function feishuChannel(opts) {
     return buildFeishuChannel(FEISHU_CLOUD, opts, feishuChannel.name);
 }
-/** How this process receives the Feishu channel: `FEISHU_INGRESS`, else WebSocket under `dev` and webhook otherwise. */
-export function feishuIngress() {
-    return feishuIngressFor("feishu");
-}
 /** Build the canonical Feishu WebSocket long-connection channel. */
 export function feishuWebSocketChannel(opts) {
     return buildFeishuWebSocketChannel(FEISHU_CLOUD, opts, feishuWebSocketChannel.name);
@@ -418,7 +415,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         return { acceptEvent, turnsIdle: () => Promise.all([runner.idle(), sideTasks.drain()]).then(() => undefined) };
     };
 }
-function createFeishuWebhookRoutes(profile, opts, runtime) {
+function createFeishuWebhookRoutes(profile, opts, runtime, stateDir) {
     const { verificationToken, encryptKey } = opts;
     const { kind, envPrefix } = profile;
     const label = `[${kind}]`;
@@ -496,6 +493,9 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
             log.warn(`${label} rejected an event: verification token mismatch (check ${envPrefix}_VERIFICATION_TOKEN against the console)`);
             return text("invalid token\n", 401);
         }
+        // The platform's token: the Request URL reaches this instance, at the address it was sent to (Lark's, set by a
+        // person where its configuration API is missing).
+        recordReached(stateDir, req);
         if (envelope.type === "url_verification" && typeof envelope.challenge === "string") {
             log.info(`${label} answered the console's url_verification challenge`);
             return Response.json({ challenge: envelope.challenge });
@@ -517,11 +517,11 @@ export function buildFeishuChannel(profile, opts, factoryName) {
         if (!opts.verificationToken) {
             // The scaffolded file reaches this under `start` with nothing set, so the error names both ways out.
             throw new Error(`${factoryName} receives by webhook and needs a non-empty verificationToken: \`fastagent deploy <host> --run\` ` +
-                `or \`fastagent add ${profile.kind} --ingress webhook\` captures ${profile.envPrefix}_VERIFICATION_TOKEN ` +
-                `(console → Events & Callbacks has it too), or set ${profile.envPrefix}_INGRESS=websocket to receive by ` +
-                `WebSocket instead`);
+                `or \`fastagent channels setup ${profile.kind} --ingress webhook\` captures ${profile.envPrefix}_VERIFICATION_TOKEN ` +
+                `(console → Events & Callbacks has it too), or set channels.<name>.ingress to "connection" in the instance's ` +
+                `fastagent.json to receive by WebSocket instead`);
         }
-        return createFeishuWebhookRoutes(profile, opts, createRuntime(ctx));
+        return createFeishuWebhookRoutes(profile, opts, createRuntime(ctx), ctx.stateDir);
     };
 }
 export function buildFeishuWebSocketChannel(profile, opts, factoryName, deps = {}) {

package/dist/channels/feishu/register-app.js

@@ -6,6 +6,7 @@
  * it behind something non-trivial, adopt the official SDK rather than chasing it.
  */
 import { gzipSync } from "node:zlib";
+import { stripEnd } from "../../strip-edges.js";
 /** Feishu accounts endpoint (the flow starts here for every user; a Lark-tenant scan switches over). */
 const FEISHU_ACCOUNTS = "https://accounts.feishu.cn";
 const LARK_ACCOUNTS = "https://accounts.larksuite.com";
@@ -14,11 +15,8 @@ const ENDPOINT = "/oauth/v1/app/registration";
 const REQUEST_TIMEOUT_MS = 30_000;
 /** JSON → gzip → base64url — the platform's fixed addons encoding. */
 export function encodeAddons(addons) {
-    return gzipSync(Buffer.from(JSON.stringify(addons), "utf8"))
-        .toString("base64")
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=+$/, "");
+    const base64 = gzipSync(Buffer.from(JSON.stringify(addons), "utf8")).toString("base64");
+    return stripEnd(base64.replace(/\+/g, "-").replace(/\//g, "_"), (char) => char === "=");
 }
 /** RFC 8628 device-flow states whose non-2xx JSON bodies belong to the polling state machine. */
 const DEVICE_FLOW_ERRORS = new Set(["authorization_pending", "slow_down", "access_denied", "expired_token"]);

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

@@ -1,20 +1,17 @@
-import { needs } from "@fastagent-sh/fastagent";
-import {
-  type FeishuChannelOptions,
-  feishuChannel,
-  feishuIngress,
-  feishuWebSocketChannel,
-} from "@fastagent-sh/fastagent/feishu";
+import { byIngress, needs } from "@fastagent-sh/fastagent";
+import { type FeishuChannelOptions, feishuChannel, feishuWebSocketChannel } from "@fastagent-sh/fastagent/feishu";
 
 // fastagent's canonical Feishu adapter (verify + run + reply), configured with YOUR policy. Feishu
 // (open.feishu.cn) only; a Lark-international tenant uses `fastagent add lark` instead.
 //
-// How it receives is FEISHU_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 /feishu. Dev reads .secrets/.env; production reads
-// .secrets/production/.env. Interactive `deploy --run` creates a separate production app.
+// How it receives is the instance's choice, `channels.feishu.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 /feishu, the way a host that
+// wakes on a request is reached.
+// Dev reads .secrets/.env; production reads .secrets/production/.env. Interactive `deploy --run`
+// creates a separate production app.
 //
-// `fastagent add feishu` creates and configures the app (scan-to-create). For a hand-made app, in the
+// `fastagent channels setup feishu` creates and configures the app (scan-to-create). For a hand-made app, 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`
@@ -45,25 +42,26 @@ const policy: Pick<FeishuChannelOptions, "onError" | "route"> = {
   //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(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. FEISHU_ENCRYPT_KEY is optional.
-export default feishuIngress() === "webhook"
-  ? needs(
-      [
-        "FEISHU_APP_ID",
-        "FEISHU_APP_SECRET",
-        "FEISHU_VERIFICATION_TOKEN",
-        { name: "FEISHU_ENCRYPT_KEY", description: "when set, plaintext events are refused", optional: true },
-      ],
-      (secrets) =>
-        feishuChannel({
-          appId: secrets.FEISHU_APP_ID,
-          appSecret: secrets.FEISHU_APP_SECRET,
-          verificationToken: secrets.FEISHU_VERIFICATION_TOKEN, // authenticates inbound events
-          encryptKey: secrets.FEISHU_ENCRYPT_KEY,
-          ...policy,
-        }),
-    )
-  : needs(["FEISHU_APP_ID", "FEISHU_APP_SECRET"], (secrets) =>
-      feishuWebSocketChannel({ appId: secrets.FEISHU_APP_ID, appSecret: secrets.FEISHU_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. FEISHU_ENCRYPT_KEY is optional.
+export default byIngress({
+  webhook: needs(
+    [
+      "FEISHU_APP_ID",
+      "FEISHU_APP_SECRET",
+      "FEISHU_VERIFICATION_TOKEN",
+      { name: "FEISHU_ENCRYPT_KEY", description: "when set, plaintext events are refused", optional: true },
+    ],
+    (secrets) =>
+      feishuChannel({
+        appId: secrets.FEISHU_APP_ID,
+        appSecret: secrets.FEISHU_APP_SECRET,
+        verificationToken: secrets.FEISHU_VERIFICATION_TOKEN, // authenticates inbound events
+        encryptKey: secrets.FEISHU_ENCRYPT_KEY,
+        ...policy,
+      }),
+  ),
+  connection: needs(["FEISHU_APP_ID", "FEISHU_APP_SECRET"], (secrets) =>
+    feishuWebSocketChannel({ appId: secrets.FEISHU_APP_ID, appSecret: secrets.FEISHU_APP_SECRET, ...policy }),
+  ),
+});

package/dist/channels/feishu/scaffold/feishu-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 { feishuTransport } from "@fastagent-sh/fastagent/feishu";
@@ -18,10 +18,10 @@ export default needs(["FEISHU_APP_ID", "FEISHU_APP_SECRET"], (secrets) =>
       "or memory); the [feishu: 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/feishu/scaffold/feishu-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 { feishuThreads } from "@fastagent-sh/fastagent/feishu";
@@ -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 = feishuThreads(await sessionIdOf(api, context));

package/dist/channels/feishu/setup-mode.d.ts

@@ -1,15 +1,5 @@
-import { type FeishuCloudKind } from "./cloud.ts";
 /** Feishu/Lark app-level event subscription choice: how a channel receives, and what an app is set up for. */
-export type FeishuSubscriptionMode = "webhook" | "websocket";
-/** The settings {@link feishuIngressFor} reads, one per cloud: what `deploy` must read the way the box will. */
-export declare const FEISHU_INGRESS_SETTINGS: string[];
-/**
- * How THIS process receives a Feishu/Lark channel (docs/design/channel-environments.md): `<PREFIX>_INGRESS` when the
- * environment names one, else WebSocket under `dev` (no public URL, no reviewed scope) and webhook everywhere else,
- * which is what every deployment runs. The channel file asks at import, and so does every reader of its shape: `deploy`
- * inspects it in a process that is not `dev`, with the same value file loaded, so it sees what the box will serve.
- */
-export declare function feishuIngressFor(kind: FeishuCloudKind, env?: NodeJS.ProcessEnv): FeishuSubscriptionMode;
+export type FeishuSubscriptionMode = "webhook" | "connection";
 /**
  * Configuring THIS app through the v7 config API: registering a webhook Request URL and switching the subscription
  * mode. Requested for a webhook app only. A tenant may review it, and a scope under review holds the app's whole first
@@ -46,7 +36,7 @@ export declare const FEISHU_AGENT_SCOPES: FeishuScopeRequest[];
 export declare function feishuAppScopes(ingress: FeishuSubscriptionMode): FeishuScopeRequest[];
 /**
  * What a created app carries on top of the platform's agent template — the `addons` merged onto the confirm page. A
- * scope that arrives here needs no console visit; one a tenant withholds is reported after creation (`add-feishu.ts`).
+ * scope that arrives here needs no console visit; one a tenant withholds is reported after creation (`setup.ts`).
  */
 export declare function feishuAppAddons(ingress: FeishuSubscriptionMode): {
     scopes: {

package/dist/channels/feishu/setup-mode.js

@@ -1,23 +1,3 @@
-import { servedByDev } from "../../serving-command.js";
-import { cloudFor } from "./cloud.js";
-/** The settings {@link feishuIngressFor} reads, one per cloud: what `deploy` must read the way the box will. */
-export const FEISHU_INGRESS_SETTINGS = ["feishu", "lark"].map((kind) => `${cloudFor(kind).envPrefix}_INGRESS`);
-/**
- * How THIS process receives a Feishu/Lark channel (docs/design/channel-environments.md): `<PREFIX>_INGRESS` when the
- * environment names one, else WebSocket under `dev` (no public URL, no reviewed scope) and webhook everywhere else,
- * which is what every deployment runs. The channel file asks at import, and so does every reader of its shape: `deploy`
- * inspects it in a process that is not `dev`, with the same value file loaded, so it sees what the box will serve.
- */
-export function feishuIngressFor(kind, env = process.env) {
-    const name = `${cloudFor(kind).envPrefix}_INGRESS`;
-    const raw = env[name]?.trim();
-    if (!raw)
-        return servedByDev(env) ? "websocket" : "webhook";
-    if (raw !== "webhook" && raw !== "websocket") {
-        throw new Error(`${name} must be "webhook" or "websocket", got "${raw}"`);
-    }
-    return raw;
-}
 /**
  * Configuring THIS app through the v7 config API: registering a webhook Request URL and switching the subscription
  * mode. Requested for a webhook app only. A tenant may review it, and a scope under review holds the app's whole first
@@ -57,7 +37,7 @@ export const FEISHU_AGENT_SCOPES = [
 /** The config scope as an app needs it: webhook only ({@link FEISHU_APP_CONFIG_SCOPE}). */
 const FEISHU_APP_CONFIG_REQUEST = {
     request: FEISHU_APP_CONFIG_SCOPE,
-    withoutIt: "the Verification Token is not captured and no Request URL is registered for you (add, dev --tunnel, deploy --run)",
+    withoutIt: "the Verification Token is not captured and no Request URL is registered for you (channels setup, dev --tunnel, deploy --run)",
 };
 /**
  * Every scope an app of this ingress needs: what onboarding requests at creation AND what it checks the app holds, so a
@@ -68,7 +48,7 @@ export function feishuAppScopes(ingress) {
 }
 /**
  * What a created app carries on top of the platform's agent template — the `addons` merged onto the confirm page. A
- * scope that arrives here needs no console visit; one a tenant withholds is reported after creation (`add-feishu.ts`).
+ * scope that arrives here needs no console visit; one a tenant withholds is reported after creation (`setup.ts`).
  */
 export function feishuAppAddons(ingress) {
     return {

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

@@ -0,0 +1,12 @@
+/**
+ * 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 { type ChannelSetup, type SetupValue } from "../setup.ts";
+import { type FeishuCloudKind } from "./cloud.ts";
+/** The setup of a Feishu or Lark app whose credentials are `credentials`. */
+export declare function feishuEngine(kind: FeishuCloudKind, credentials: SetupValue, context: Parameters<ChannelSetup>[0]): ReturnType<ChannelSetup>;
+export declare const feishuSetup: ChannelSetup;