@fastagent-sh/fastagent 0.12.0 → 0.13.0

package/dist/channels/feishu/parse.js

@@ -0,0 +1,175 @@
+/** Restore the platform's mention placeholders (`@_user_1`) in a text body to readable `@Name`. */
+function restoreMentions(text, mentions) {
+    let out = text;
+    for (const m of mentions ?? []) {
+        if (!m.key)
+            continue;
+        out = out.split(m.key).join(`@${m.name ?? "user"}`);
+    }
+    return out;
+}
+/**
+ * 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 function parseContent(m) {
+    let c;
+    try {
+        c = JSON.parse(m.content);
+        if (typeof c !== "object" || c === null)
+            throw new Error("not an object");
+    }
+    catch {
+        return { text: `[unreadable ${m.message_type} message]`, imageKeys: [], fileRefs: [] };
+    }
+    const imageKeys = [];
+    const fileRefs = [];
+    const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
+    switch (m.message_type) {
+        case "text":
+            return { text: restoreMentions(str(c.text) ?? "", m.mentions), imageKeys, fileRefs };
+        case "post": {
+            // A post is paragraphs of typed nodes; renders as text lines with inline markers. Mentions in a
+            // post are `at` NODES (user_name inline), not placeholders — no restore pass needed.
+            const lines = [];
+            const title = str(c.title);
+            if (title)
+                lines.push(title);
+            const paragraphs = Array.isArray(c.content) ? c.content : [];
+            for (const para of paragraphs) {
+                if (!Array.isArray(para))
+                    continue;
+                const parts = [];
+                for (const node of para) {
+                    if (typeof node !== "object" || node === null)
+                        continue;
+                    if (node.tag === "at")
+                        parts.push(`@${str(node.user_name) ?? str(node.user_id) ?? "user"}`);
+                    else if (node.tag === "a")
+                        parts.push(node.href ? `${str(node.text) ?? node.href} (${node.href})` : (str(node.text) ?? ""));
+                    else if (node.tag === "img") {
+                        if (str(node.image_key))
+                            imageKeys.push(node.image_key);
+                        parts.push("[image]");
+                    }
+                    else if (node.tag === "media") {
+                        if (str(node.file_key))
+                            fileRefs.push({ key: node.file_key, name: str(node.file_name) });
+                        parts.push("[video]");
+                    }
+                    else if (node.tag === "code_block")
+                        parts.push(`\n\`\`\`${str(node.language)?.toLowerCase() ?? ""}\n${str(node.text) ?? ""}\n\`\`\`\n`);
+                    else if (str(node.text))
+                        parts.push(node.text);
+                }
+                const line = parts.join("").trim();
+                if (line)
+                    lines.push(line);
+            }
+            return { text: lines.join("\n"), imageKeys, fileRefs };
+        }
+        case "image": {
+            if (str(c.image_key))
+                imageKeys.push(c.image_key);
+            return { text: "[image]", imageKeys, fileRefs };
+        }
+        case "file": {
+            const name = str(c.file_name);
+            if (str(c.file_key))
+                fileRefs.push({ key: c.file_key, name });
+            return { text: `[file: ${name ?? "file"}]`, imageKeys, fileRefs };
+        }
+        case "audio": {
+            if (str(c.file_key))
+                fileRefs.push({ key: c.file_key, name: "voice-message" });
+            return { text: "[voice message]", imageKeys, fileRefs };
+        }
+        case "media": {
+            const name = str(c.file_name);
+            if (str(c.file_key))
+                fileRefs.push({ key: c.file_key, name });
+            return { text: `[video: ${name ?? "video"}]`, imageKeys, fileRefs };
+        }
+        case "location": {
+            const name = str(c.name);
+            return {
+                text: `[location: ${name ? `${name} — ` : ""}${str(c.latitude) ?? "?"},${str(c.longitude) ?? "?"}]`,
+                imageKeys,
+                fileRefs,
+            };
+        }
+        default:
+            // sticker / share_chat / share_user / system / … — name the type so the agent can say what it got.
+            return { text: `[${m.message_type} message]`, imageKeys, fileRefs };
+    }
+}
+/** 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 function senderLabel(sender) {
+    const id = sender?.sender_id?.open_id ?? sender?.sender_id?.user_id ?? sender?.sender_id?.union_id;
+    return id ? `user ${id}` : undefined;
+}
+/** The place a message lives (chat, or chat:topic in a topic group) — the default session key. */
+export function placeKey(m) {
+    return m.thread_id ? `${m.chat_id}:${m.thread_id}` : m.chat_id;
+}
+/**
+ * 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 function feishuEnvelope(event) {
+    return cloudEnvelope(event, "feishu");
+}
+/** Internal compatibility seam: bind the canonical envelope shape to one cloud's branded tag. */
+export function cloudEnvelope(event, tag) {
+    const m = event.message;
+    if (!m)
+        return "";
+    const meta = [
+        `chat ${m.chat_id} (${m.chat_type})`,
+        m.thread_id ? `topic ${m.thread_id}` : undefined,
+        senderLabel(event.sender) ? `from ${senderLabel(event.sender)}` : undefined,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    const scope = m.chat_type === "group" ? "\n[group chat — multiple people; each message is prefixed with its sender]" : "";
+    const replyTo = m.parent_id ? `\n[in reply to msg ${m.parent_id}]` : "";
+    return `[${tag}: ${meta}]${scope}${replyTo}\n${parseContent(m).text}`;
+}
+/**
+ * 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 function mentionsBot(m, botOpenId) {
+    if (!botOpenId)
+        return false;
+    return (m.mentions ?? []).some((x) => x.id?.open_id === botOpenId);
+}
+/**
+ * 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 function defaultFeishuRoute(event, options) {
+    const m = event.message;
+    if (!m)
+        return null;
+    if (event.sender?.sender_type !== "user")
+        return null;
+    const summoned = m.chat_type === "p2p" || mentionsBot(m, options?.botOpenId);
+    return summoned ? {} : null;
+}

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

@@ -0,0 +1,36 @@
+import type { AgentEvent } from "../../agent.ts";
+import { type FeishuApi, type FeishuTarget } from "./feishu-api.ts";
+/** A terminal failure, as the channel hands it to `onError`. */
+export interface FeishuFailure {
+    details: string;
+    retryable: boolean;
+}
+/** The customer-facing default: neutral, no leaked internals; differentiate only on whether to retry. */
+export declare function defaultErrorMessage(failed: FeishuFailure): string;
+/** A visible preview mounted into the chat. Exported only for the channel wiring: a queued turn mounts
+ * one before execution, then hands the exact entity/message to {@link streamFeishuReply} for takeover. */
+export type MountedFeishuPreview = {
+    kind: "card";
+    cardId: string;
+    messageId: string;
+} | {
+    kind: "text";
+    messageId: string;
+};
+/**
+ * Mount one preview message: preferably a streaming card entity, with a static text message as the
+ * visible fallback. Queue feedback and ordinary turn startup share this constructor so a queued card
+ * has exactly the same shape the stream pump expects to take over later.
+ */
+export declare function mountFeishuPreview(api: FeishuApi, target: FeishuTarget, initial: string, label?: string): Promise<MountedFeishuPreview>;
+/** Settle an already-mounted queue preview without starting an Agent stream (the poison/defer paths).
+ * Card and text tiers both change in place; only a missing/failed preview sends a fresh message. */
+export declare function settleFeishuPreview(api: FeishuApi, target: FeishuTarget, preview: MountedFeishuPreview | undefined, text: string): Promise<void>;
+/**
+ * Consume one turn's event stream into a Feishu-compatible chat, live (see the module header for the preview
+ * model). Preview updates are best-effort (logged once if they fail); the final write is authoritative
+ * and surfaces a real failure (bad credentials, etc.). `initialPreview`, when present, is the queued
+ * turn's already-mounted card/text message: the pump and terminal write mutate that same message rather
+ * than recalling it and posting another reply.
+ */
+export declare function streamFeishuReply(events: AsyncIterable<AgentEvent>, api: FeishuApi, target: FeishuTarget, formatError: (failed: FeishuFailure) => string | undefined, initialPreview?: MountedFeishuPreview, label?: string): Promise<void>;

package/dist/channels/feishu/preview.js

@@ -0,0 +1,387 @@
+/**
+ * Canonical Feishu live-preview rendering (also reused by Lark compatibility). The preview is ONE
+ * streaming CARD (create entity → mount it with a reply/send → stream full-text snapshots at its
+ * markdown element with a strictly increasing `sequence`; the client renders the typewriter effect);
+ * on completion the same card is settled in place with the final answer (streaming off). Streaming
+ * updates ride the cardkit quota (50 QPS per app, 10 QPS per card entity, no edit ceiling) — NOT the
+ * 5 QPS per-chat message quota or
+ * the 20-edit cap on text messages, which is why the preview is a card and not an edited text message.
+ *
+ * A queued turn mounts this same card early with its queue status, reply-quoted to that turn's source
+ * message; when execution starts the preview takes the entity over in place. This mirrors Telegram's
+ * one-message lifecycle without trying to change a text message into a card (which the platform does
+ * not support), and keeps multiple queued asks attributable even if their card mounts race visually.
+ *
+ * Fallback tier (fail visibly, degrade per turn): if the card cannot be created or mounted, the turn
+ * runs with a TEXT placeholder and NO live updates (text edits are capped at 20 per message, so the
+ * text tier spends them only on terminal writes); if the platform closes streaming mid-turn (idle
+ * timeout), the preview freezes and the settle still lands. The final write is authoritative either
+ * way, mirroring the telegram preview's terminal-write matrix (completed/failed/abnormal ×
+ * settle/delete+send/suppress).
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+import { log } from "../../log.js";
+import { ANSWER_ELEMENT_ID, CARD_MARKDOWN_MAX_BYTES, cardEntityContent, finalCardJson, streamingCardJson, } from "./card.js";
+import { chunkFeishuText, isCardStreamingClosed } from "./feishu-api.js";
+import { truncateCodePointPrefix, truncateCodePointSuffix, truncateUtf8 } from "./text.js";
+/** The customer-facing default: neutral, no leaked internals; differentiate only on whether to retry. */
+export function defaultErrorMessage(failed) {
+    return failed.retryable ? "⚠️ Temporary problem — please try again." : "⚠️ Sorry, something went wrong.";
+}
+/** How often (ms) to push a live-preview snapshot; tool events still flush on the next loop. Cardkit
+ *  allows 10 QPS per card entity (50 per app), but one snapshot a second reads smoothly (the client
+ *  animates between snapshots).
+ *  Doubles as the answer-preview aging window (see answerView). */
+const STREAM_THROTTLE_MS = 1000;
+/** Max length of a tool's arg preview in the live view. */
+const TOOL_ARG_MAX = 48;
+/** How much of the (growing) reasoning to peek at in the live view — the most recent tail. */
+const THINKING_PREVIEW = 280;
+/** The placeholder shown before any reasoning/tool/text arrives. */
+const THINKING_PLACEHOLDER = "💭 Thinking…";
+/** One-line, truncated: collapse whitespace so a multi-line command/arg stays on one line. */
+function clip(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    return truncateCodePointPrefix(one, TOOL_ARG_MAX);
+}
+/**
+ * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
+ * rather than just `🔧 read`. Generic (the channel knows no tool schemas): show the salient value — the
+ * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
+ */
+function summarizeArgs(args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return clip(String(args));
+    const values = Object.values(args);
+    const primary = values.find((v) => typeof v === "string" || typeof v === "number");
+    if (primary !== undefined)
+        return clip(String(primary));
+    return values.length > 0 ? clip(JSON.stringify(args)) : "";
+}
+/** Cap a live view to the card budget, PREFIX-STABLE: the streaming client animates only when the old
+ *  text is a prefix of the new, so an over-budget view freezes at its head rather than sliding a tail
+ *  window (which would redraw the whole card every frame). The full answer still lands at settle. */
+function capBytes(s, maxBytes) {
+    return truncateUtf8(s, maxBytes);
+}
+/**
+ * The terminal-write POLICY: resolve the preview into `text`. One card → settle it in place (final
+ * markdown, streaming off); an over-budget answer settles the card with its first chunk and sends the
+ * rest as follow-up messages. A failed settle falls back to delete + fresh send, so no "Thinking…" card
+ * is left pinned above the answer. Text tier → ONE edit into the final text (or delete + fresh sends
+ * when it doesn't fit). No preview → fresh send. EMPTY text = "say nothing" → just delete the preview.
+ */
+async function finalize(api, target, preview, text, seq) {
+    if (text.trim() === "") {
+        if (preview.kind !== "none")
+            await api.deleteMessage(preview.messageId).catch(() => { });
+        return;
+    }
+    if (preview.kind === "card") {
+        const [head, ...rest] = chunkFeishuText(text, CARD_MARKDOWN_MAX_BYTES);
+        let settled = false;
+        try {
+            await api.updateCard(preview.cardId, finalCardJson(head ?? ""), seq());
+            settled = true;
+        }
+        catch {
+            // Settle failed (card expired / rejected) — fall through to delete + fresh send below.
+        }
+        if (settled) {
+            // Topic continuations must keep reply_in_thread; ordinary group continuations intentionally avoid
+            // repeating the quote on every chunk. sendText owns the same distinction for its own chunking.
+            // A continuation failure propagates: the card is already authoritative, so deleting it and sending
+            // the full answer again would deterministically duplicate every continuation that already landed.
+            const continuationTarget = target.replyInThread ? target : { chatId: target.chatId };
+            for (const chunk of rest)
+                await api.sendText(continuationTarget, chunk);
+            return;
+        }
+    }
+    if (preview.kind === "text") {
+        if (chunkFeishuText(text).length === 1) {
+            try {
+                await api.editTextMessage(preview.messageId, text);
+                return;
+            }
+            catch {
+                // Edit failed (edit window / count / policy) — fall through to delete + fresh send below.
+            }
+        }
+    }
+    if (preview.kind !== "none")
+        await api.deleteMessage(preview.messageId).catch(() => { });
+    await api.sendText(target, text);
+}
+/**
+ * Mount one preview message: preferably a streaming card entity, with a static text message as the
+ * visible fallback. Queue feedback and ordinary turn startup share this constructor so a queued card
+ * has exactly the same shape the stream pump expects to take over later.
+ */
+export async function mountFeishuPreview(api, target, initial, label = "[feishu]") {
+    try {
+        const cardId = await api.createCard(streamingCardJson(initial));
+        const content = cardEntityContent(cardId);
+        const mountOnce = () => target.replyTo !== undefined
+            ? api.replyMessage(target.replyTo, "interactive", content, { replyInThread: target.replyInThread })
+            : api.sendMessage(target.chatId, "interactive", content);
+        let messageId;
+        // Field-observed: the mount can reject a JUST-minted card id (code 230099 / "cardid is invalid")
+        // — the entity is not yet visible to the IM side (eventual consistency between cardkit and IM).
+        // That specific rejection gets a short backoff and another try before degrading; anything else
+        // degrades immediately.
+        for (let attempt = 1;; attempt++) {
+            try {
+                messageId = await mountOnce();
+                break;
+            }
+            catch (e) {
+                if (attempt >= 3 || !/230099|11310|cardid is invalid/i.test(String(e)))
+                    throw e;
+                log.warn(`${label} mount rejected the fresh card (card=${cardId}, attempt ${attempt}) — retrying: ${String(e)}`);
+                await sleep(attempt * 400);
+            }
+        }
+        if (messageId === undefined)
+            throw new Error("interactive send returned ok without a message_id");
+        return { kind: "card", cardId, messageId };
+    }
+    catch (e) {
+        // Card tier failed — degrade to a text placeholder with NO live updates (the text tier's 20-edit
+        // cap is spent on terminal writes only). Visible: the operator learns why the preview is static.
+        log.warn(`${label} streaming card unavailable — live preview degrades to a static placeholder: ${String(e)}`);
+        const messageId = target.replyTo !== undefined
+            ? await api.replyMessage(target.replyTo, "text", JSON.stringify({ text: initial }), {
+                replyInThread: target.replyInThread,
+            })
+            : await api.sendMessage(target.chatId, "text", JSON.stringify({ text: initial }));
+        if (messageId === undefined)
+            throw new Error("text preview send returned ok without a message_id");
+        return { kind: "text", messageId };
+    }
+}
+/** Settle an already-mounted queue preview without starting an Agent stream (the poison/defer paths).
+ * Card and text tiers both change in place; only a missing/failed preview sends a fresh message. */
+export async function settleFeishuPreview(api, target, preview, text) {
+    let sequence = 0;
+    await finalize(api, target, preview ?? { kind: "none" }, text, () => ++sequence);
+}
+/**
+ * Consume one turn's event stream into a Feishu-compatible chat, live (see the module header for the preview
+ * model). Preview updates are best-effort (logged once if they fail); the final write is authoritative
+ * and surfaces a real failure (bad credentials, etc.). `initialPreview`, when present, is the queued
+ * turn's already-mounted card/text message: the pump and terminal write mutate that same message rather
+ * than recalling it and posting another reply.
+ */
+export async function streamFeishuReply(events, api, target, formatError, initialPreview, label = "[feishu]") {
+    const tools = [];
+    const toolIndexById = new Map();
+    let thinking = "";
+    let answer = "";
+    let answerPreviewSince;
+    const mark = { running: "…", ok: "✓", error: "✗" };
+    const toolView = () => tools.map((t) => `🔧 ${t.label} ${mark[t.status]}`).join("\n");
+    // Reasoning is process, not the answer: shown (capped to its tail) in the live preview only, never
+    // in the settled final card (which is `answer` alone).
+    const thinkingView = () => {
+        const t = thinking.replace(/\s+/g, " ").trim();
+        if (t === "")
+            return "";
+        return `💭 ${truncateCodePointSuffix(t, THINKING_PREVIEW)}`;
+    };
+    // The answer is hidden until its first delta has aged one STREAM_THROTTLE_MS: the pump's leading-edge
+    // flush would otherwise turn the very first content delta (often a lone character) into its own frame
+    // — the short-reply flicker. Aging is anchored at delta ARRIVAL (set in the event loop, not here) so
+    // an in-flight update can't skew the clock; a turn completing within the window settles directly.
+    const answerView = () => {
+        if (answer.trim() === "" || answerPreviewSince === undefined)
+            return "";
+        return Date.now() - answerPreviewSince >= STREAM_THROTTLE_MS ? answer : "";
+    };
+    const view = () => {
+        const v = [thinkingView(), toolView(), answerView()]
+            .filter((s) => s.trim() !== "")
+            .join("\n\n")
+            .trim();
+        return capBytes(v === "" ? THINKING_PLACEHOLDER : v, CARD_MARKDOWN_MAX_BYTES);
+    };
+    // The live preview is ONE message: either the queue card/text handed in by the wiring, or a preview
+    // mounted lazily on this turn's first flush. `sequence` must increase strictly per card — the single-
+    // writer pump guarantees it by construction. A queue card has had no updates yet, so sequence starts
+    // at zero in both paths.
+    let preview = initialPreview ?? { kind: "none" };
+    let setupAttempted = initialPreview !== undefined;
+    let sequence = 0;
+    const nextSeq = () => ++sequence;
+    let streamDead = false; // the platform closed streaming (idle timeout) — freeze the live view
+    let finalized = false; // a terminal write (completed/failed) ran — the finally skips its orphan cleanup
+    let lastSent = "";
+    const flushPreview = async () => {
+        const text = view();
+        if (!setupAttempted) {
+            setupAttempted = true;
+            preview = await mountFeishuPreview(api, target, text, label);
+            lastSent = text;
+            return;
+        }
+        if (preview.kind !== "card" || streamDead)
+            return; // text tier / dead stream: frozen until the terminal write
+        if (text === lastSent)
+            return; // skip an unchanged snapshot
+        lastSent = text;
+        try {
+            await api.updateCardElement(preview.cardId, ANSWER_ELEMENT_ID, text, nextSeq());
+        }
+        catch (e) {
+            if (isCardStreamingClosed(e)) {
+                // The platform closed streaming (idle timeout). Freeze the live view; the settle write replaces
+                // the whole entity (streaming off) and still lands.
+                streamDead = true;
+                log.warn(`${label} card streaming closed mid-turn — preview frozen; the final answer still lands`);
+                return;
+            }
+            throw e;
+        }
+    };
+    // ── Live-preview pump: a SINGLE serialized writer. ──────────────────────────────────────────
+    // Events mutate state (thinking / tools / answer) and mark the preview dirty; the pump pushes the
+    // LATEST view() with at most ONE update in flight, paced by a throttle. One-in-flight also guarantees
+    // the card's strictly-increasing `sequence` lands in order (no concurrent frames).
+    let dirty = false;
+    let pumping = false;
+    let stopped = false;
+    let previewErrLogged = false;
+    let pumpDone;
+    let wakeThrottle; // set while the pump is mid-throttle; finish() cuts it short
+    const runPump = async () => {
+        pumping = true;
+        try {
+            while (dirty && !stopped) {
+                dirty = false;
+                try {
+                    await flushPreview();
+                }
+                catch (e) {
+                    // Best-effort preview (the final write is authoritative), but a failing update must be visible —
+                    // log once per turn so a never-rendering preview is diagnosable, not silent.
+                    if (!previewErrLogged) {
+                        previewErrLogged = true;
+                        log.warn(`${label} live preview failed (final reply still sends): ${String(e)}`);
+                    }
+                }
+                if (dirty && !stopped) {
+                    // Pace + coalesce a burst into one snapshot. Interruptible: finish() cuts this short so the
+                    // final write is not delayed by up to STREAM_THROTTLE_MS after the turn completes.
+                    await new Promise((resolve) => {
+                        const t = setTimeout(resolve, STREAM_THROTTLE_MS);
+                        wakeThrottle = () => {
+                            clearTimeout(t);
+                            resolve();
+                        };
+                    });
+                    wakeThrottle = undefined;
+                }
+            }
+        }
+        finally {
+            pumping = false;
+        }
+    };
+    // Mark the preview dirty and ensure the single writer is running (an update already in flight picks
+    // up the new state on its next loop). Synchronous — callers never await a network write.
+    const touch = () => {
+        dirty = true;
+        if (!pumping)
+            pumpDone = runPump();
+    };
+    touch(); // mount the "💭 Thinking…" preview immediately
+    // Stop the pump and await any in-flight update, so the final write below is strictly the LAST one to
+    // the preview (no stale frame landing after the answer).
+    const finish = async () => {
+        stopped = true;
+        wakeThrottle?.(); // cut an in-flight throttle so the final write is not delayed up to STREAM_THROTTLE_MS
+        await pumpDone?.catch(() => { });
+    };
+    /** Terminal write, whatever tier the preview reached. */
+    const settle = async (text) => {
+        await finalize(api, target, preview, text, nextSeq);
+    };
+    try {
+        for await (const e of events) {
+            if (e.type === "text") {
+                answer += e.delta;
+                if (answerPreviewSince === undefined && answer.trim() !== "")
+                    answerPreviewSince = Date.now();
+                touch();
+            }
+            else if (e.type === "thinking") {
+                thinking += e.delta;
+                touch();
+            }
+            else if (e.type === "tool_started") {
+                const arg = summarizeArgs(e.args);
+                toolIndexById.set(e.id, tools.length);
+                tools.push({ label: arg ? `${e.name} ${arg}` : e.name, status: "running" });
+                touch();
+            }
+            else if (e.type === "tool_ended") {
+                const i = toolIndexById.get(e.id);
+                const t = i === undefined ? undefined : tools[i];
+                if (t)
+                    t.status = e.isError ? "error" : "ok";
+                touch();
+            }
+            else if (e.type === "completed") {
+                await finish();
+                // Settle the preview into the final answer; the persisted card is the answer alone — the
+                // process (thinking/tools) was preview-only. Mark finalized BEFORE delivering: the terminal was
+                // reached, so a delivery failure here is a plain failure, not an "abnormal exit" (which would
+                // wrongly fire the finally's neutral-notice fallback = double delivery + wrong text).
+                finalized = true;
+                await settle(answer.trim() !== "" ? answer : "(no reply)");
+                return;
+            }
+            else if (e.type === "failed") {
+                await finish();
+                // Two audiences: the chat (customer-facing — formatError, neutral by default) and the operator
+                // log (dev-facing — the full details, via the throw below + the handler's catch). Same terminal
+                // write as completed; an empty notice deletes the preview (suppress = no residue). Best-effort —
+                // we throw below regardless.
+                finalized = true;
+                {
+                    const msg = formatError({ details: e.details, retryable: e.retryable }) ?? "";
+                    try {
+                        await settle(msg);
+                    }
+                    catch (deliveryError) {
+                        // Preserve the Agent failure as the primary error below, but keep the broken final hop in
+                        // the operator-visible chain — otherwise the log falsely implies the user saw the notice.
+                        log.error(`${label} failed to deliver the agent-failure notice: ${String(deliveryError)}`);
+                    }
+                }
+                throw new Error(`agent failed: ${e.details} (retryable=${e.retryable})`);
+            }
+        }
+        throw new Error("stream ended without a terminal event"); // violates SPEC MUST 1
+    }
+    finally {
+        await finish();
+        // Abnormal exit (stream ended without a terminal, the generator threw, or the consumer abandoned):
+        // no terminal write ran. Show the SAME neutral notice a `failed` event would — the preview may show
+        // real partial work, so don't delete it silently, and don't leave the user in silence. A suppressing
+        // onError still collapses to a delete (finalize on empty text).
+        if (!finalized) {
+            // retryable:false — an abnormal end (no terminal / a throw) is of UNKNOWN retryability, so use the
+            // neutral "something went wrong" default rather than promising "try again" that may not help.
+            const notice = formatError({ details: "the turn ended without completing", retryable: false }) ?? "";
+            try {
+                await settle(notice);
+            }
+            catch (deliveryError) {
+                // The stream's original throw remains primary; this explicit line records that the user-facing
+                // terminal notice failed too instead of silently breaking the responsibility chain.
+                log.error(`${label} failed to deliver the abnormal-turn notice: ${String(deliveryError)}`);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,70 @@
+/**
+ * One-click app creation ("scan to create") — the OAuth 2.0 Device Authorization Grant (RFC 8628)
+ * flow the platform provides for agent apps: `begin` returns a one-time verification URL the user
+ * opens in Feishu/Lark and confirms (the platform pre-configures the agent app template: bot
+ * capability, messaging scopes, event subscriptions); polling returns the new app's credentials.
+ *
+ * Hand-rolled on fetch, no SDK: the wire protocol is two form-encoded POSTs to the accounts endpoint
+ * plus RFC 8628's polling error dance — shared verbatim by all four official SDKs (node/python/java/go),
+ * which makes it a de-facto stable surface even though only the SDKs document it. Provenance:
+ * larksuite/node-sdk `scene/registration` (registerApp). If the platform ever moves this behind
+ * something non-trivial (signed payloads, websockets), adopt the official SDK instead of chasing it —
+ * the same tripwire as feishu-api.ts.
+ *
+ * The scanning user's tenant decides the brand: a Lark-tenant user flips polling to the Lark accounts
+ * domain mid-flow (`tenant_brand: "lark"`), and the result carries the brand so the caller can point
+ * everything else (API origin) at the right cloud.
+ */
+/**
+ * Additive app config carried on the confirm-page URL (`addons` query param): extra scopes/events
+ * merged ON TOP of the platform's agent template — base permissions can never be removed. Shape and
+ * encoding (JSON → gzip → base64url) follow the official SDKs (provenance: node-sdk
+ * scene/registration); item names unknown to the platform catalog are silently dropped by the page.
+ */
+export interface FeishuAppAddons {
+    scopes?: {
+        tenant?: string[];
+        user?: string[];
+    };
+    events?: {
+        items?: {
+            tenant?: string[];
+            user?: string[];
+        };
+    };
+    callbacks?: {
+        items?: string[];
+    };
+}
+export interface RegisterFeishuAppOptions {
+    /** Pre-filled app name shown on the confirm page (`{user}` expands to the scanning user's name). */
+    name?: string;
+    /** Pre-filled app description. */
+    desc?: string;
+    /** Extra scopes/events merged onto the agent template at creation (see {@link FeishuAppAddons}). */
+    addons?: FeishuAppAddons;
+    /** Called once the one-time verification URL is ready — print it / render it as a QR code. */
+    onVerificationUrl: (info: {
+        url: string;
+        expiresInS: number;
+    }) => void;
+    /** Cancel the polling. */
+    signal?: AbortSignal;
+    /** Accounts origins, for tests. */
+    accountsBaseUrl?: string;
+    larkAccountsBaseUrl?: string;
+}
+export interface RegisteredFeishuApp {
+    appId: string;
+    appSecret: string;
+    /** "feishu" | "lark" — which cloud the scanning user's tenant lives on (drives the API origin). */
+    tenantBrand?: string;
+    /** The scanning user's open_id, when the platform returns it. */
+    openId?: string;
+}
+/**
+ * Run the scan-to-create flow (module header): begin → hand the verification URL to the caller →
+ * poll until the user confirms. Resolves with the new app's credentials; rejects on denial, expiry,
+ * abort, or a transport failure — every rejection is a plain Error whose message says what to do.
+ */
+export declare function registerFeishuApp(options: RegisterFeishuAppOptions): Promise<RegisteredFeishuApp>;