@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/channels/feishu/history.js

@@ -0,0 +1,199 @@
+/**
+ * A Feishu/Lark place's history, read from `im/v1/messages` when a turn runs (docs/design/place-history.md). What a
+ * place remembers between turns, and what a read leaves out, is the kit's (`createPlaceHistory`); this is the read:
+ * newest first up to the turn's own ask (`end_time` in seconds, then `(create_time, message_id)`), back to the cursor,
+ * with senders named from the chat's members.
+ */
+import { log } from "../../log.js";
+import { capBufferedRefs } from "../kit/context-buffer.js";
+import { createPlaceHistory, } from "../kit/place-history.js";
+import { threadList } from "../kit/room-threads.js";
+import { CONTEXT_READ } from "../kit/transport.js";
+import { decodeFeishuContent } from "./normalize.js";
+/** How many of a place's newest messages one read lists; a place busier than this since its last answer says so. */
+const PAGE_SIZE = 50;
+/** What a place's first answered turn reads back, with no cursor yet. */
+const FIRST_READ = 20;
+/** How long a chat's member names are reused before they are read again. */
+const NAMES_TTL_MS = 10 * 60_000;
+/** Someone said it: not deleted, and not the platform's own (a system message has no sender). */
+function isSpoken(item) {
+    return item.deleted !== true && item.msg_type !== "system" && Boolean(item.sender?.sender_type);
+}
+/** A place: the chat, or a thread within it. The turn record carries it as this key. */
+export function feishuHistoryKey(place) {
+    return place.threadId ? `${place.chatId}:thread:${place.threadId}` : place.chatId;
+}
+/** The inverse of {@link feishuHistoryKey}. */
+export function feishuPlaceOf(key) {
+    const at = key.indexOf(":thread:");
+    return at === -1 ? { chatId: key } : { chatId: key.slice(0, at), threadId: key.slice(at + ":thread:".length) };
+}
+/** Select the most recent background resources of the folded messages, excluding the turn's own primary ones. */
+export function collectFoldedAttachments(folded, primary) {
+    const identity = (ref) => `${ref.messageId}\u0000${ref.key}`;
+    const refs = (pick, primaryRefs) => {
+        const seen = new Set(primaryRefs.map(identity));
+        const out = [];
+        for (const message of folded) {
+            for (const resource of pick(message)) {
+                const ref = { messageId: message.id, ...resource, from: message.from.label };
+                if (seen.has(identity(ref)))
+                    continue;
+                seen.add(identity(ref));
+                out.push(ref);
+            }
+        }
+        return out;
+    };
+    const files = capBufferedRefs(refs((message) => message.files, primary.files));
+    const images = capBufferedRefs(refs((message) => message.images, primary.images));
+    return { files: files.kept, images: images.kept, skipped: files.skipped + images.skipped };
+}
+export function createFeishuPlaceHistory(deps) {
+    const { api, appId, label } = deps;
+    /**
+     * Per chat, the speakers already looked up: named, or known to have no name to find (not a member, past the page
+     * cap, or a failed read). Both halves expire together, so a failure or a newcomer is retried after the TTL, not on
+     * every turn.
+     */
+    const names = new Map();
+    /** Names for the speakers a fold shows; one not found is shown by open_id. Never rejects: a name is a label. */
+    const memberNames = async (chatId, speakers) => {
+        const cached = names.get(chatId);
+        const entry = cached && Date.now() - cached.at < NAMES_TTL_MS
+            ? cached
+            : { named: new Map(), unnamed: new Set(), at: Date.now() };
+        names.set(chatId, entry);
+        const unknown = new Set([...speakers].filter((id) => !entry.named.has(id) && !entry.unnamed.has(id)));
+        if (unknown.size === 0)
+            return entry.named;
+        try {
+            const { names: found, complete } = await api.chatMemberNames(chatId, unknown, CONTEXT_READ);
+            for (const [id, name] of found)
+                entry.named.set(id, name);
+            const missing = [...unknown].filter((id) => !found.has(id));
+            for (const id of missing)
+                entry.unnamed.add(id);
+            // A complete list without them is ordinary (they left the chat); a list cut at the page cap is a gap to say.
+            if (!complete && missing.length > 0) {
+                log.warn(`${label} chat ${chatId} has more members than one name read covers; ${missing.length} speaker(s) are shown by open_id`);
+            }
+        }
+        catch (error) {
+            for (const id of unknown)
+                entry.unnamed.add(id);
+            log.warn(`${label} could not read chat ${chatId}'s member names (speakers are shown by id): ${String(error)}`);
+        }
+        return entry.named;
+    };
+    /** One listed message as a fold shows it; `people` names the humans among its speakers. */
+    const placeMessage = (item, id, at, people) => {
+        const decoded = decodeFeishuContent({
+            message_type: item.msg_type ?? "unknown",
+            content: item.body?.content ?? "",
+            // The list API names a mention's id as a bare string; the decoder needs only key and name.
+            mentions: item.mentions?.flatMap((mention) => (mention.key ? [{ key: mention.key, name: mention.name }] : [])),
+        });
+        const senderId = item.sender?.id ?? "unknown";
+        const from = item.sender?.sender_type === "app"
+            ? senderId === appId
+                ? { kind: "self", label: "you" }
+                : { kind: "bot", label: `bot ${senderId}` }
+            : { kind: "human", label: people.get(senderId) ?? `user ${senderId}` };
+        return {
+            id,
+            at,
+            from,
+            text: decoded.text,
+            ...(item.parent_id ? { replyTo: item.parent_id } : {}),
+            images: decoded.resources.filter((r) => r.kind === "image").map((r) => ({ key: r.key })),
+            files: decoded.resources
+                .filter((r) => r.kind === "file" || r.kind === "audio" || r.kind === "video")
+                .map((r) => ({ key: r.key, ...(r.name ? { name: r.name } : {}) })),
+        };
+    };
+    /** The place's messages since its cursor (or its newest {@link FIRST_READ}), oldest first, minus the session's own. */
+    const read = async (key, { cursor, drop }, until) => {
+        const place = feishuPlaceOf(key);
+        const listed = await api.listMessages(place.threadId ? { type: "thread", id: place.threadId } : { type: "chat", id: place.chatId }, PAGE_SIZE, 
+        // Seconds, inclusive: the same second's later messages still arrive, and are skipped below by time.
+        until ? Math.floor(until.at / 1000) : undefined, CONTEXT_READ);
+        // A thread id names a thread in ANY chat the bot is in: its key's chat is a claim this read checks.
+        const stranger = place.threadId ? listed.items.find((item) => item.chat_id !== place.chatId) : undefined;
+        if (stranger)
+            throw new Error(`thread ${place.threadId} is not in chat ${place.chatId}`);
+        const fresh = [];
+        let reachedCursor = false;
+        for (const item of listed.items) {
+            const id = item.message_id;
+            const at = Number(item.create_time);
+            if (!id || !Number.isFinite(at))
+                continue;
+            if (until && (id === until.id || at > until.at))
+                continue;
+            if (cursor && (id === cursor.id || at < cursor.at)) {
+                reachedCursor = true;
+                break;
+            }
+            fresh.push({ item, id, at });
+            if (!cursor && fresh.length >= FIRST_READ)
+                break;
+        }
+        const newest = fresh[0] ? { at: fresh[0].at, id: fresh[0].id } : undefined;
+        const earlier = cursor
+            ? !reachedCursor && (listed.hasMore || listed.items.length >= PAGE_SIZE)
+            : fresh.length >= FIRST_READ && (listed.items.length > FIRST_READ || listed.hasMore);
+        const covered = fresh.map(({ id }) => id);
+        const kept = fresh.reverse().filter(({ item, id }) => {
+            if (!isSpoken(item))
+                return false;
+            // A topic group lists every topic's replies with its chat; the room is its top-level messages.
+            if (!place.threadId && item.thread_id && item.root_id)
+                return false;
+            return !drop(id);
+        });
+        const speakers = new Set(kept.flatMap(({ item }) => (item.sender?.sender_type === "user" && item.sender.id ? [item.sender.id] : [])));
+        const people = speakers.size > 0 ? await memberNames(place.chatId, speakers) : new Map();
+        const messages = kept.map(({ item, id, at }) => placeMessage(item, id, at, people));
+        return { covered, messages, ...(newest ? { newest } : {}), earlier };
+    };
+    /**
+     * The chat's threads among its newest {@link PAGE_SIZE} messages. Feishu has no thread list: an ordinary group lists
+     * each thread's root (no reply count, no last activity), a topic group every message with its thread's id.
+     */
+    const threads = async (chatId) => {
+        const listed = await api.listMessages({ type: "chat", id: chatId }, PAGE_SIZE, undefined, CONTEXT_READ);
+        // Newest first, so a thread's first entry is its newest message seen and its last the earliest.
+        const byThread = new Map();
+        for (const item of listed.items) {
+            const at = Number(item.create_time);
+            if (!item.thread_id || !item.message_id || !isSpoken(item) || !Number.isFinite(at))
+                continue;
+            byThread.set(item.thread_id, [...(byThread.get(item.thread_id) ?? []), { item, id: item.message_id, at }]);
+        }
+        const openers = [...byThread.values()].map((seen) => seen.at(-1));
+        const speakers = new Set(openers.flatMap(({ item }) => (item.sender?.sender_type === "user" && item.sender.id ? [item.sender.id] : [])));
+        const people = speakers.size > 0 ? await memberNames(chatId, speakers) : new Map();
+        const summaries = [...byThread].map(([id, seen]) => {
+            const opener = seen.at(-1);
+            const message = placeMessage(opener.item, opener.id, opener.at, people);
+            // A reply is the thread's last activity this read saw; a root alone may have replies the listing omits.
+            const newest = seen[0];
+            const time = newest.item.root_id
+                ? { at: newest.at, is: "last active" }
+                : { at: opener.at, is: "started" };
+            return { id, time, first: { label: message.from.label, text: message.text } };
+        });
+        return threadList(summaries, `this chat's newest ${PAGE_SIZE} messages`);
+    };
+    const history = createPlaceHistory({
+        label,
+        path: deps.path,
+        isCursor: (value) => typeof value?.at === "number" && typeof value.id === "string",
+        compare: (a, b) => a.at - b.at,
+        isTurnInput: (_key, id) => deps.isTurnInput(id),
+        read,
+    });
+    return { ...history, threads };
+}

