@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/channels/feishu/feishu.js

@@ -1,27 +1,34 @@
 /**
- * Canonical Feishu bot-channel engine: verify webhook → answer url_verification → dedup → route → run
- * the turn → stream a live card → ACK 200. Feishu (open.feishu.cn) is the reference cloud. Lark
+ * Canonical Feishu bot-channel engine: verified webhook or official-SDK WebSocket → dedup → route →
+ * persist → enqueue → stream a live card. Feishu (open.feishu.cn) is the reference cloud. Lark
  * international binds this engine through an explicit compatibility profile because its control plane
  * trails Feishu; protocol reuse does not make Lark the design center.
  *
  * The channel kind remains the unit of route, env namespace, state home, logs, and onboarding, so one
- * workspace may mount both without sharing state. Webhook mode only; WebSocket long connection needs
- * the official SDK and a non-HTTP ingress seam. See docs/feishu.md.
+ * workspace may run both without sharing state. Webhook returns the existing route factory; WebSocket
+ * returns an explicit long-connection module. Both feed the same acceptance/turn engine. See docs/feishu.md.
  */
 import { isAbsolute, join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
+import { createSeenRing } from "../seen.js";
+import { createTaskTracker } from "../tasks.js";
 import { ensureStateHome } from "../state.js";
+import { dispatchStop, isStopText } from "../stop-command.js";
 import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "../turn-store.js";
 import { FEISHU_CLOUD } from "./cloud.js";
+import { collectFeishuBufferedAttachments, createFeishuContextBuffer, feishuBufferPlaceKey, feishuBufferText, } from "./context-buffer.js";
 import { decryptEvent, timingSafeEqualStr, verifySignature } from "./crypto.js";
 import { invokeFeishuTurn } from "./invoke-turn.js";
 import { createFeishuApi } from "./feishu-api.js";
-import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, parseContent, placeKey, } from "./parse.js";
+import { normalizeFeishuMessage } from "./normalize.js";
+import { createOwnedFeishuThreads } from "./owned-threads.js";
+import { FEISHU_GROUP_CONTEXT_SCOPE } from "./setup-mode.js";
+import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderLabel, } from "./parse.js";
 import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, streamFeishuReply, } from "./preview.js";
-import { createSeenRing } from "./seen.js";
+import { connectFeishuWs } from "./ws-ingress.js";
 // Canonical public surface; the Lark subpath aliases these types/functions at its compatibility boundary.
 export { defaultFeishuRoute, feishuEnvelope };
 /** Execution ceiling: a turn that has STARTED running this many times without finishing is dropped
@@ -45,6 +52,7 @@ function isStoredFeishuTurn(t) {
         typeof r.seq === "number" &&
         typeof r.session === "string" &&
         typeof r.baseText === "string" &&
+        (r.bufferKey === undefined || typeof r.bufferKey === "string") &&
         typeof r.chatId === "string" &&
         (r.replyTo === undefined || typeof r.replyTo === "string") &&
         (r.queueReplyTo === undefined || typeof r.queueReplyTo === "string") &&
@@ -54,24 +62,33 @@ function isStoredFeishuTurn(t) {
         refs(r.files) &&
         typeof r.attempts === "number");
 }
-/** Build the canonical Feishu channel. Lark calls the internal profile-bound builder below. */
+/** Build the canonical Feishu Request-URL webhook channel. */
 export function feishuChannel(opts) {
     return buildFeishuChannel(FEISHU_CLOUD, opts, feishuChannel.name);
 }
