@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/dist/channels/feishu/feishu.js

@@ -0,0 +1,472 @@
+/**
+ * Canonical Feishu bot-channel engine: verify webhook → answer url_verification → dedup → route → persist → run
+ * the turn → stream a live card → ACK 200. 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.
+ */
+import { isAbsolute, join } from "node:path";
+import { log } from "../../log.js";
+import { readBodyCapped } from "../body.js";
+import { text } from "../respond.js";
+import { ensureStateHome } from "../state.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 { normalizeFeishuMessage } from "./normalize.js";
+import { createOwnedFeishuThreads } from "./owned-threads.js";
+import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderLabel, } from "./parse.js";
+import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, streamFeishuReply, } from "./preview.js";
+import { createSeenRing } from "./seen.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
+ *  rather than run again (a poison turn must not loop forever under a restart policy). Counted per turn
+ *  at dequeue, so a never-run turn queued behind a poison one keeps its full budget. */
+const MAX_TURN_ATTEMPTS = 3;
+/** Event body cap — events are small JSON; 1 MiB is generous and guards a public endpoint. */
+const MAX_EVENT_BYTES = 1 << 20;
+/** Queue feedback is immediate by default: it is the user's acknowledgement that this exact ask was
+ *  accepted behind another turn. The same reply-quoted card becomes the preview/final answer, so there
+ *  is no extra message or recall tombstone to avoid. Authors may still configure a delay explicitly. */
+const QUEUE_NOTICE_DELAY_MS = 0;
+const QUEUED_PLACEHOLDER = "⏳ Queued — I’ll start once the current task finishes.";
+const DEFERRED_PLACEHOLDER = "⏳ Delayed by a temporary system issue — I’ll retry automatically.";
+/** State files are an IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt file. */
+function isStoredFeishuTurn(t) {
+    const r = t;
+    const refs = (v) => Array.isArray(v) &&
+        v.every((x) => typeof x.msg === "string" && typeof x.key === "string");
+    return (typeof r?.id === "string" &&
+        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") &&
+        (r.replyInThread === undefined || typeof r.replyInThread === "boolean") &&
+        (r.parentId === undefined || typeof r.parentId === "string") &&
+        refs(r.images) &&
+        refs(r.files) &&
+        typeof r.attempts === "number");
+}
+/** Build the canonical Feishu channel. Lark calls the internal profile-bound builder below. */
+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, directMessageSession = "threaded", groupMessageSession = "threaded", 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)`);
+    }
+    if (!verificationToken) {
+        throw new Error(`${factoryName} requires a non-empty verificationToken (console → Events & Callbacks; an unset one accepts forged events)`);
+    }
+    if (directMessageSession !== "continuous" && directMessageSession !== "threaded") {
+        throw new Error(`${factoryName} directMessageSession must be "continuous" or "threaded"`);
+    }
+    if (groupMessageSession !== "continuous" && groupMessageSession !== "threaded") {
+        throw new Error(`${factoryName} groupMessageSession must be "continuous" or "threaded"`);
+    }
+    return ({ agent, stateRoot }) => {
+        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.
+        // Until it resolves (or if it fails), group summon stays off — fail-closed — while p2p works.
+        let botOpenId;
+        void api.botInfo().then((me) => {
+            botOpenId = me.openId;
+            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)}`));
+        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
+        // the operator's ONE state knob (FASTAGENT_STATE_DIR) can never be silently bypassed by glue.
+        if (!isAbsolute(stateRoot)) {
+            throw new Error(`${factoryName} requires an absolute ctx.stateRoot, got "${stateRoot}"`);
+        }
+        const stateHome = join(stateRoot, "channels", kind);
+        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);
+        const toStored = (r) => {
+            const { preview: _live, ...intent } = r; // drop the live-only field; TS enforces the rest is complete
+            return { ...intent, attempts: 0 };
+        };
+        const targetOf = (r) => ({
+            chatId: r.chatId,
+            replyTo: r.replyTo,
+            replyInThread: r.replyInThread,
+        });
+        const queueTargetOf = (r) => ({
+            chatId: r.chatId,
+            replyTo: r.queueReplyTo,
+            replyInThread: r.replyInThread,
+        });
+        // In-memory: the pending queue-preview mount per turn. Immediate by default; with an explicit delay,
+        // it mounts only if the turn is still waiting when the timer fires and is cancelled unsent otherwise.
+        // `done` settles either way, awaited at dequeue so the runner reliably receives the mounted preview
+        // instead of racing it and double-posting.
+        const notices = new Map();
+        const queue = createTurnQueue({
+            label,
+            // Queue feedback: when this session already has a turn running/queued, a silent wait reads as
+            // "the bot ignored me" once the current turn runs long — mount that turn's preview early with a
+            // queue status. It reply-quotes the exact source message (including p2p), then the runner mutates
+            // the SAME card/text into Thinking → final answer. Best-effort and post-ACK: a failed mount is a
+            // log line, never a failed event delivery; the turn later mounts its normal preview.
+            onQueuedBehind: (rec) => {
+                let fired = false;
+                let settle = () => { };
+                const done = new Promise((resolve) => {
+                    settle = resolve;
+                });
+                const mount = () => {
+                    fired = true;
+                    mountFeishuPreview(api, queueTargetOf(rec), QUEUED_PLACEHOLDER, label)
+                        .then((preview) => {
+                        rec.preview = preview;
+                    }, (e) => log.warn(`${label} queue preview failed (the turn still runs): ${String(e)}`))
+                        .finally(settle);
+                };
+                const timer = queueNoticeDelayMs > 0 ? setTimeout(mount, queueNoticeDelayMs) : undefined;
+                if (timer === undefined)
+                    mount();
+                notices.set(rec.id, {
+                    // Cancel is a no-op once mounting started — the send is in flight and `done` settles with it.
+                    cancel: () => {
+                        if (!fired) {
+                            if (timer !== undefined)
+                                clearTimeout(timer);
+                            settle();
+                        }
+                    },
+                    done,
+                });
+            },
+            run: async (rec) => {
+                // Runs at DEQUEUE time (serialized). The turn's queue wait is over: cancel a not-yet-mounted
+                // preview (fast turnover skips the Queued frame), then settle so rec.preview is final — in the
+                // common path this await is instant. BEFORE the ceiling check so drop/defer can take it over too.
+                const notice = notices.get(rec.id);
+                notice?.cancel();
+                await notice?.done;
+                notices.delete(rec.id);
+                // Count this execution against the durable record (poison-turn ceiling) before running it again.
+                const decision = store.startAttempt(rec.id, MAX_TURN_ATTEMPTS);
+                if (decision === "exceeded") {
+                    notifyDropped(rec);
+                    return;
+                }
+                if (decision === "defer") {
+                    // Couldn't record the attempt (disk failure): skip this cycle; a restart replays it. Do not
+                    // recall an existing queue preview (the client exposes a confusing tombstone): settle it in
+                    // place to an honest delayed status. The eventual replay mounts a fresh preview.
+                    if (rec.preview !== undefined) {
+                        void settleFeishuPreview(api, targetOf(rec), rec.preview, DEFERRED_PLACEHOLDER).catch((e) => log.warn(`${label} could not update a deferred turn's queue preview: ${String(e)}`));
+                    }
+                    return;
+                }
+                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, 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) {
+                    log.error(`${label} turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error)}`);
+                }
+                finally {
+                    // Fallback removal for the caught-error paths (a `failed` event or a transport throw): those
+                    // never reach the completed hook above. Idempotent — a second remove is a no-op. Only an
+                    // INTERRUPTED run (this finally never runs — a crash or SIGTERM deploy) leaves the record for
+                    // replay; a transport throw is dropped, not retried (safe retry needs an L2 delivery key).
+                    store.remove(rec.id);
+                }
+            },
+        });
+        // 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)); // failed write → webhook 500 → platform redelivery
+                seen.add(rec.id); // post-persist, best-effort protection from documented duplicate pushes
+            }
+            queue.accept(rec);
+        };
+        // Tell the asker when a turn is dropped at the execution ceiling: the chain's end needs a signal,
+        // not just an operator log line. Take over its queue preview in place if present (else send fresh) —
+        // leaving it pinned at "Queued" while sending a separate failure would double-post.
+        const notifyDropped = (r) => {
+            const body = "⚠️ I couldn’t complete an earlier request — please ask again.";
+            void settleFeishuPreview(api, targetOf(r), r.preview, body).catch((e) => log.warn(`${label} could not notify a dropped turn (session=${r.session}): ${String(e)}`));
+        };
+        // Re-enqueue turns a prior crash left mid-flight (ACKed but unfinished). Synchronous at construction:
+        // the queue runs them on the next tick. The execution ceiling is enforced per turn at dequeue.
+        const recovered = store.recover();
+        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) {
+            // 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);
+        }
+        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);
+            }
+            // ── 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);
+                    }
+                    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 {
+                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;
+            }
+            // 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);
+            }
+            // ── 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 });
+            }
+            // ── 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 });
+            }
+            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 persisted, skipping`);
+                return new Response(null, { status: 200 });
+            }
+            let r = decide(event);
+            const normalized = normalizeFeishuMessage(event);
+            if (!normalized)
+                return new Response(null, { status: 200 });
+            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);
+            // In an Agent-created thread, a bare user continuation still summons. Any explicit mention changes
+            // that intent: only defaultFeishuRoute's structural @THIS-bot match summons; @other-only discussion
+            // is buffered like unsummoned group context. A custom route remains fully authoritative.
+            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,
+                        }));
+                        // Pre-ACK persistence: a write failure rejects the webhook so the platform can redeliver.
+                        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); // post-persist: a redelivery cannot duplicate buffered context
+                        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})`);
+                    }
+                }
+                else {
+                    log.debug(`${label} not summoned — ignoring message ${m.message_id} (chat ${m.chat_id}, ${m.chat_type})`);
+                }
+                return new Response(null, { status: 200 });
+            }
+            {
+                const threadedP2p = directMessageSession === "threaded" && m.chat_type === "p2p";
+                const threadedGroup = groupMessageSession === "threaded" && m.chat_type === "group";
+                const threadedConversation = threadedP2p || threadedGroup;
+                // A top-level threaded message has no thread_id yet. Its tenant-unique message_id is therefore
+                // the only identity available both before and after the first reply creates the thread.
+                // Continuations carry that same value as root_id (field-verified on Feishu p2p; shared protocol
+                // shape for groups/Lark). Prefix with the channel kind to isolate Feishu/Lark while keeping pi's
+                // provider-facing session/cache key under 64 characters.
+                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`);
+                }
+                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;
+                // Groups always quote the summon. Threaded groups and p2p add reply_in_thread: on a top-level
+                // message that creates the thread, and on a continuation it keeps the answer inside it. Only
+                // quote when the resolved target is the source chat — a custom redirect cannot reuse a message
+                // id there. A continuous group still keeps replies inside an already-existing platform topic.
+                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;
+                // Queue feedback always identifies the exact ask, including continuous modes. In threaded mode
+                // it inherits replyInThread, so an ask queued inside a root cannot leak a status card to main chat.
+                const queueReplyTo = sameTarget ? m.message_id : undefined;
+                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) {
+                    // Persist ownership before ACK. The platform thread does not exist until the first reply lands,
+                    // but a failed reply has no continuation to misroute; pre-ACK ownership closes the opposite,
+                    // worse window (thread created, process dies, then its unmentioned continuation is forgotten).
+                    if (route === undefined &&
+                        threadedGroup &&
+                        m.thread_id === undefined &&
+                        sameTarget &&
+                        replyInThread === true) {
+                        ownedThreads.add(m.chat_id, m.message_id);
+                    }
+                    submit({
+                        id: m.message_id,
+                        seq: ++seqCounter,
+                        session,
+                        baseText,
+                        bufferKey,
+                        chatId,
+                        replyTo,
+                        queueReplyTo,
+                        replyInThread,
+                        // Inside a threaded session the root conversation history already contains the previous
+                        // turns. Reloading parent_id would duplicate that input (and its attachments). A top-level
+                        // quoted reply has no thread_id, starts a new root, and still hydrates its referent.
+                        parentId: threadedConversation && m.thread_id !== undefined ? undefined : m.parent_id,
+                        images,
+                        files,
+                    }, true);
+                }
+            }
+            // 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.
+            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 };
+    };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Run one turn (the IO half of canonical Feishu→Agent translation): assemble its inputs — resolve the reply
+ * referent (a summon that replies to an earlier message names it only by `parent_id`; the content is
+ * NOT in the event, so it is fetched here) and the attachments (vision images inline, files to disk) —
+ * and stream `agent.invoke` with the assembled prompt. Split from parse.ts (which is pure) because this
+ * half touches the Open API + disk; split from feishu.ts so the factory keeps only wiring and the
+ * per-turn lifecycle.
+ *
+ * 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 { 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 {
+    api: FeishuApi;
+    chatId: string;
+    filesDir: string;
+    label: 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). */
+export interface FeishuAttachmentInput {
+    msg: string;
+    key: string;
+    name?: string;
+}
+/** A turn's primary resources plus background resources folded from the context buffer. */
+export interface FeishuTurnAttachments {
+    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;
+    };
+}
+/** 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;
+}
+/**
+ * Run one turn: resolve its inputs, then stream agent.invoke. A primary-input failure surfaces as a
+ * `failed` event (never a silent drop). `onCompleted` (if given) fires on the `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.
+ */
+export declare function invokeFeishuTurn(agent: Agent, session: string, text: string, transport: FeishuTurnTransport, attachments: FeishuTurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;