package/dist/channels/feishu/invoke-turn.d.ts

@@ -12,11 +12,11 @@
  * ancestors, and degrade per attachment: one expired background file must not block the current ask
  * or hide its still-readable siblings.
  */
-import type { Agent, AgentEvent } from "../../agent.ts";
+import type { Agent } from "../../agent-api.ts";
 import type * as Stream from "effect/Stream";
 import type { PortFailure } from "../../effect-port.ts";
-import { type BusyRetry } from "../kit/invoke-turn-kit.ts";
-import type { FeishuBufferedRef } from "./context-buffer.ts";
+import { type TurnEvent } from "../kit/invoke-turn-kit.ts";
+import type { FeishuBufferedRef } from "./history.ts";
 import type { FeishuApi } from "./feishu-api.ts";
 /** Everything the transport needs to fetch a turn's attachments. */
 export interface FeishuTurnTransport {
@@ -28,11 +28,6 @@ export interface FeishuTurnTransport {
      *  sender is an app. Needed to tell the agent's OWN messages from any other bot's in the same chat:
      *  `sender_type` alone says "some app", which is not the question the referent path asks. */
     appId: string;
-    /** The place this thread branched from (the chat's main place), when the turn runs in a thread —
-     *  rides the Scope's lineage extension so a NEW thread session starts from what the room knew
-     *  (participant-model.md §5). The engine reads it once, at session creation; every later turn
-     *  carries it inertly. */
-    parentSession?: string;
 }
 /** An attachment reference: the resource key inside its CARRYING message (the resource API addresses
  *  bytes by message_id + key, so the pair travels together through the turn record). */
@@ -56,8 +51,15 @@ export interface FeishuTurnAttachments {
     };
 }
 /**
- * Run one turn: resolve its inputs, then ask the agent (invoke-turn-kit — a primary-input failure
- * surfaces as a `failed` event, never a silent drop).
+ * Run one turn: resolve its inputs, then ask the agent (invoke-turn-kit — a preparation failure surfaces as a
+ * `rejected` event, never a silent drop). `key` is the turn's: the message it answers, which is also how a later
+ * thread finds the message this one becomes. `session` gets the reply chain's ids, where a new thread forks from.
  */