-/** Internal compatibility seam: protocol behavior comes from Feishu; the profile binds cloud edges. */
-export function buildFeishuChannel(profile, { appId, appSecret, verificationToken, encryptKey, route, onError, baseUrl = profile.apiBase, queueNoticeDelayMs = QUEUE_NOTICE_DELAY_MS, }, factoryName) {
-    const { kind, envPrefix } = profile;
-    const label = `[${kind}]`;
-    // All three are mandatory: without the app credentials no reply can be sent; without the verification
-    // token a plaintext-mode endpoint would accept forged events. Fail at construction (startup), not
-    // silently at the first event.
-    if (!appId || !appSecret) {
-        throw new Error(`${factoryName} requires appId + appSecret (developer console → Credentials & Basic Info)`);
+/** Build the canonical Feishu WebSocket long-connection channel. */
+export function feishuWebSocketChannel(opts) {
+    return buildFeishuWebSocketChannel(FEISHU_CLOUD, opts, feishuWebSocketChannel.name);
+}
+function validateSessionOptions(opts, factoryName) {
+    if (opts.directMessageSession !== undefined && !["continuous", "threaded"].includes(opts.directMessageSession)) {
+        throw new Error(`${factoryName} directMessageSession must be "continuous" or "threaded"`);
     }
-    if (!verificationToken) {
-        throw new Error(`${factoryName} requires a non-empty verificationToken (console → Events & Callbacks; an unset one accepts forged events)`);
+    if (opts.groupMessageSession !== undefined && !["continuous", "threaded"].includes(opts.groupMessageSession)) {
+        throw new Error(`${factoryName} groupMessageSession must be "continuous" or "threaded"`);
     }
-    return ({ agent, stateRoot }) => {
+}
+function createFeishuRuntimeFactory(profile, opts, factoryName) {
+    const { appId, appSecret, directMessageSession = "threaded", groupMessageSession = "threaded", route, onError, queueNoticeDelayMs = QUEUE_NOTICE_DELAY_MS, } = opts;
+    const baseUrl = opts.apiBaseUrl ?? opts.baseUrl ?? profile.apiBase;
+    const { kind } = profile;
+    const label = `[${kind}]`;
+    return ({ agent, stateRoot, control }) => {
+        // Credential checks run when serving starts, not while the authored module is imported: deployment
+        // can inspect the module shape before secrets exist, while serving still fails before ready.
+        if (!appId || !appSecret) {
+            throw new Error(`${factoryName} requires appId + appSecret (developer console → Credentials & Basic Info)`);
+        }
         const formatError = onError ?? defaultErrorMessage;
         const api = createFeishuApi({ kind, baseUrl, appId, appSecret });
         // One bot/v3/info at startup: the bot's open_id drives the default route's group @mention summon.
@@ -82,6 +99,17 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
             if (!botOpenId)
                 log.warn(`${label} bot/v3/info returned no open_id — group @mention summon stays off`);
         }, (e) => log.warn(`${label} bot/v3/info failed; group @mention summon stays off until restart: ${String(e)}`));
+        void api.listAppScopes().then((scopes) => {
+            const contextAware = scopes.some((scope) => scope.name === FEISHU_GROUP_CONTEXT_SCOPE &&
+                scope.grantStatus === 1 &&
+                (scope.type === undefined || scope.type === "tenant"));
+            if (contextAware) {
+                log.info(`${label} group visibility: context-aware — bare managed-thread replies + buffered discussion enabled`);
+            }
+            else {
+                log.warn(`${label} group visibility: @mentions only — ${FEISHU_GROUP_CONTEXT_SCOPE} is not granted; bare managed-thread replies + group context buffering are unavailable`);
+            }
+        }, (error) => log.warn(`${label} could not inspect group visibility: ${String(error)}`));
         const decide = route ?? ((event) => defaultFeishuRoute(event, { botOpenId }));
         // The channel-state convention: this channel's durable home is `<stateRoot>/channels/<kind>`
         // (engine state at the root, channel state under `channels/<kind>/`) — derived, not an option, so
@@ -90,13 +118,17 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
             throw new Error(`${factoryName} requires an absolute ctx.stateRoot, got "${stateRoot}"`);
         }
         const stateHome = join(stateRoot, "channels", kind);
-        ensureStateHome(stateHome); // create + self-ignore — downloaded files may carry chat content
+        ensureStateHome(stateHome); // create + self-ignore — buffers/files may carry chat content
+        const ownedThreads = createOwnedFeishuThreads(join(stateHome, "owned-threads.json"), label);
+        const buffer = createFeishuContextBuffer(join(stateHome, "buffers.json"), label);
         const store = createTurnStore(join(stateHome, "turns.json"), {
             label,
             isRecord: isStoredFeishuTurn,
             order: (a, b) => a.seq - b.seq,
         });
         const seen = createSeenRing(join(stateHome, "seen.json"), label);
+        // Side tasks (stop feedback) run off the ingress path but drain in turnsIdle.
+        const sideTasks = createTaskTracker();
         const toStored = (r) => {
             const { preview: _live, ...intent } = r; // drop the live-only field; TS enforces the rest is complete
             return { ...intent, attempts: 0 };
@@ -177,10 +209,24 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
                 }
                 const startedAt = Date.now();
                 log.info(`${label} turn start: turn=${rec.id} session=${rec.session} chat=${rec.chatId}`);
+                // Snapshot background discussion at dequeue. Commit only this snapshot on `completed`, so a
+                // message arriving while the turn runs remains buffered for the next answered turn.
+                // ponytail: independent threaded roots in one main chat dequeue concurrently and may both fold
+                // this snapshot before either commits it. That fan-out loses nothing; claiming by buffer key
+                // would instead couple otherwise-independent root sessions and require failure rollback.
+                const { text: recent, consumed } = buffer.peek(rec.bufferKey);
+                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${rec.baseText}` : rec.baseText;
+                const buffered = collectFeishuBufferedAttachments(consumed, {
+                    images: rec.images.map((ref) => ({ messageId: ref.msg, key: ref.key })),
+                    files: rec.files.map((ref) => ({ messageId: ref.msg, key: ref.key, name: ref.name })),
+                });
                 try {
-                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, rec.baseText, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label }, { images: rec.images, files: rec.files, parentId: rec.parentId }, 
-                    // On completed, drop the intent — the turn provably lives in the session from here on.
-                    () => store.remove(rec.id)), api, targetOf(rec), formatError, rec.preview, label);
+                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
+                        // Drop intent first: a crash between these writes may re-fold answered context later,
+                        // but can never replay this turn after its context was removed.
+                        store.remove(rec.id);
+                        buffer.commit(rec.bufferKey, consumed);
+                    }), api, targetOf(rec), formatError, rec.preview, label);
                     log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
                 }
                 catch (error) {
@@ -195,13 +241,13 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
                 }
             },
         });
-        // Accept a turn: persist its intent (pre-ACK; a failed write throws → webhook 500 → redeliver),
-        // record its id in the dedup ring (post-decision insurance, best-effort), enqueue it. Recovery
-        // re-enqueues a crash-surviving turn WITHOUT re-persisting.
+        // Accept a turn: persist its intent before the ACK, then record the platform delivery id and enqueue
+        // it. The ordering is deliberate: recording first could turn a failed intent write into silent loss
+        // when the platform redelivers. Recovery re-enqueues a crash survivor without re-persisting it.
         const submit = (rec, persist) => {
             if (persist) {
-                store.add(toStored(rec));
-                seen.add(rec.id);
+                store.add(toStored(rec)); // failed write → HTTP/WS 500 → platform re-push
+                seen.add(rec.id); // post-persist, best-effort protection from documented duplicate pushes
             }
             queue.accept(rec);
         };
@@ -218,142 +264,231 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
         if (recovered.length > 0)
             log.info(`${label} recovering ${recovered.length} unfinished turn(s) from a prior run`);
         let seqCounter = recovered.reduce((max, r) => Math.max(max, r.seq), 0);
-        for (const { attempts: _a, ...intent } of recovered)
-            submit({ ...intent, preview: undefined }, false);
-        const handler = async (req) => {
-            if (req.method !== "POST")
-                return text("POST only\n", 405);
-            const body = await readBodyCapped(req, MAX_EVENT_BYTES);
-            if ("tooLarge" in body)
-                return text("payload too large\n", 413);
-            let outer;
-            try {
-                outer = JSON.parse(body.text);
-                if (typeof outer !== "object" || outer === null)
-                    throw new Error("not an object");
-            }
-            catch {
-                return text("invalid json\n", 400);
+        for (const { attempts: _a, ...intent } of recovered) {
+            // A pre-buffer-version record has no trustworthy place identity. Give it an empty private bucket
+            // rather than risk consuming new main-chat context that arrived after this restart.
+            const bufferKey = intent.bufferKey ?? `${intent.chatId}:legacy-turn:${intent.id}`;
+            submit({ ...intent, bufferKey, preview: undefined }, false);
+        }
+        // Transport-neutral acceptance boundary. It performs only the fast pre-ACK work: normalize,
+        // route, persist intent/context, and enqueue. The minutes-long Agent turn remains fire-and-forget.
+        const acceptEvent = (event) => {
+            const m = event.message;
+            if (!m?.message_id || !m.chat_id)
+                return;
+            if (seen.has(m.message_id)) {
+                log.debug(`${label} duplicate push for message ${m.message_id} — already persisted, skipping`);
+                return;
             }
-            // ── Verification. Two modes, decided by the CONSOLE's Encrypt Key setting, mirrored here. ──────
-            let envelope;
-            if (typeof outer.encrypt === "string") {
-                if (!encryptKey) {
-                    log.error(`${label} received an ENCRYPTED event but no encryptKey is configured — set ${envPrefix}_ENCRYPT_KEY`);
-                    return text("encrypt key not configured\n", 400);
-                }
-                const sig = {
-                    timestamp: req.headers.get("x-lark-request-timestamp") ?? "",
-                    nonce: req.headers.get("x-lark-request-nonce") ?? "",
-                    signature: req.headers.get("x-lark-signature") ?? "",
-                };
-                // Ordinary encrypted events MUST verify the signature over the raw body before decryption.
-                // Feishu's documented exception is Request URL verification: its encrypted challenge carries
-                // no event-signature headers, so it is decrypted first and admitted ONLY when its type is
-                // url_verification; the common constant-time Token check below then authenticates it.
-                if (sig.signature && !verifySignature(encryptKey, sig, body.text)) {
-                    log.warn(`${label} rejected an event: invalid X-Lark-Signature (encrypt key mismatch, or a forgery)`);
-                    return text("invalid signature\n", 401);
-                }
-                try {
-                    envelope = JSON.parse(decryptEvent(encryptKey, outer.encrypt));
-                }
-                catch {
-                    if (!sig.signature) {
-                        log.warn(`${label} rejected an unsigned encrypted request that could not be decrypted`);
-                        return text("invalid encrypted payload\n", 401);
+            let r = decide(event);
+            const normalized = normalizeFeishuMessage(event);
+            if (!normalized)
+                return;
+            const bufferKey = feishuBufferPlaceKey(normalized.conversation);
+            const isHumanGroup = event.sender?.sender_type === "user" && m.chat_type === "group";
+            const managedThread = groupMessageSession === "threaded" &&
+                isHumanGroup &&
+                m.thread_id !== undefined &&
+                m.root_id !== undefined &&
+                ownedThreads.has(m.chat_id, m.root_id);
+            if (!r && route === undefined && managedThread && !normalized.content.hasMentions)
+                r = {};
+            if (!r) {
+                if (route === undefined && isHumanGroup) {
+                    const bodyText = feishuBufferText(normalized.content.text);
+                    if (bodyText) {
+                        const resources = normalized.content.resources;
+                        const images = resources
+                            .filter((resource) => resource.kind === "image")
+                            .map((resource) => ({ messageId: resource.messageId, key: resource.key }));
+                        const files = resources
+                            .filter((resource) => resource.kind === "file" || resource.kind === "audio" || resource.kind === "video")
+                            .map((resource) => ({
+                            messageId: resource.messageId,
+                            key: resource.key,
+                            name: resource.name,
+                        }));
+                        // A write failure escapes this boundary. HTTP turns it into a 500 response; the official WS
+                        // SDK turns it into a 500 ACK frame. Both transports therefore ask the platform to re-push.
+                        buffer.push(bufferKey, {
+                            sender: senderLabel(event.sender) ?? "someone",
+                            body: bodyText,
+                            messageId: m.message_id,
+                            replyTo: m.parent_id,
+                            files: files.length ? files : undefined,
+                            images: images.length ? images : undefined,
+                        });
+                        seen.add(m.message_id);
+                        log.debug(`${label} buffered unsummoned group message ${m.message_id} (place ${bufferKey})`);
+                    }
+                    else {
+                        log.debug(`${label} not summoned — ignoring empty message ${m.message_id} (chat ${m.chat_id})`);
                     }
-                    return text("invalid encrypted payload\n", 400);
                 }
-                if (!sig.signature && envelope.type !== "url_verification") {
-                    log.warn(`${label} rejected an encrypted event: missing X-Lark-Signature`);
-                    return text("invalid signature\n", 401);
+                else {
+                    log.debug(`${label} not summoned — ignoring message ${m.message_id} (chat ${m.chat_id}, ${m.chat_type})`);
                 }
+                return;
             }
-            else {
-                if (encryptKey) {
-                    // With an Encrypt Key configured, a PLAINTEXT event can only be a forgery (or a console
-                    // mismatch — surfaced in the log): accepting it would let a sender skip the signature.
-                    log.warn(`${label} rejected a plaintext event while encryptKey is set (console mismatch, or a forgery)`);
-                    return text("plaintext events not accepted\n", 401);
-                }
-                envelope = outer;
+            const threadedP2p = directMessageSession === "threaded" && m.chat_type === "p2p";
+            const threadedGroup = groupMessageSession === "threaded" && m.chat_type === "group";
+            const threadedConversation = threadedP2p || threadedGroup;
+            if (threadedConversation && m.thread_id !== undefined && m.root_id === undefined) {
+                log.warn(`${label} threaded ${m.chat_type} message ${m.message_id} has thread_id ${m.thread_id} but no root_id — session continuity cannot be guaranteed`);
             }
-            // The Verification Token authenticates plaintext mode and the platform-documented unsigned,
-            // encrypted URL challenge; on signed encrypted events it is defense in depth. V2 events carry it
-            // in header.token, while url_verification carries it at the top level. Fail closed when absent.
-            const token = (typeof envelope.token === "string" ? envelope.token : undefined) ??
-                (typeof envelope.header?.token === "string"
-                    ? envelope.header.token
-                    : undefined);
-            if (!token || !timingSafeEqualStr(token, verificationToken)) {
-                // Loud on purpose: the send side gets an opaque 401 and the platform just retries — this line is
-                // the operator's ONLY signal that LARK_VERIFICATION_TOKEN does not match the console.
-                log.warn(`${label} rejected an event: verification token mismatch (check ${envPrefix}_VERIFICATION_TOKEN against the console)`);
-                return text("invalid token\n", 401);
+            const defaultSession = threadedConversation
+                ? `${kind}:${m.thread_id === undefined ? m.message_id : (m.root_id ?? `missing-root:${m.thread_id}`)}`
+                : placeKey(m);
+            const session = r.session ?? defaultSession;
+            const chatId = r.chatId ?? m.chat_id;
+            const sameTarget = chatId === m.chat_id;
+            const replyTo = sameTarget && (m.chat_type === "group" || threadedP2p) ? m.message_id : undefined;
+            const replyInThread = replyTo !== undefined && (threadedConversation || m.thread_id !== undefined) ? true : undefined;
+            const queueReplyTo = sameTarget ? m.message_id : undefined;
+            // Explicit user stop: a control action, never a turn — it must not queue behind the run it
+            // stops. Mentions arrive as @name tokens; strip them before matching the bare word. Record the
+            // message id so a platform re-push doesn't double-abort or double-notify.
+            if (isStopText(normalized.content.text.replace(/@\S+/g, " "))) {
+                seen.add(m.message_id);
+                sideTasks.track(dispatchStop(control, session, label)
+                    .then((feedback) => api.sendText({ chatId, replyTo, replyInThread }, feedback).then(() => undefined))
+                    .catch((error) => log.warn(`${label} stop feedback failed: ${String(error)}`)));
+                return;
             }
-            // ── The console's URL-verification challenge (fires when the operator saves the Request URL). ──
-            if (envelope.type === "url_verification" && typeof envelope.challenge === "string") {
-                // The console fires this when the operator saves the Request URL; without this line a PASSING
-                // handshake is invisible and "did the challenge even arrive?" becomes guesswork.
-                log.info(`${label} answered the console's url_verification challenge`);
-                return Response.json({ challenge: envelope.challenge });
+            const resources = normalized.content.resources;
+            const images = resources
+                .filter((resource) => resource.kind === "image")
+                .map((resource) => ({ msg: resource.messageId, key: resource.key }));
+            const files = resources
+                .filter((resource) => resource.kind === "file" || resource.kind === "audio" || resource.kind === "video")
+                .map((resource) => ({ msg: resource.messageId, key: resource.key, name: resource.name }));
+            const baseText = r.text ?? cloudEnvelope(event, kind);
+            if (baseText.trim() === "" && images.length === 0 && files.length === 0)
+                return;
+            if (route === undefined && threadedGroup && m.thread_id === undefined && sameTarget && replyInThread === true) {
+                ownedThreads.add(m.chat_id, m.message_id);
             }
-            // ── Events. Only im.message.receive_v1 is consumed; everything else is ACKed and dropped
-            // (a non-2xx would just make the platform retry an event this channel will never act on). ──────
-            const header = envelope.header;
-            if (header?.event_type !== "im.message.receive_v1") {
-                log.debug(`${label} ignoring event type ${header?.event_type ?? "(none)"}`);
-                return new Response(null, { status: 200 });
+            submit({
+                id: m.message_id,
+                seq: ++seqCounter,
+                session,
+                baseText,
+                bufferKey,
+                chatId,
+                replyTo,
+                queueReplyTo,
+                replyInThread,
+                parentId: threadedConversation && m.thread_id !== undefined ? undefined : m.parent_id,
+                images,
+                files,
+            }, true);
+        };
+        return { acceptEvent, turnsIdle: () => Promise.all([queue.idle(), sideTasks.drain()]).then(() => undefined) };
+    };
+}
+function createFeishuWebhookRoutes(profile, opts, runtime) {
+    const { verificationToken, encryptKey } = opts;
+    const { kind, envPrefix } = profile;
+    const label = `[${kind}]`;
+    const handler = async (req) => {
+        if (req.method !== "POST")
+            return text("POST only\n", 405);
+        const body = await readBodyCapped(req, MAX_EVENT_BYTES);
+        if ("tooLarge" in body)
+            return text("payload too large\n", 413);
+        let outer;
+        try {
+            outer = JSON.parse(body.text);
+            if (typeof outer !== "object" || outer === null)
+                throw new Error("not an object");
+        }
+        catch {
+            return text("invalid json\n", 400);
+        }
+        let envelope;
+        if (typeof outer.encrypt === "string") {
+            if (!encryptKey) {
+                log.error(`${label} received an ENCRYPTED event but no encryptKey is configured — set ${envPrefix}_ENCRYPT_KEY`);
+                return text("encrypt key not configured\n", 400);
             }
-            const event = (envelope.event ?? {});
-            const m = event.message;
-            if (!m?.message_id || !m.chat_id)
-                return new Response(null, { status: 200 });
-            if (seen.has(m.message_id)) {
-                log.debug(`${label} duplicate push for message ${m.message_id} — already accepted, skipping`);
-                return new Response(null, { status: 200 });
+            const sig = {
+                timestamp: req.headers.get("x-lark-request-timestamp") ?? "",
+                nonce: req.headers.get("x-lark-request-nonce") ?? "",
+                signature: req.headers.get("x-lark-signature") ?? "",
+            };
+            if (sig.signature && !verifySignature(encryptKey, sig, body.text)) {
+                log.warn(`${label} rejected an event: invalid X-Lark-Signature (encrypt key mismatch, or a forgery)`);
+                return text("invalid signature\n", 401);
             }
-            const r = decide(event);
-            if (!r) {
-                log.debug(`${label} not summoned — ignoring message ${m.message_id} (chat ${m.chat_id}, ${m.chat_type})`);
-                return new Response(null, { status: 200 });
+            try {
+                envelope = JSON.parse(decryptEvent(encryptKey, outer.encrypt));
             }
-            {
-                const session = r.session ?? placeKey(m);
-                const chatId = r.chatId ?? m.chat_id;
-                // Reply to the summoning message in groups (threads the answer under the asker; stays inside a
-                // topic); a 1:1 p2p chat needs no reply-quote. Only when the RESOLVED target is the message's own
-                // chat: a route that redirects elsewhere must not quote a same-id message in the wrong place.
-                const sameTarget = chatId === m.chat_id;
-                const replyTo = m.chat_type !== "p2p" && sameTarget ? m.message_id : undefined;
-                // Queue feedback always identifies the exact ask, including p2p. Ordinary p2p answers remain
-                // unquoted unless the turn actually waited long enough for its queue preview to mount.
-                const queueReplyTo = sameTarget ? m.message_id : undefined;
-                const content = parseContent(m);
-                const baseText = r.text ?? cloudEnvelope(event, kind);
-                if (baseText.trim() !== "" || content.imageKeys.length > 0 || content.fileRefs.length > 0) {
-                    submit({
-                        id: m.message_id,
-                        seq: ++seqCounter,
-                        session,
-                        baseText,
-                        chatId,
-                        replyTo,
-                        queueReplyTo,
-                        replyInThread: replyTo !== undefined && m.thread_id !== undefined ? true : undefined,
-                        parentId: m.parent_id,
-                        images: content.imageKeys.map((key) => ({ msg: m.message_id, key })),
-                        files: content.fileRefs.map((f) => ({ msg: m.message_id, key: f.key, name: f.name })),
-                    }, true);
+            catch {
+                if (!sig.signature) {
+                    log.warn(`${label} rejected an unsigned encrypted request that could not be decrypted`);
+                    return text("invalid encrypted payload\n", 401);
                 }
+                return text("invalid encrypted payload\n", 400);
             }
-            // ACK immediately (the platform expects a fast 200; the turn may outlast it by minutes) —
-            // lifecycle goes to stderr; after the 200 those lines are the operator's only signal.
+            if (!sig.signature && envelope.type !== "url_verification") {
+                log.warn(`${label} rejected an encrypted event: missing X-Lark-Signature`);
+                return text("invalid signature\n", 401);
+            }
+        }
+        else {
+            if (encryptKey) {
+                log.warn(`${label} rejected a plaintext event while encryptKey is set (console mismatch, or a forgery)`);
+                return text("plaintext events not accepted\n", 401);
+            }
+            envelope = outer;
+        }
+        const token = (typeof envelope.token === "string" ? envelope.token : undefined) ??
+            (typeof envelope.header?.token === "string"
+                ? envelope.header.token
+                : undefined);
+        if (!token || !timingSafeEqualStr(token, verificationToken)) {
+            log.warn(`${label} rejected an event: verification token mismatch (check ${envPrefix}_VERIFICATION_TOKEN against the console)`);
+            return text("invalid token\n", 401);
+        }
+        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 });
+        }
+        const header = envelope.header;
+        if (header?.event_type !== "im.message.receive_v1") {
+            log.debug(`${label} ignoring event type ${header?.event_type ?? "(none)"}`);
             return new Response(null, { status: 200 });
-        };
-        // Test/observability seam: await the fire-and-forget turns this handler enqueues (see turn-queue).
-        handler.turnsIdle = () => queue.idle();
-        return { [`POST /${kind}`]: handler };
+        }
+        runtime.acceptEvent((envelope.event ?? {}));
+        return new Response(null, { status: 200 });
+    };
+    handler.turnsIdle = runtime.turnsIdle;
+    return { [`POST /${kind}`]: handler };
+}
+export function buildFeishuChannel(profile, opts, factoryName) {
+    validateSessionOptions(opts, factoryName);
+    const createRuntime = createFeishuRuntimeFactory(profile, opts, factoryName);
+    return (ctx) => {
+        if (!opts.verificationToken) {
+            throw new Error(`${factoryName} requires a non-empty verificationToken (console → Events & Callbacks)`);
+        }
+        return createFeishuWebhookRoutes(profile, opts, createRuntime(ctx));
+    };
+}
+export function buildFeishuWebSocketChannel(profile, opts, factoryName, deps = {}) {
+    validateSessionOptions(opts, factoryName);
+    const createRuntime = createFeishuRuntimeFactory(profile, opts, factoryName);
+    return {
+        name: `${profile.kind} websocket`,
+        connect(ctx, signal) {
+            const runtime = createRuntime(ctx);
+            return (deps.connectWs ?? connectFeishuWs)({
+                kind: profile.kind,
+                appId: opts.appId,
+                appSecret: opts.appSecret,
+                domain: opts.apiBaseUrl ?? opts.baseUrl ?? profile.apiBase,
+                onEvent: runtime.acceptEvent,
+            }, signal);
+        },
     };
 }

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

@@ -6,13 +6,14 @@
  * half touches the Open API + disk; split from feishu.ts so the factory keeps only wiring and the
  * per-turn lifecycle.
  *
- * Everything here is PRIMARY input — the summoning message's own attachments and the message the user
- * explicitly replied to — so any load failure THROWS and the caller sees a `failed` event: the agent
- * never runs on inputs the user pointed at but we failed to load. (The telegram channel's second,
- * degrade-per-attachment tier is its context BUFFER — background material; Feishu grows that tier only
- * with the buffer itself, which needs the sensitive all-group-messages scope.)
+ * Inputs have two tiers. PRIMARY is the summoning message plus the message it explicitly replied to;
+ * any load failure there aborts visibly so the Agent never runs without an input the user pointed at.
+ * BUFFERED resources come from earlier un-summoned thread/group discussion and degrade per attachment:
+ * one expired background file must not block the current ask or hide its still-readable siblings.
  */
-import { type Agent, type AgentEvent } from "../../agent.ts";
+import type { Agent, AgentEvent } from "../../agent.ts";
+import { type BusyRetry } from "../invoke-turn-kit.ts";
+import type { FeishuBufferedRef } from "./context-buffer.ts";
 import type { FeishuApi } from "./feishu-api.ts";
 /** Everything the transport needs to fetch a turn's attachments. */
 export interface FeishuTurnTransport {
@@ -23,37 +24,29 @@ export interface FeishuTurnTransport {
 }
 /** 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). */
-export interface FeishuAttachmentInput {
+interface FeishuAttachmentInput {
     msg: string;
     key: string;
     name?: string;
 }
-/** A turn's attachment inputs: the summoning message's own resources, plus the message it replied to
- *  (resolved here — content and resources both). */
+/** A turn's primary resources plus background resources folded from the context buffer. */
 export interface FeishuTurnAttachments {
-    images: FeishuAttachmentInput[];
-    files: FeishuAttachmentInput[];
-    /** The replied-to message's id, when the summon is a reply. */
-    parentId?: string;
-}
-/** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
- *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
- *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
- *  always an outside holder — wait for it like a queued turn, instead of erroring at the user. */
-export interface BusyRetry {
-    delayMs: number;
-    maxWaitMs: number;
+    primary: {
+        images: FeishuAttachmentInput[];
+        files: FeishuAttachmentInput[];
+        /** The replied-to message's id, when the summon is a reply. */
+        parentId?: string;
+    };
+    buffered: {
+        files: FeishuBufferedRef[];
+        images: FeishuBufferedRef[];
+        skipped: number;
+    };
 }
 /**
- * Run one turn: resolve its inputs, then stream agent.invoke. An input failure surfaces as a `failed`
- * event (never a silent drop). `onCompleted` (if given) fires on the turn's `completed` event — the
- * durable-commit point; the caller uses it to remove the turn intent (turn-store L1) at the earliest
- * moment the turn provably lives in the session.
- *
- * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn holds this session's
- * lease and OUR turn never started — replay-safe. Retry (bounded) instead of yielding it: the user sees
- * the "Thinking…" preview while waiting, and only an exhausted wait surfaces the busy failure. Only a
- * FIRST-event busy retries — inputs are already resolved, and a fail-fast reject is the only shape the
- * engine emits it in, so nothing that started is ever re-run.
+ * Run one turn: resolve its inputs, then stream agent.invoke with the shared busy-wait
+ * (invoke-turn-kit — `onCompleted` is the durable-commit point; see streamTurnWithBusyRetry). A
+ * primary-input failure surfaces as a `failed` event (never a silent drop).
  */
 export declare function invokeFeishuTurn(agent: Agent, session: string, text: string, transport: FeishuTurnTransport, attachments: FeishuTurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;
+export {};