@fastagent-sh/fastagent 0.14.0 → 0.16.0

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

@@ -11,7 +11,8 @@
  * BUFFERED resources come from earlier un-summoned thread/group discussion and degrade per attachment:
  * one expired background file must not block the current ask or hide its still-readable siblings.
  */
-import { type Agent, type AgentEvent } from "../../agent.ts";
+import type { Agent, AgentEvent } from "../../agent.ts";
+import { type BusyRetry } from "../invoke-turn-kit.ts";
 import type { FeishuBufferedRef } from "./context-buffer.ts";
 import type { FeishuApi } from "./feishu-api.ts";
 /** Everything the transport needs to fetch a turn's attachments. */
@@ -23,7 +24,7 @@ export interface FeishuTurnTransport {
 }
 /** An attachment reference: the resource key inside its CARRYING message (the resource API addresses
  *  bytes by message_id + key, so the pair travels together through the turn record). */
-export interface FeishuAttachmentInput {
+interface FeishuAttachmentInput {
     msg: string;
     key: string;
     name?: string;
@@ -42,24 +43,10 @@ export interface FeishuTurnAttachments {
         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.
+ * Run one turn: resolve its inputs, then stream agent.invoke with the shared busy-wait
+ * (invoke-turn-kit — `onCompleted` is the durable-commit point; see streamTurnWithBusyRetry). A
+ * primary-input failure surfaces as a `failed` event (never a silent drop).
  */
 export declare function invokeFeishuTurn(agent: Agent, session: string, text: string, transport: FeishuTurnTransport, attachments: FeishuTurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;
+export {};

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

@@ -1,20 +1,7 @@
-/**
- * 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 { SESSION_BUSY_CODE } from "../../agent.js";
 import { log } from "../../log.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
 import { parseContent } from "./parse.js";
-import { codePointPrefix } from "./text.js";
+import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } 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.)";
@@ -28,24 +15,41 @@ async function resolveTurnInputs(t, attachments) {
     let referentBlock = "";
     if (attachments.primary.parentId !== undefined) {
         const parentId = attachments.primary.parentId;
-        const parent = await t.api.getMessage(parentId);
-        if (!parent)
-            throw new Error(`replied-to message ${parentId} is not readable`);
-        const parsed = parseContent({
-            message_type: parent.msg_type ?? "unknown",
-            content: parent.body?.content ?? "",
-            mentions: parent.mentions,
+        // A referent is CONTEXT, not the ask. Losing it (deleted, restricted, unreadable) must not cost
+        // the user their answer — every first message of a thread carries one, so a hard failure here
+        // would turn an ordinary platform edge into a lost turn. Degrade visibly instead: the operator
+        // gets a warning, and the model is told the quote could not be read rather than being left to
+        // guess what "about that" refers to.
+        // A deleted or invisible message comes back as an EMPTY item list rather than an error, so the
+        // warning belongs on the branch that renders the marker — that is the one the operator must see.
+        let failure;
+        const parent = await t.api.getMessage(parentId).catch((error) => {
+            failure = String(error);
+            return undefined;
         });
-        // 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: parentId, key });
-        for (const ref of parsed.fileRefs)
-            files.push({ msg: 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 ${parentId}${from ? `, from ${from}` : ""}): ${codePointPrefix(parsed.text, 560) || "(empty)"}]`;
+        if (!parent) {
+            log.warn(`${t.label} could not read replied-to message ${parentId} (${failure ?? "no such message"}) — the model is told the quote is unreadable`);
+            // Fall THROUGH: the resources this turn carries are the ask itself. Returning here would drop
+            // the images and files the user explicitly attached along with the referent they merely quoted.
+            referentBlock = `\n\n[replied-to message (msg ${parentId}) could not be read]`;
+        }
+        else {
+            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: parentId, key });
+            for (const ref of parsed.fileRefs)
+                files.push({ msg: 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 ${parentId}${from ? `, from ${from}` : ""}): ${truncateCodePointPrefix(parsed.text, REFERENT_MAX_CODE_POINTS) || "(empty)"}]`;
+        }
     }
     // Primary first and fail-fast: these are resources the current user explicitly pointed at.
     const imageRefs = [];
@@ -84,46 +88,25 @@ async function resolveTurnInputs(t, attachments) {
             log.warn(`${t.label} could not load an earlier (buffered) attachment: ${String(result.reason)}`);
         }
     }
-    const missing = lost + attachments.buffered.skipped;
-    const bufferedNote = missing > 0
-        ? `\n[note: ${missing} attachment(s) from the earlier discussion are not loaded (expired, or older than the most recent few)]`
-        : "";
-    const backgroundImageManifest = backgroundImages.length
-        ? `\n\n[background vision images from earlier discussion — appended after ${imageRefs.length} primary image(s):\n${backgroundImages
-            .map(({ ref }, index) => `- vision image ${imageRefs.length + index + 1}: from ${ref.from}, msg ${ref.messageId}`)
-            .join("\n")}\n]`
-        : "";
+    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped);
+    const backgroundImageManifest = backgroundImagesManifest(imageRefs.length, backgroundImages.map(({ ref }) => ref));
     const allFiles = [
         ...downloaded,
         ...backgroundFiles.map(({ file, ref }) => ({
             ...file,
-            name: `${file.name} (from ${ref.from}, msg ${ref.messageId}, earlier discussion)`,
+            name: attributedFileName(file.name, ref.from, ref.messageId),
         })),
     ];
-    const manifest = allFiles.length
-        ? `\n\n[attached files — read them with your tools:\n${allFiles.map((file) => `- ${file.name} (${file.size} bytes) → ${file.path}`).join("\n")}\n]`
-        : "";
     const allImages = [...imageRefs, ...backgroundImages.map(({ image }) => image)];
     return {
         images: allImages.length ? allImages : undefined,
-        promptSuffix: `${referentBlock}${bufferedNote}${backgroundImageManifest}${manifest}`,
+        promptSuffix: `${referentBlock}${missingNote}${backgroundImageManifest}${attachedFilesManifest(allFiles)}`,
     };
 }
-// 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. 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.
+ * Run one turn: resolve its inputs, then stream agent.invoke with the shared busy-wait
+ * (invoke-turn-kit — `onCompleted` is the durable-commit point; see streamTurnWithBusyRetry). A
+ * primary-input failure surfaces as a `failed` event (never a silent drop).
  */
 export async function* invokeFeishuTurn(agent, session, text, transport, attachments, onCompleted, busyRetry = DEFAULT_BUSY_RETRY) {
     let resolved;
@@ -135,23 +118,5 @@ export async function* invokeFeishuTurn(agent, session, text, transport, attachm
         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));
-    }
+    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
 }

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

@@ -76,7 +76,7 @@ export type FeishuResourceKind = "image" | "file" | "audio" | "video";
  * A resource locator. User-sent resources are scoped by BOTH their carrying message id and resource
  * key; a bare file_key/image_key is insufficient for the message-resource download API.
  */
-export interface FeishuResourceRef {
+interface FeishuResourceRef {
     kind: FeishuResourceKind;
     messageId: string;
     key: string;
@@ -87,7 +87,6 @@ export interface NormalizedFeishuMessage {
     conversation: {
         chatId: string;
         threadId?: string;
-        rootId?: string;
     };
     content: {
         text: string;
@@ -95,3 +94,4 @@ export interface NormalizedFeishuMessage {
         resources: FeishuResourceRef[];
     };
 }
+export {};

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

@@ -4,7 +4,7 @@
  * converts resource keys into message-scoped locators before the turn engine sees them.
  */
 import type { FeishuMessage, FeishuMessageEvent, FeishuResourceKind, NormalizedFeishuMessage } from "./model.ts";
-export interface DecodedFeishuResource {
+interface DecodedFeishuResource {
     kind: FeishuResourceKind;
     key: string;
     name?: string;
@@ -20,3 +20,4 @@ export interface DecodedFeishuContent {
 export declare function decodeFeishuContent(message: Pick<FeishuMessage, "message_type" | "content" | "mentions">): DecodedFeishuContent;
 /** Normalize one verified message event. Returns null only when its required identity is absent. */
 export declare function normalizeFeishuMessage(event: FeishuMessageEvent): NormalizedFeishuMessage | null;
+export {};

package/dist/channels/feishu/normalize.js

@@ -121,7 +121,6 @@ export function normalizeFeishuMessage(event) {
         conversation: {
             chatId: message.chat_id,
             threadId: message.thread_id,
-            rootId: message.root_id,
         },
         content: {
             text: decoded.text,

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

@@ -7,9 +7,9 @@
 import type { FeishuCloudKind } from "./cloud.ts";
 import type { FeishuMention, FeishuMessage, FeishuMessageEvent, FeishuRoute, FeishuSender } from "./model.ts";
 export type { FeishuMention, FeishuMessage, FeishuMessageEvent, FeishuRoute, FeishuSender };
-/** Legacy compatibility shape returned by {@link parseContent}. New internal code consumes normalized
- * resource refs, which retain resource kind + carrying message id. */
-export interface FeishuAttachmentRef {
+/** A resource reduced to what a caller needs to fetch and name it — the kind and carrying message id
+ * that {@link decodeFeishuContent} attaches are supplied by the caller's own context. */
+interface FeishuAttachmentRef {
     key: string;
     name?: string;
 }
@@ -19,14 +19,27 @@ export interface ParsedFeishuContent {
     fileRefs: FeishuAttachmentRef[];
 }
 /**
- * Compatibility decoder for existing helpers/tests and parent-message resolution. The canonical
- * decoder now emits typed resources; this wrapper projects them onto the historical parallel arrays.
+ * The decoder projected onto flat per-kind arrays, for callers that resolve a message on their own
+ * (the prompt envelope, and the quoted parent whose resources are carried by the PARENT message id).
+ * `decodeFeishuContent` stays canonical: this only reshapes what it returns.
  */
 export declare function parseContent(message: Pick<FeishuMessage, "message_type" | "content" | "mentions">): ParsedFeishuContent;
 /** A stable sender label for attribution. Display names require an additional contacts permission. */
 export declare function senderLabel(sender: FeishuSender | undefined): string | undefined;
-/** The place a message lives (chat, or chat:topic in a topic group) — the legacy default session key. */
-export declare function placeKey(message: Pick<FeishuMessage, "chat_id" | "thread_id">): string;
+/** Whichever id flavour the tenant populates. `sender_id` is a union and which members are filled is
+ *  app configuration, not an invariant — callers only ever compare these for distinctness. */
+export declare function senderId(sender: FeishuSender | undefined): string | undefined;
+/**
+ * The place a message lives (the chat, or a thread within it) — the session key (participant model §5),
+ * and the key thread participation is recorded under, since that record is a claim about this session.
+ *
+ * Branded with the channel kind, like Slack's twin, because session ids share ONE namespace across
+ * every channel in a deployment: without it a `feishu` and a `lark` chat carrying the same platform id
+ * would answer into the same memory. The length bound is the FILENAME the id becomes (sessions.ts
+ * percent-encodes it, so each `:` costs three), and the worst case here — brand + a 35-char chat id +
+ * a 36-char thread id — encodes to well under 100 bytes against the filesystem's 255.
+ */
+export declare function placeKey(kind: string, message: Pick<FeishuMessage, "chat_id" | "thread_id">): string;
 /** The canonical Feishu-branded prompt envelope. */
 export declare function feishuEnvelope(event: FeishuMessageEvent): string;
 /** Internal compatibility seam: bind the canonical envelope shape to one cloud's branded tag. */
@@ -36,7 +49,8 @@ export declare function mentionsBot(message: Pick<FeishuMessage, "mentions">, bo
 /**
  * Default EXPLICIT-summon policy: ignore non-user senders, always answer p2p, and answer groups only
  * when THIS bot is structurally mentioned. No bot identity means group routing fails closed. The
- * stateful channel wiring may additionally admit unmentioned continuations from its managed-root index.
+ * stateful channel wiring may additionally admit unmentioned messages in a thread it takes part in
+ * (docs/design/participant-model.md §3).
  */
 export declare function defaultFeishuRoute(event: FeishuMessageEvent, options?: {
     botOpenId?: string;

package/dist/channels/feishu/parse.js

@@ -1,7 +1,8 @@
 import { decodeFeishuContent } from "./normalize.js";
 /**
- * Compatibility decoder for existing helpers/tests and parent-message resolution. The canonical
- * decoder now emits typed resources; this wrapper projects them onto the historical parallel arrays.
+ * The decoder projected onto flat per-kind arrays, for callers that resolve a message on their own
+ * (the prompt envelope, and the quoted parent whose resources are carried by the PARENT message id).
+ * `decodeFeishuContent` stays canonical: this only reshapes what it returns.
  */
 export function parseContent(message) {
     const decoded = decodeFeishuContent(message);
@@ -15,12 +16,27 @@ export function parseContent(message) {
 }
 /** A stable sender label for attribution. Display names require an additional contacts permission. */
 export function senderLabel(sender) {
-    const id = sender?.sender_id?.open_id ?? sender?.sender_id?.user_id ?? sender?.sender_id?.union_id;
+    const id = senderId(sender);
     return id ? `user ${id}` : undefined;
 }
-/** The place a message lives (chat, or chat:topic in a topic group) — the legacy default session key. */
-export function placeKey(message) {
-    return message.thread_id ? `${message.chat_id}:${message.thread_id}` : message.chat_id;
+/** Whichever id flavour the tenant populates. `sender_id` is a union and which members are filled is
+ *  app configuration, not an invariant — callers only ever compare these for distinctness. */
+export function senderId(sender) {
+    return sender?.sender_id?.open_id ?? sender?.sender_id?.user_id ?? sender?.sender_id?.union_id;
+}
+/**
+ * The place a message lives (the chat, or a thread within it) — the session key (participant model §5),
+ * and the key thread participation is recorded under, since that record is a claim about this session.
+ *
+ * Branded with the channel kind, like Slack's twin, because session ids share ONE namespace across
+ * every channel in a deployment: without it a `feishu` and a `lark` chat carrying the same platform id
+ * would answer into the same memory. The length bound is the FILENAME the id becomes (sessions.ts
+ * percent-encodes it, so each `:` costs three), and the worst case here — brand + a 35-char chat id +
+ * a 36-char thread id — encodes to well under 100 bytes against the filesystem's 255.
+ */
+export function placeKey(kind, message) {
+    const chat = `${kind}:${message.chat_id}`;
+    return message.thread_id ? `${chat}:${message.thread_id}` : chat;
 }
 /** The canonical Feishu-branded prompt envelope. */
 export function feishuEnvelope(event) {
@@ -52,7 +68,8 @@ export function mentionsBot(message, botOpenId) {
 /**
  * Default EXPLICIT-summon policy: ignore non-user senders, always answer p2p, and answer groups only
  * when THIS bot is structurally mentioned. No bot identity means group routing fails closed. The
- * stateful channel wiring may additionally admit unmentioned continuations from its managed-root index.
+ * stateful channel wiring may additionally admit unmentioned messages in a thread it takes part in
+ * (docs/design/participant-model.md §3).
  */
 export function defaultFeishuRoute(event, options) {
     const message = event.message;

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

@@ -1,12 +1,9 @@
 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;
+import { type ChannelFailure, defaultErrorMessage } from "../preview-kit.ts";
+/** A terminal failure, as the channel hands it to `onError` — the shared channel shape. */
+export type FeishuFailure = ChannelFailure;
+export { defaultErrorMessage };
 /** 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 = {

package/dist/channels/feishu/preview.js

@@ -23,41 +23,16 @@ 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.";
-}
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../preview-kit.js";
+import { truncateUtf8 } from "../text.js";
+export { defaultErrorMessage };
 /** 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. */
@@ -88,8 +63,9 @@ async function finalize(api, target, preview, text, seq) {
             // Settle failed (card expired / rejected) — fall through to delete + fresh send below.
         }
         if (settled) {
-            // Threaded continuations must keep reply_in_thread; continuous top-level group replies intentionally
-            // avoid repeating the quote on every chunk. sendText owns the same distinction for its own chunking.
+            // Threaded continuations must keep reply_in_thread; top-level group replies (target.replyInThread
+            // unset — a custom route, or an ask outside a thread) 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 };
@@ -174,35 +150,16 @@ export async function settleFeishuPreview(api, target, preview, text) {
  * 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 : "";
-    };
+    // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal
+    // policy, the card-budget cap, and delivery below.
+    const turn = createTurnView();
     const view = () => {
-        const v = [thinkingView(), toolView(), answerView()]
-            .filter((s) => s.trim() !== "")
-            .join("\n\n")
-            .trim();
+        const v = composeTurnBody([
+            thinkingLine(turn, THINKING_PREVIEW),
+            toolLines(turn),
+            turn.retrying ? RETRY_NOTICE : "",
+            revealedAnswer(turn, STREAM_THROTTLE_MS),
+        ]);
         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
@@ -243,105 +200,31 @@ export async function streamFeishuReply(events, api, target, formatError, initia
             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();
-    };
+    // The shared single-writer pump (preview-kit) serializes snapshots to the one preview — which also
+    // guarantees the card's strictly-increasing `sequence` lands in order (no concurrent frames).
+    const { touch, finish } = createPreviewPump({
+        flush: flushPreview,
+        throttleMs: STREAM_THROTTLE_MS,
+        onError: (e) => log.warn(`${label} live preview failed (final reply still sends): ${String(e)}`),
+    });
     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") {
+            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)");
+                await settle(turn.answer.trim() !== "" ? turn.answer : "(no reply)");
                 return;
             }
-            else if (e.type === "failed") {
+            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
@@ -361,6 +244,8 @@ export async function streamFeishuReply(events, api, target, formatError, initia
                 }
                 throw new Error(`agent failed: ${e.details} (retryable=${e.retryable})`);
             }
+            if (applyTurnEvent(turn, e))
+                touch();
         }
         throw new Error("stream ended without a terminal event"); // violates SPEC MUST 1
     }

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

@@ -21,7 +21,7 @@
  * 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 {
+interface FeishuAppAddons {
     scopes?: {
         tenant?: string[];
         user?: string[];
@@ -68,3 +68,4 @@ export interface RegisteredFeishuApp {
  * 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>;
+export {};