-export declare function feishuTurnStream(agent: Agent, session: string, text: string, transport: FeishuTurnTransport, attachments: FeishuTurnAttachments, busyRetry?: BusyRetry): Stream.Stream<AgentEvent, PortFailure>;
+export declare function feishuTurnStream(agent: Agent, turn: {
+    session: (referentIds: readonly string[]) => Promise<string>;
+    /** While it runs, the room its thread-reading tool reads (a group turn's chat). */
+    enter?: (sessionId: string) => () => void;
+    key: string;
+    text: string;
+}, transport: FeishuTurnTransport, attachments: FeishuTurnAttachments): Stream.Stream<TurnEvent, PortFailure>;
 export {};

package/dist/channels/feishu/invoke-turn.js

@@ -1,5 +1,5 @@
 import { log } from "../../log.js";
-import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, loadBackground, missingAttachmentsNote, turnStream, } from "../kit/invoke-turn-kit.js";
+import { attachedFilesManifest, attributedFileName, backgroundImagesManifest, loadBackground, missingAttachmentsNote, turnStream, promptContent, } from "../kit/invoke-turn-kit.js";
 import { BUFFER_ATTACH_MAX } from "../kit/context-buffer.js";
 import { parseContent } from "./parse.js";
 import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../kit/text.js";
