@fastagent-sh/fastagent 0.21.0 → 0.22.0

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

@@ -1,5 +1,5 @@
 import { log } from "../../log.js";
-import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../kit/invoke-turn-kit.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, loadBackground, missingAttachmentsNote, turnStream, } from "../kit/invoke-turn-kit.js";
 import { BUFFER_ATTACH_MAX } from "../kit/context-buffer.js";
 import { parseContent } from "./parse.js";
 import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../kit/text.js";
@@ -41,9 +41,8 @@ function fetchedSenderLabel(sender, appId) {
  * is what makes the walk bounded by STRUCTURE rather than by a level count someone picked.
  *
  * This is pointer resolution, not history. Session memory — what this place already knows — is a
- * different track (design/participant-model.md §8): a one-hop version of this walk was removed once
- * for trying to be that substitute; it returns doing only the pointer's job, which is also why it
- * walks through ANY author's message — the chain is the platform's structure, not a conversation the
+ * different track (design/participant-model.md §8), so this walk does only the pointer's job, which is also
+ * why it walks through ANY author's message — the chain is the platform's structure, not a conversation the
  * agent took part in. The repetition this implies (an established session re-reads chain text it may
  * already hold, each reply turn) is accepted deliberately and bounded: ancestors are CONTEXT, not
  * the ask, so their text shares ONE further `REFERENT_MAX_CODE_POINTS` budget across the whole chain
@@ -201,40 +200,25 @@ async function resolveTurnInputs(t, attachments) {
     const mergedFiles = capMerge(chain.files, attachments.buffered.files, primaryFiles);
     const bufferedImages = mergedImages.kept;
     const bufferedFiles = mergedFiles.kept;
-    const backgroundImages = [];
-    const backgroundFiles = [];
-    let lost = 0;
-    const imageResults = await Promise.allSettled(bufferedImages.map(async (ref) => ({ ref, image: await t.api.fetchImage(ref.messageId, ref.key) })));
-    for (const result of imageResults) {
-        if (result.status === "fulfilled")
-            backgroundImages.push(result.value);
-        else {
-            lost++;
-            log.warn(`${t.label} could not load an earlier (buffered) image: ${String(result.reason)}`);
-        }
-    }
-    const fileResults = await Promise.allSettled(bufferedFiles.map(async (ref) => ({
-        ref,
-        file: await t.api.fetchFile(ref.messageId, ref.key, ref.name ?? ref.key, t.chatId, t.filesDir),
-    })));
-    for (const result of fileResults) {
-        if (result.status === "fulfilled")
-            backgroundFiles.push(result.value);
-        else {
-            lost++;
-            log.warn(`${t.label} could not load an earlier (buffered) attachment: ${String(result.reason)}`);
-        }
-    }
-    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped + mergedImages.dropped + mergedFiles.dropped);
-    const backgroundImageManifest = backgroundImagesManifest(imageRefs.length, backgroundImages.map(({ ref }) => ref));
+    const backgroundImages = await loadBackground(bufferedImages, (ref) => t.api.fetchImage(ref.messageId, ref.key), {
+        label: t.label,
+        what: "image",
+    });
+    const backgroundFiles = await loadBackground(bufferedFiles, (ref) => t.api.fetchFile(ref.messageId, ref.key, ref.name ?? ref.key, t.chatId, t.filesDir), { label: t.label, what: "attachment" });
+    const missingNote = missingAttachmentsNote(backgroundImages.lost +
+        backgroundFiles.lost +
+        attachments.buffered.skipped +
+        mergedImages.dropped +
+        mergedFiles.dropped);
+    const backgroundImageManifest = backgroundImagesManifest(imageRefs.length, backgroundImages.loaded.map(({ ref }) => ref));
     const allFiles = [
         ...downloaded,
-        ...backgroundFiles.map(({ file, ref }) => ({
-            ...file,
-            name: attributedFileName(file.name, ref.from, ref.messageId),
+        ...backgroundFiles.loaded.map(({ value, ref }) => ({
+            ...value,
+            name: attributedFileName(value.name, ref.from, ref.messageId),
         })),
     ];
-    const allImages = [...imageRefs, ...backgroundImages.map(({ image }) => image)];
+    const allImages = [...imageRefs, ...backgroundImages.loaded.map(({ value }) => value)];
     return {
         images: allImages.length ? allImages : undefined,
         promptSuffix: `${referentBlock}${missingNote}${backgroundImageManifest}${attachedFilesManifest(allFiles)}`,
@@ -242,25 +226,23 @@ async function resolveTurnInputs(t, attachments) {
     };
 }
 /**
- * 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).
+ * Run one turn: resolve its inputs, then ask the agent (invoke-turn-kit — 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;
-    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}${REPLY_INSTRUCTION}`, images: resolved.images };
-    // A thread turn names its lineage: parent place + the message ids that can locate the branch point
-    // (the referent and its chain — nearest first). The engine reads them ONCE, when the thread's
-    // session does not exist yet; on every later turn they ride along inertly.
-    const scope = transport.parentSession === undefined
-        ? { session }
-        : { session, parentSession: transport.parentSession, branchHints: resolved.referentIds };
-    yield* streamTurnWithBusyRetry(agent, scope, prompt, { label: transport.label, onCompleted, busyRetry });
+export function feishuTurnStream(agent, session, text, transport, attachments, busyRetry = DEFAULT_BUSY_RETRY) {
+    return turnStream({
+        agent,
+        label: transport.label,
+        busyRetry,
+        resolve: () => resolveTurnInputs(transport, attachments),
+        turn: (resolved) => ({
+            // Lineage is resolved per turn; the engine reads it only when creating a new session.
+            scope: (transport.parentSession === undefined
+                ? { session }
+                : { session, parentSession: transport.parentSession, branchHints: resolved.referentIds }),
+            prompt: { text: `${text}${resolved.promptSuffix}${REPLY_INSTRUCTION}`, images: resolved.images },
+        }),
+        // A resource fetch that failed may simply succeed on the redelivery.
+        retryableLoadFailure: () => true,
+    });
 }

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

@@ -1,12 +1,5 @@
-/**
- * Canonical Feishu/Lark protocol and normalized-message models.
- *
- * Raw wire types stay at the webhook/policy boundary: authors' existing `route(event)` callbacks keep
- * receiving the platform event unchanged. The narrow normalized shape below owns only what currently
- * benefits from normalization: conversation-place identity, decoded content, mention presence, and
- * message-scoped resource locators. Do not pre-model unused transport metadata for a future ingress.
- */
-/** The v2 event envelope header. Feishu and Lark use the same wire shape. */
+/** Canonical Feishu/Lark protocol and normalized-message models. */
+/** The v2 event envelope header. */
 export interface FeishuEventHeader {
     event_id?: string;
     event_type?: string;
@@ -16,7 +9,7 @@ export interface FeishuEventHeader {
     tenant_key?: string;
     [k: string]: unknown;
 }
-/** One entry of a message's `mentions` array. `key` is the placeholder carried in text content. */
+/** One entry of a message's `mentions` array. */
 export interface FeishuMention {
     key: string;
     id?: {
@@ -25,11 +18,10 @@ export interface FeishuMention {
         union_id?: string;
     };
     name?: string;
-    mentioned_type?: string;
     tenant_key?: string;
     [k: string]: unknown;
 }
-/** A received `im.message.receive_v1` message. `content` is JSON encoded according to `message_type`. */
+/** A received `im.message.receive_v1` message. */
 export interface FeishuMessage {
     message_id: string;
     root_id?: string;
@@ -42,11 +34,6 @@ export interface FeishuMessage {
     message_type: string;
     content: string;
     mentions?: FeishuMention[];
-    user_agent?: string;
-    lark_agent_context?: {
-        active_chat_id?: string;
-        [k: string]: unknown;
-    };
     [k: string]: unknown;
 }
 export interface FeishuSender {
@@ -72,10 +59,6 @@ export interface FeishuRoute {
     text?: string;
 }
 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.
- */
 interface FeishuResourceRef {
     kind: FeishuResourceKind;
     messageId: string;

package/dist/channels/feishu/model.js

@@ -1,9 +1,2 @@
-/**
- * Canonical Feishu/Lark protocol and normalized-message models.
- *
- * Raw wire types stay at the webhook/policy boundary: authors' existing `route(event)` callbacks keep
- * receiving the platform event unchanged. The narrow normalized shape below owns only what currently
- * benefits from normalization: conversation-place identity, decoded content, mention presence, and
- * message-scoped resource locators. Do not pre-model unused transport metadata for a future ingress.
- */
+/** Canonical Feishu/Lark protocol and normalized-message models. */
 export {};

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

@@ -1,8 +1,4 @@
-/**
- * Pure Feishu/Lark message normalization. The platform sends a stable event shell but encodes the
- * actual message body as a JSON string selected by `message_type`; this module is the one decoder and
- * converts resource keys into message-scoped locators before the turn engine sees them.
- */
+/** Pure Feishu/Lark message normalization. */
 import type { FeishuMessage, FeishuMessageEvent, FeishuResourceKind, NormalizedFeishuMessage } from "./model.ts";
 interface DecodedFeishuResource {
     kind: FeishuResourceKind;
@@ -13,11 +9,7 @@ export interface DecodedFeishuContent {
     text: string;
     resources: DecodedFeishuResource[];
 }
-/**
- * Decode one JSON-string message body. Unknown or malformed external input degrades to a visible
- * marker rather than throwing, preserving the channel's existing fail-visible prompt behavior.
- */
+/** Decode one JSON-string message body. */
 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

@@ -1,18 +1,6 @@
 /**
- * Render one paragraph of tagged nodes to a line, collecting any resource it carries INTO the sink
- * the caller supplies — or none, when the caller passes no sink.
- *
- * Shared by `post` and `interactive` because the platform hands both out in the same shape. Card-only
- * shapes are handled here rather than in a second walker: `note` nests its own `elements`, and the
- * widget tags (button/select/overflow/date_picker) carry their user-visible label in `text` or
- * `placeholder` — a card is read for what it SAYS, so a label is content and an unlabelled control is
- * nothing.
- *
- * The OPTIONAL sink is the whole reason this is a parameter rather than a return value: a card's
- * resources are documented as unfetchable (see the card branch), so that caller renders the same
- * `[image]` / `[video]` markers into the text while collecting nothing. The markers still tell the
- * model what is there; what must not happen is a key entering the turn's PRIMARY inputs, which load
- * fail-fast.
+ * Render one paragraph of tagged nodes to a line, collecting any resource it carries INTO the sink the caller supplies
+ * — or none, when the caller passes no sink.
  */
 function renderNodes(nodes, resources) {
     if (!Array.isArray(nodes))
@@ -70,10 +58,7 @@ function restoreMentions(text, mentions) {
     }
     return out;
 }
-/**
- * Decode one JSON-string message body. Unknown or malformed external input degrades to a visible
- * marker rather than throwing, preserving the channel's existing fail-visible prompt behavior.
- */
+/** Decode one JSON-string message body. */
 export function decodeFeishuContent(message) {
     const rawType = typeof message.message_type === "string" ? message.message_type : "unknown";
     let content;
@@ -102,18 +87,7 @@ export function decodeFeishuContent(message) {
             }
             return { text: lines.join("\n"), resources };
         }
-        // A CARD, as the platform hands it BACK. What we send is an entity reference
-        // (`{type:"card",data:{card_id}}`, card.ts) whose text lives in cardkit — but a query API renders
-        // the card down to `title` + `elements` (paragraphs of the same tagged nodes as `post`), so the
-        // content is readable without a second remote call. This is the message type the agent's OWN
-        // answers are, so the case that matters is a user following up on one: without this branch a
-        // reply-referent that is the agent's own card decoded to the bare `[interactive message]` marker
-        // and the model was told its own answer was unreadable (field-observed).
-        //
-        // BOTH spellings on purpose: the platform's own docs disagree with themselves — the field table
-        // says `interactive` (what the receive EVENT carries) while the message-object example shows
-        // `"msg_type": "card"`. Matching one would leave the other silently on the default branch, which
-        // is exactly the symptom this fixes.
+        // A CARD, as the platform hands it BACK.
         case "interactive":
         case "card": {
             const lines = [];
@@ -122,21 +96,13 @@ export function decodeFeishuContent(message) {
                 lines.push(title);
             const paragraphs = Array.isArray(content.elements) ? content.elements : [];
             for (const paragraph of paragraphs) {
-                // NO resource sink, deliberately. The platform documents that a card's resources cannot be
-                // fetched at all: `im/v1/messages/:id/resources/:key` answers 234043 ("Unsupported message
-                // type") for a card message id, by stated limitation rather than by permission. Collecting a
-                // key here would hand the turn a PRIMARY input that is guaranteed to fail its fail-fast load
-                // — turning "the card reads as a marker" (the old behaviour) into "the whole turn errors",
-                // which is strictly worse than the gap this branch exists to close. The text still renders
-                // `[image]` / `[video]`, so the model knows what is there and that it does not have it.
-                //
-                // Tolerate both shapes: elements as paragraphs (array of arrays) and a flat element list.
+                // NO resource sink, deliberately.
                 const line = Array.isArray(paragraph) ? renderNodes(paragraph) : renderNodes([paragraph]);
                 if (line)
                     lines.push(line);
             }
-            // An unrenderable card (all controls, no labels) still says something by existing — keep the
-            // marker rather than returning empty, which reads as "the message was blank".
+            // An unrenderable card (all controls, no labels) still says something by existing — keep the marker rather than
+            // returning empty, which reads as "the message was blank".
             return { text: lines.length > 0 ? lines.join("\n") : `[${rawType} message]`, resources };
         }
         case "image": {
@@ -176,7 +142,6 @@ export function decodeFeishuContent(message) {
             return { text: `[${rawType} message]`, resources };
     }
 }
-/** Normalize one verified message event. Returns null only when its required identity is absent. */
 export function normalizeFeishuMessage(event) {
     const message = event.message;
     if (!message || typeof message.message_id !== "string" || typeof message.chat_id !== "string")

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

@@ -1,14 +1,8 @@
-/**
- * Canonical Feishu protocol policy and prompt-envelope helpers — PURE. Raw event types remain public
- * for the existing `route(event)` authoring surface; JSON-string content decoding is delegated to the
- * normalized-message boundary in normalize.ts so the turn engine and compatibility wrappers share one
- * decoder.
- */
+/** Canonical Feishu protocol policy and prompt-envelope helpers — PURE. */
 import type { FeishuCloudKind } from "./cloud.ts";
 import type { FeishuMention, FeishuMessage, FeishuMessageEvent, FeishuRoute, FeishuSender } from "./model.ts";
 export type { FeishuMention, FeishuMessage, FeishuMessageEvent, FeishuRoute, FeishuSender };
-/** 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. */
+/** A resource reduced to what a caller needs to fetch and name it. */
 interface FeishuAttachmentRef {
     key: string;
     name?: string;
@@ -19,27 +13,15 @@ export interface ParsedFeishuContent {
     fileRefs: FeishuAttachmentRef[];
 }
 /**
- * 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.
+ * 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).
  */
 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. */
+/** A stable sender label for attribution. */
 export declare function senderLabel(sender: FeishuSender | undefined): string | undefined;
-/** 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. */
+/** Whichever id flavour the tenant populates. */
 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 (session-store.ts
- * `piSessionId` escapes every character outside `[A-Za-z0-9.-]` as `_XX` / `_uXXXX`, 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.
- */
+/** The place a message lives (the chat, or a thread within it). */
 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;
@@ -48,10 +30,8 @@ export declare function cloudEnvelope(event: FeishuMessageEvent, tag: FeishuClou
 /** Whether the parsed mention list contains this bot's app-scoped open_id. */
 export declare function mentionsBot(message: Pick<FeishuMessage, "mentions">, botOpenId: string | undefined): boolean;
 /**
- * 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 messages in a thread it takes part in
- * (docs/design/participant-model.md §3).
+ * Default EXPLICIT-summon policy: ignore non-user senders, always answer p2p, and answer groups only when THIS bot is
+ * structurally mentioned.
  */
 export declare function defaultFeishuRoute(event: FeishuMessageEvent, options?: {
     botOpenId?: string;

package/dist/channels/feishu/parse.js

@@ -1,8 +1,7 @@
 import { decodeFeishuContent } from "./normalize.js";
 /**
- * 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.
+ * 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).
  */
 export function parseContent(message) {
     const decoded = decodeFeishuContent(message);
@@ -14,27 +13,16 @@ export function parseContent(message) {
             .map((resource) => ({ key: resource.key, name: resource.name })),
     };
 }
-/** A stable sender label for attribution. Display names require an additional contacts permission. */
+/** A stable sender label for attribution. */
 export function senderLabel(sender) {
     const id = senderId(sender);
     return id ? `user ${id}` : undefined;
 }
-/** 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. */
+/** Whichever id flavour the tenant populates. */
 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 (session-store.ts
- * `piSessionId` escapes every character outside `[A-Za-z0-9.-]` as `_XX` / `_uXXXX`, 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.
- */
+/** The place a message lives (the chat, or a thread within it). */
 export function placeKey(kind, message) {
     const chat = `${kind}:${message.chat_id}`;
     return message.thread_id ? `${chat}:${message.thread_id}` : chat;
@@ -53,11 +41,7 @@ export function cloudEnvelope(event, tag) {
         `chat ${message.chat_id} (${message.chat_type})`,
         message.thread_id ? `topic ${message.thread_id}` : undefined,
         from ? `from ${from}` : undefined,
-        // The message's own id is LOAD-BEARING, not decoration: it is the only way this message's id
-        // enters the session transcript, and session inheritance locates a thread's branch point by
-        // searching the parent transcript for exactly these ids (scope.branchHints — session-inheritance.ts).
-        // Remove it and every thread quietly inherits from the room's present instead of the branch
-        // point. It also lets the model name what it is answering in a busy chat.
+        // The message's own id is LOAD-BEARING, not decoration.
         `msg ${message.message_id}`,
     ]
         .filter(Boolean)
@@ -73,10 +57,8 @@ export function mentionsBot(message, botOpenId) {
     return (message.mentions ?? []).some((mention) => mention.id?.open_id === 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 messages in a thread it takes part in
- * (docs/design/participant-model.md §3).
+ * Default EXPLICIT-summon policy: ignore non-user senders, always answer p2p, and answer groups only when THIS bot is
+ * structurally mentioned.
  */
 export function defaultFeishuRoute(event, options) {
     const message = event.message;

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

@@ -1,11 +1,13 @@
 import type { AgentEvent } from "../../agent.ts";
+import * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
+import { type PortFailure } from "../../effect-port.ts";
 import { type FeishuApi, type FeishuTarget } from "./feishu-api.ts";
 import { type ChannelFailure, defaultErrorMessage } from "../kit/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. */
+/** A visible preview mounted into the chat. */
 export type MountedFeishuPreview = {
     kind: "card";
     cardId: string;
@@ -15,20 +17,16 @@ export type MountedFeishuPreview = {
     messageId: string;
 };
 /**
- * Mount one preview message: preferably a streaming card entity (`initial` seeds the process element;
- * the answer element starts empty), 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.
+ * Mount one preview message: preferably a streaming card entity (`initial` seeds the process element; the answer
+ * element starts empty), with a static text message as the visible fallback.
  */
 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. */
+/**
+ * Settle a preview without starting an Agent stream: a queue/poison/defer notice, or a recovered answer whose own
+ * preview died with the run that produced it (`undefined` — then it is one 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.
+ * Consume one turn's event stream into a Feishu-compatible chat, live.
  */
-export declare function streamFeishuReply(events: AsyncIterable<AgentEvent>, api: FeishuApi, target: FeishuTarget, formatError: (failed: FeishuFailure) => string | undefined, initialPreview?: MountedFeishuPreview, label?: string): Promise<void>;
+export declare function feishuReply(events: Stream.Stream<AgentEvent, PortFailure>, api: FeishuApi, target: FeishuTarget, formatError: (failed: FeishuFailure) => string | undefined, initialPreview?: MountedFeishuPreview, label?: string, onAnswered?: (answer: string) => void): Effect.Effect<void, PortFailure, import("effect/Scope").Scope>;