@fastagent-sh/fastagent 0.12.0 → 0.13.0

package/dist/channels/feishu/feishu.js

@@ -0,0 +1,359 @@
+/**
+ * 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
+ * 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 { 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 { 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" &&
+        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, 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)`);
+    }
+    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 — downloaded files may carry chat content
+        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}`);
+                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);
+                    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 (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.
+        const submit = (rec, persist) => {
+            if (persist) {
+                store.add(toStored(rec));
+                seen.add(rec.id);
+            }
+            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)
+            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);
+            }
+            // ── 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 accepted, skipping`);
+                return new Response(null, { status: 200 });
+            }
+            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 });
+            }
+            {
+                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);
+                }
+            }
+            // 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,59 @@
+/**
+ * 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.
+ *
+ * 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.)
+ */
+import { type Agent, type AgentEvent } from "../../agent.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 attachment inputs: the summoning message's own resources, plus the message it replied to
+ *  (resolved here — content and resources both). */
+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;
+}
+/**
+ * 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.
+ */
+export declare function invokeFeishuTurn(agent: Agent, session: string, text: string, transport: FeishuTurnTransport, attachments: FeishuTurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;

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

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ *
+ * 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.)
+ */
+import { SESSION_BUSY_CODE } from "../../agent.js";
+import { log } from "../../log.js";
+import { parseContent } from "./parse.js";
+import { codePointPrefix } from "./text.js";
+/** Appended to the prompt (not the system prompt): the channel renders the reply in a card, and the
+ *  card's markdown element is the natural fit for LLM output — steer away from HTML/plain. */
+const MARKDOWN_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card.)";
+/**
+ * Resolve a turn's inputs (module header): fetch the reply referent's content, then load every image
+ * (vision) and file (disk). Throws on any failure — primary inputs, no silent drops.
+ */
+async function resolveTurnInputs(t, attachments) {
+    const images = [...attachments.images];
+    const files = [...attachments.files];
+    let referentBlock = "";
+    if (attachments.parentId !== undefined) {
+        const parent = await t.api.getMessage(attachments.parentId);
+        if (!parent)
+            throw new Error(`replied-to message ${attachments.parentId} is not readable`);
+        const parsed = parseContent({
+            message_type: parent.msg_type ?? "unknown",
+            content: parent.body?.content ?? "",
+            mentions: parent.mentions,
+        });
+        // The referent's own resources join the turn as primary inputs, carried by the PARENT message id.
+        for (const key of parsed.imageKeys)
+            images.push({ msg: attachments.parentId, key });
+        for (const ref of parsed.fileRefs)
+            files.push({ msg: attachments.parentId, key: ref.key, name: ref.name });
+        // getMessage's sender is `{ id, id_type, sender_type }` — a DIFFERENT shape from the event's
+        // sender (`{ sender_id: { open_id } }`), so the label is built here, not via parse.senderLabel.
+        const senderId = parent.sender?.id;
+        const from = senderId ? `user ${senderId}` : undefined;
+        referentBlock = `\n\n[replied-to message (msg ${attachments.parentId}${from ? `, from ${from}` : ""}): ${codePointPrefix(parsed.text, 560) || "(empty)"}]`;
+    }
+    const imageRefs = [];
+    for (const ref of images)
+        imageRefs.push(await t.api.fetchImage(ref.msg, ref.key));
+    const downloaded = [];
+    for (const ref of files)
+        downloaded.push(await t.api.fetchFile(ref.msg, ref.key, ref.name ?? ref.key, t.chatId, t.filesDir));
+    const manifest = downloaded.length
+        ? `\n\n[attached files — read them with your tools:\n${downloaded.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
+        : "";
+    return { images: imageRefs.length ? imageRefs : undefined, promptSuffix: `${referentBlock}${manifest}` };
+}
+// Each retry is a lease-check-level reject (tryAcquire runs before harness assembly) — waiting is nearly
+// free, and the loop exits within one delay of the holder finishing. The cap is sized to outlast a real
+// tool-using wake turn (minutes); a holder that runs longer still surfaces the busy error to the user.
+const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
+/**
+ * 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.
+ */
+export async function* invokeFeishuTurn(agent, session, text, transport, attachments, onCompleted, busyRetry = DEFAULT_BUSY_RETRY) {
+    let resolved;
+    try {
+        resolved = await resolveTurnInputs(transport, attachments);
+    }
+    catch (e) {
+        yield { type: "failed", details: `could not load attachment: ${String(e)}`, retryable: true };
+        return;
+    }
+    const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
+    const deadline = Date.now() + busyRetry.maxWaitMs;
+    for (;;) {
+        let retryBusy = false;
+        let first = true;
+        for await (const e of agent.invoke({ session }, prompt)) {
+            if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
+                retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
+                break;
+            }
+            first = false;
+            if (e.type === "completed")
+                onCompleted?.(); // the turn is durably in the session — commit point
+            yield e;
+        }
+        if (!retryBusy)
+            return;
+        log.info(`${transport.label} session ${session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
+        await new Promise((r) => setTimeout(r, busyRetry.delayMs));
+    }
+}

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