@@ -226,21 +226,20 @@ async function resolveTurnInputs(t, attachments) {
     };
 }
 /**
- * Run one turn: resolve its inputs, then ask the agent (invoke-turn-kit — a primary-input failure
- * surfaces as a `failed` event, never a silent drop).
+ * Run one turn: resolve its inputs, then ask the agent (invoke-turn-kit — a preparation failure surfaces as a
+ * `rejected` event, never a silent drop). `key` is the turn's: the message it answers, which is also how a later
+ * thread finds the message this one becomes. `session` gets the reply chain's ids, where a new thread forks from.
  */
-export function feishuTurnStream(agent, session, text, transport, attachments, busyRetry = DEFAULT_BUSY_RETRY) {
+export function feishuTurnStream(agent, turn, transport, attachments) {
     return turnStream({
         agent,
         label: transport.label,
-        busyRetry,
+        session: (resolved) => turn.session(resolved.referentIds),
+        ...(turn.enter === undefined ? {} : { enter: turn.enter }),
         resolve: () => resolveTurnInputs(transport, attachments),
         turn: (resolved) => ({
-            // Lineage is resolved per turn; the engine reads it only when creating a new session.
-            scope: (transport.parentSession === undefined
-                ? { session }
-                : { session, parentSession: transport.parentSession, branchHints: resolved.referentIds }),
-            prompt: { text: `${text}${resolved.promptSuffix}${REPLY_INSTRUCTION}`, images: resolved.images },
+            idempotencyKey: turn.key,
+            content: promptContent(`${turn.text}${resolved.promptSuffix}${REPLY_INSTRUCTION}`, resolved.images),
         }),
         // A resource fetch that failed may simply succeed on the redelivery.
         retryableLoadFailure: () => true,

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

@@ -54,7 +54,8 @@ export interface FeishuMessageEvent {
 }
 /** Existing public route result: act with these overrides, or return null to ignore the message. */
 export interface FeishuRoute {
-    session?: string;
+    /** Which conversation it belongs to, the one its session is kept by (default: the chat, or the thread). */
+    conversation?: string;
     chatId?: string;
     text?: string;
 }

package/dist/channels/feishu/normalize.js

@@ -45,6 +45,95 @@ function renderNodes(nodes, resources) {
     }
     return parts.join("").trim();
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Text components of a card as sent, whose `content` is what a reader sees. */
+const CARD_TEXT_TAGS = new Set(["markdown", "plain_text", "lark_md"]);
+/**
+ * Whether a card body is the card as SENT (`card_msg_content_type=user_card_content`): a Card 2.0 has `body`, a card
+ * 1.0 has a `header` object, component objects in `elements`, or per-locale `i18n_elements`. The rendered-down shape
+ * is a string `title` and `elements` of paragraph ARRAYS.
+ */
+function isSentCard(card) {
+    return (isRecord(card.body) ||
+        isRecord(card.header) ||
+        isRecord(card.i18n_elements) ||
+        (Array.isArray(card.elements) && card.elements.some((element) => isRecord(element))));
+}
+/** A card's declared `config.locales`, in order: the locales a multi-language card is read in, first carried wins. */
+function declaredLocales(card) {
+    const declared = isRecord(card.config) && Array.isArray(card.config.locales) ? card.config.locales : [];
+    return declared.filter((locale) => typeof locale === "string");
+}
+/**
+ * One locale's form out of per-locale `forms`: the first declared locale it carries, else the first it carries. A card
+ * holds the same content once per locale; one of them is the content.
+ */
+function pickLocale(forms, locales) {
+    const declared = locales.find((locale) => locale in forms);
+    return declared !== undefined ? forms[declared] : Object.values(forms)[0];
+}
+/** A text field's value: `content`, else its per-locale form (1.0 `i18n`, 2.0 `i18n_content`). */
+function localizedText(node, locales) {
+    const own = nonEmptyString(node.content)?.trim();
+    if (own)
+        return own;
+    for (const key of ["i18n", "i18n_content"]) {
+        const forms = node[key];
+        if (!isRecord(forms))
+            continue;
+        const text = nonEmptyString(pickLocale(forms, locales))?.trim();
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+/**
+ * A sent card's visible text, in reading order: the header title, then every text component, through the containers
+ * (columns, panels, forms, a 1.0 `div`'s fields and `extra`, an action row) that nest them, with a control's label or
+ * placeholder. An image or a table says it is there; controls with no text say nothing. Card 2.0 keeps its components in `body.elements`, card 1.0 in `elements`.
+ */
+function sentCardLines(card) {
+    const lines = [];
+    const locales = declaredLocales(card);
+    const titleOf = (header) => isRecord(header) && isRecord(header.title) ? localizedText(header.title, locales) : undefined;
+    const title = titleOf(card.header);
+    if (title)
+        lines.push(title);
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const child of node)
+                visit(child);
+            return;
+        }
+        if (!isRecord(node))
+            return;
+        // A collapsible panel's title is the one line it shows folded.
+        const panelTitle = titleOf(node.header);
+        if (panelTitle)
+            lines.push(panelTitle);
+        const content = localizedText(node, locales);
+        if (typeof node.tag === "string" && CARD_TEXT_TAGS.has(node.tag) && content)
+            lines.push(content);
+        else if (node.tag === "img")
+            lines.push("[image]");
+        // Rows of typed cells, not text components: said, so the rest of the card does not read as the whole of it.
+        else if (node.tag === "table")
+            lines.push("[table]");
+        // A control's visible words: a button's or a div's `text`, a picker's `placeholder`.
+        for (const key of ["text", "placeholder"]) {
+            const label = isRecord(node[key]) ? localizedText(node[key], locales) : undefined;
+            if (label)
+                lines.push(label);
+        }
+        for (const key of ["elements", "columns", "fields", "actions", "extra"])
+            visit(node[key]);
+    };
+    const i18nElements = isRecord(card.i18n_elements) ? pickLocale(card.i18n_elements, locales) : undefined;
+    visit(isRecord(card.body) ? card.body.elements : (card.elements ?? i18nElements));
+    return lines;
+}
 function nonEmptyString(value) {
     return typeof value === "string" && value !== "" ? value : undefined;
 }
@@ -90,6 +179,17 @@ export function decodeFeishuContent(message) {
         // A CARD, as the platform hands it BACK.
         case "interactive":
         case "card": {
+            // As SENT (`card_msg_content_type=user_card_content`, what every read asks for): a Card 2.0 (every answer this
+            // channel streams) or a card 1.0 (what many CI and alert bots post).
+            // A card sent from a template is, as sent, a reference (`template_id` + variables), and its text was never in
+            // the message. Said in the prompt, so the model does not read the marker as an empty card.
+            if (content.type === "template") {
+                return { text: `[${rawType} message: a template card; its text cannot be read]`, resources };
+            }
+            if (isSentCard(content)) {
+                const lines = sentCardLines(content);
+                return { text: lines.length > 0 ? lines.join("\n") : `[${rawType} message]`, resources };
+            }
             const lines = [];
             const title = nonEmptyString(content.title);
             if (title)

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

@@ -1,4 +1,4 @@
-import type { AgentEvent } from "../../agent.ts";
+import type { TurnEvent } from "../kit/invoke-turn-kit.ts";
 import * as Effect from "effect/Effect";
 import type * as Stream from "effect/Stream";
 import { type PortFailure } from "../../effect-port.ts";
@@ -29,4 +29,4 @@ export declare function settleFeishuPreview(api: FeishuApi, target: FeishuTarget
 /**
  * Consume one turn's event stream into a Feishu-compatible chat, live.
  */
-export declare function feishuReply(events: Stream.Stream<AgentEvent, PortFailure>, api: FeishuApi, target: FeishuTarget, formatError: (failed: FeishuFailure) => string | undefined, initialPreview?: MountedFeishuPreview, label?: string, onAnswered?: (answer: string) => void): Effect.Effect<void, PortFailure, import("effect/Scope").Scope>;
+export declare function feishuReply(events: Stream.Stream<TurnEvent, PortFailure>, api: FeishuApi, target: FeishuTarget, formatError: (failed: FeishuFailure) => string | undefined, initialPreview?: MountedFeishuPreview, label?: string, onAnswered?: (answer: string) => void): Effect.Effect<void, PortFailure, import("effect/Scope").Scope>;

package/dist/channels/feishu/register-webhook.d.ts

@@ -6,6 +6,7 @@ interface FeishuManualRegistration {
     requestUrl: string;
 }
 export interface RegisterFeishuWebhookOptions {
+    env?: NodeJS.ProcessEnv;
     attempts?: number;
     retryMs?: number;
     apiBase?: string;

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

@@ -9,8 +9,9 @@ import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistratio
 export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
     const profile = cloudFor(kind);
     const envPrefix = profile.envPrefix;
-    const appId = process.env[`${envPrefix}_APP_ID`];
-    const appSecret = process.env[`${envPrefix}_APP_SECRET`];
+    const env = opts.env ?? process.env;
+    const appId = env[`${envPrefix}_APP_ID`];
+    const appSecret = env[`${envPrefix}_APP_SECRET`];
     const apiBase = opts.apiBase ?? profile.apiBase;
     const requestUrl = `${baseUrl}/${kind}`;
     const manual = `switch Subscription mode to webhook and set the event Request URL in the developer console (Events & Callbacks) to ${requestUrl} — keep the server running while you save (the console verifies the URL with a challenge)`;

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

@@ -1,50 +1,69 @@
-import { feishuChannel } from "@fastagent-sh/fastagent/feishu";
-import { defineChannel } from "@fastagent-sh/fastagent";
+import { needs } from "@fastagent-sh/fastagent";
+import {
+  type FeishuChannelOptions,
+  feishuChannel,
+  feishuIngress,
+  feishuWebSocketChannel,
+} from "@fastagent-sh/fastagent/feishu";
 
-// feishuChannel is fastagent's canonical Feishu adapter (verify + run + reply), configured with YOUR
-// policy. fastagent discovers this file, mounts POST /feishu, and pipes the agent + state home to it.
-// Feishu (open.feishu.cn) only; a Lark-international
-// tenant uses `fastagent add lark` instead. Setup (developer console):
+// 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.
+//
+// `fastagent add 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`
 //      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
-//      card scope ("Create and update card" — the live preview streams through a card). To answer bare
-//      messages in threads the Agent takes part in, and buffer other unsummoned group/thread context, also add the
-//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version. Add a
-//      message-read scope (e.g. `im:message:readonly`) too, so a thread's opening ask can carry the
-//      message it quotes; without it that quote degrades to a marker in the prompt.
-//   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
-//      .env; RECOMMENDED: set an Encrypt Key there and mirror it in FEISHU_ENCRYPT_KEY
-//   4. the event Request URL (https://your.host/feishu) is registered AUTOMATICALLY by
-//      `fastagent dev --tunnel` and `fastagent deploy … --run`; to set it by hand in the console,
-//      keep the server running while you save (the platform verifies the URL with a challenge)
-//   5. create a version and publish the app (a Feishu admin approves it), then add the bot to a chat
-// `fastagent add feishu` already did steps 1-3 for you (scan-to-create); this walkthrough is for a
-// hand-made app or for auditing what the scan configured.
-export default defineChannel({
-  // The env vars this channel needs. fastagent carries them to a deployed box and refuses to serve
-  // while one is unset — a bare process.env read gets neither guarantee. FEISHU_ENCRYPT_KEY is
-  // optional, so it is NOT declared here: an undeclared read stays undeclared on purpose.
-  secrets: ["FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_VERIFICATION_TOKEN"],
-  channel: (secrets) =>
-    feishuChannel({
-      appId: secrets.FEISHU_APP_ID,
-      appSecret: secrets.FEISHU_APP_SECRET,
-      verificationToken: secrets.FEISHU_VERIFICATION_TOKEN, // authenticates inbound events
-      encryptKey: process.env.FEISHU_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
-      // No session modes: a chat is one session and a thread is another, and where the answer goes follows
-      // from that (docs/design/participant-model.md).
-      // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
-      // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
-      // full details always go to the server log regardless.
-      onError: (failed) => `⚠️ ${failed.details}`,
-      // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
-      // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
-      // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
-      // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
-      // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
-      // Override to customise explicit routing, reusing the export:
-      //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
-      //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },
-    }),
-});
+//      card scope ("Create and update card" — the live preview streams through a card). So the Agent
+//      hears its group chats, also add `im:message.group_msg` (sensitive), `im:message:readonly` and
+//      `im:chat.members:read`; for webhook, `application:application:patch` lets fastagent set the
+//      Request URL. What each is for is in the channel guide; the channel warns about any it lacks.
+//   3. Events & Callbacks → subscribe to `im.message.receive_v1`. For webhook, copy the Verification
+//      Token into .env (RECOMMENDED: set an Encrypt Key there and mirror it in FEISHU_ENCRYPT_KEY).
+//   4. create a version and publish the app (a Feishu admin approves it), then add the bot to a chat
+
+// Your policy, the same whichever way the channel receives.
+const policy: Pick<FeishuChannelOptions, "onError" | "route"> = {
+  // A chat is one conversation and a thread is another, each with a session of its own, and where the
+  // answer goes follows from that (docs/design/participant-model.md).
+  // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
+  // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
+  // full details always go to the server log regardless.
+  onError: (failed) => `⚠️ ${failed.details}`,
+  // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
+  // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
+  // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
+  // Agent takes part and exactly ONE human does. Other group/thread discussion is read from the
+  // platform by that place's next answered turn; @other-only messages are discussion, not asks.
+  // Override to customise explicit routing, reusing the export:
+  //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { conversation: `user:${e.sender?.sender_id?.open_id}` },
+  //   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 }),
+    );