@@ -0,0 +1,125 @@
+/**
+ * Canonical Feishu protocol parsing — PURE: event field extraction, message-content decoding, prompt
+ * envelope, and summon/route policy. Lark compatibility events reuse these wire shapes. Feishu
+ * messages carry their payload as a JSON-ENCODED STRING in `content`, shaped by `message_type`
+ * (text / post / image / file / audio / media / …). {@link parseContent} is the single decoder: it
+ * yields the readable text (mention placeholders restored), the vision image keys, and the downloadable
+ * file refs — the envelope, the turn record, and the parent-message resolution all read through it.
+ */
+import type { FeishuCloudKind } from "./cloud.ts";
+/** One entry of a message's `mentions` array: the platform's parsed @-mention (the `key` is the
+ *  placeholder in the text content, e.g. `@_user_1`). */
+export interface FeishuMention {
+    key: string;
+    id?: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    name?: string;
+    [k: string]: unknown;
+}
+/** A received message (the `im.message.receive_v1` event's `message`, common subset; `[k]` keeps the
+ *  rest reachable without a types dependency). */
+export interface FeishuMessage {
+    message_id: string;
+    /** The replied-to message, when this message is a reply. Content is NOT included — the channel
+     *  fetches it via the API (the IO half, invoke-turn.ts). */
+    parent_id?: string;
+    root_id?: string;
+    chat_id: string;
+    /** Present in topic groups — reply into the same topic to stay threaded. */
+    thread_id?: string;
+    chat_type: string;
+    message_type: string;
+    /** JSON-encoded string, shaped by message_type — decode with {@link parseContent}. */
+    content: string;
+    mentions?: FeishuMention[];
+    [k: string]: unknown;
+}
+export interface FeishuSender {
+    sender_id?: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    /** "user" for humans; apps/bots have other values — the default route ignores those (anti-loop). */
+    sender_type?: string;
+    [k: string]: unknown;
+}
+/** The `im.message.receive_v1` event body (`event` of the v2.0 envelope). */
+export interface FeishuMessageEvent {
+    sender?: FeishuSender;
+    message?: FeishuMessage;
+    [k: string]: unknown;
+}
+/** What `route` returns: act with these (every field optional — omitted ones default from the message),
+ *  or null to ignore. */
+export interface FeishuRoute {
+    /** Conversation identity (default: `chat` or `chat:thread`). */
+    session?: string;
+    /** Reply target chat (default: the message's chat). */
+    chatId?: string;
+    /** Base prompt (default: {@link feishuEnvelope}); the channel still appends attachments. */
+    text?: string;
+}
+/** A downloadable attachment reference: the resource key inside its carrying message (the resource API
+ *  addresses a file by message_id + key). */
+export interface FeishuAttachmentRef {
+    key: string;
+    name?: string;
+}
+/** A message's decoded payload — see the module header. */
+export interface ParsedFeishuContent {
+    /** Readable text: the text/post body with mention placeholders restored to `@Name`; marker lines
+     *  (`[image]`, `[file: …]`) for non-text payloads, so a media-only message is never blank. */
+    text: string;
+    /** Vision images: `image_key`s from an image message or a post's inline images. */
+    imageKeys: string[];
+    /** Files to download to disk (file / audio / media). */
+    fileRefs: FeishuAttachmentRef[];
+}
+/**
+ * Decode a message's `content` by its `message_type` — the single decoder (module header). Unknown or
+ * malformed content degrades to a visible marker (`[sticker message]`), never a throw: the payload is
+ * external input, and a message the agent cannot read should still say WHAT it couldn't read.
+ */
+export declare function parseContent(m: Pick<FeishuMessage, "message_type" | "content" | "mentions">): ParsedFeishuContent;
+/** A stable sender label for attribution. The receive event carries only ids (a display name needs a
+ *  contacts-API scope), so the label is the open_id — stable across turns, which is what a shared
+ *  multi-user session needs to tell participants apart. */
+export declare function senderLabel(sender: FeishuSender | undefined): string | undefined;
+/** The place a message lives (chat, or chat:topic in a topic group) — the default session key. */
+export declare function placeKey(m: Pick<FeishuMessage, "chat_id" | "thread_id">): string;
+/**
+ * The default base prompt: a context envelope (chat/thread/sender + a group note + a reply marker),
+ * then the message's decoded body. The sender is named on every message and a group chat is flagged —
+ * in a shared multi-user session that is how the model tells participants apart and knows it is not a
+ * 1:1. A reply carries only `[in reply to msg …]` here: the referent's CONTENT is not in the event, so
+ * the channel fetches and appends it in the IO half (invoke-turn.ts), keeping this layer pure. Exported
+ * so a custom Feishu `route` can reuse it, e.g. `text: `${feishuEnvelope(event)}\n\n[extra]``. The
+ * internal compatibility seam binds the same shape to `[lark: …]`; each kind's send tool reads the
+ * chat id from its own branded line.
+ */
+export declare function feishuEnvelope(event: FeishuMessageEvent): string;
+/** Internal compatibility seam: bind the canonical envelope shape to one cloud's branded tag. */
+export declare function cloudEnvelope(event: FeishuMessageEvent, tag: FeishuCloudKind): string;
+/**
+ * Whether the message @mentions the bot — read from the `mentions` array the platform already parsed
+ * (never a regex over the text: a pasted `@bot` in a code block is not a mention entry), matched on the
+ * bot's open_id (stable identity; names are mutable). No id → fail closed (false): answering "is this
+ * mention me?" with "I don't know who I am, so yes" would mis-summon in every multi-bot group.
+ */
+export declare function mentionsBot(m: Pick<FeishuMessage, "mentions">, botOpenId: string | undefined): boolean;
+/**
+ * The default routing policy (used when `route` is omitted; exported so a custom route can reuse it):
+ * answer humans only (a non-`user` sender is another bot/app — two bots answering each other loop
+ * forever), p2p chats always, a group only on an @mention of THIS bot (matched by open_id, which
+ * feishuChannel resolves via bot/v3/info). NOTE the platform side of the same coin: with the default
+ * `im:message.group_at_msg` scope, un-mentioned group messages are never even delivered — receiving
+ * everything needs the sensitive `im:message.group_msg` scope. Returns `{}` (act; the channel fills
+ * session/target/prompt from the message) or `null` (ignore).
+ */
+export declare function defaultFeishuRoute(event: FeishuMessageEvent, options?: {
+    botOpenId?: string;
+}): FeishuRoute | null;