@fastagent-sh/fastagent 0.17.0 → 0.18.0

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

@@ -1,18 +1,136 @@
 import { log } from "../../log.js";
 import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
+import { BUFFER_ATTACH_MAX } from "../context-buffer.js";
 import { parseContent } from "./parse.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.)";
+/** The per-turn REPLY CONTRACT, appended to the prompt (not the system prompt). Two halves, one
+ *  concept — what happens to the reply: its FORMAT (rendered in a card whose markdown element is the
+ *  natural fit for LLM output — steer away from HTML/plain) and its DELIVERY OWNERSHIP (the channel
+ *  itself delivers it; answering through a send TOOL instead is the observed failure — the channel
+ *  then settles an empty turn as "(no reply)" next to the tool's un-threaded duplicate). */
+const REPLY_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card. This reply is " +
+    "delivered to the current chat by the channel itself: do not call a send tool to answer the " +
+    "current chat.)";
+/** How far up a reply chain the walk reads, beyond the replied-to message itself. The chain's natural
+ *  end is its ROOT — the platform threads every reply back to one — so this is an IO guard, not a
+ *  semantic boundary: each ancestor costs one serial `getMessage`, and a pathological chain must not
+ *  stall the turn. Field chains are 1–3 long; a capped walk says so in the block. */
+const MAX_CHAIN_ANCESTORS = 8;
+/** Attribution for a FETCHED message. 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.
+ *
+ *  OWN means THIS app, not "an app". A group can hold several bots, and `sender_type === "app"` is
+ *  true for every one of them — matching on it alone would tell the model it wrote another bot's
+ *  message. The identity to compare is the app id, because an app sender carries `id_type: "app_id"`:
+ *  the cached bot open_id answers a different question (who was @mentioned) and would never match
+ *  here. A missing or unexpected id fails CLOSED — labelled by id, never claimed as the agent's own.
+ *  And an app is not a person: labelling another bot's message "user cli_…" is the same
+ *  misattribution in a quieter form, so the noun follows the sender type. */
+function fetchedSenderLabel(sender, appId) {
+    const appSender = sender?.sender_type === "app";
+    const senderId = sender?.id;
+    if (appSender && senderId === appId)
+        return "you, the agent";
+    return senderId ? `${appSender ? "app" : "user"} ${senderId}` : undefined;
+}
+/**
+ * Walk the reply chain ABOVE the replied-to message, to its root. Quoting a reply points at one link
+ * of an exchange; the pointer is only fully resolved when the model can read what that link was
+ * replying to — all the way up, because the platform defines where the chain ends (its root), which
+ * 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
+ * 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
+ * — the walk costs at most one more referent — while the pointed-at referent keeps its own full
+ * fidelity bound.
+ *
+ * Fail-open at every edge, but never silently at the model: any walk that ends short of the root —
+ * the ancestor cap, an exhausted text budget, an unreadable ancestor, a cycle — leaves the same
+ * neutral truncation line at the top of the block, because a chain rendered without it READS as
+ * complete and the model would take the oldest fetched node for the original ask. Unreadable
+ * ancestors and cycles also warn the operator; a cycle is corrupt platform data (reply chains are
+ * temporally acyclic by construction — a reply can only point at an EARLIER message — so one firing
+ * means the data, not the walk, is wrong).
+ */
+async function walkReplyChain(t, start, visited) {
+    const nodes = [];
+    const images = [];
+    const files = [];
+    // No parent above the referent = no chain — not a truncated one. The marker below is only for
+    // walks that END SHORT of a root that exists.
+    if (start === undefined)
+        return { block: "", images, files, ids: [] };
+    let reachedRoot = false;
+    let textBudget = REFERENT_MAX_CODE_POINTS;
+    let next = start;
+    while (next !== undefined) {
+        if (visited.has(next)) {
+            log.warn(`${t.label} reply chain points back to already-visited message ${next} — corrupt platform data; the walk ends here`);
+            break;
+        }
+        if (nodes.length >= MAX_CHAIN_ANCESTORS || textBudget <= 0)
+            break;
+        // The annotation breaks a control-flow-analysis cycle (id → msg → next → id) that trips TS7022.
+        const id = next;
+        visited.add(id);
+        let failure;
+        const msg = await t.api.getMessage(id).catch((error) => {
+            failure = String(error);
+            return undefined;
+        });
+        if (!msg) {
+            log.warn(`${t.label} could not read reply-chain message ${id} (${failure ?? "no such message"}) — the chain is rendered up to it`);
+            break;
+        }
+        const parsed = parseContent({
+            message_type: msg.msg_type ?? "unknown",
+            content: msg.body?.content ?? "",
+            mentions: msg.mentions,
+        });
+        const label = fetchedSenderLabel(msg.sender, t.appId);
+        const from = label ?? "reply chain";
+        for (const key of parsed.imageKeys)
+            images.push({ messageId: id, key, from });
+        for (const ref of parsed.fileRefs)
+            files.push({ messageId: id, key: ref.key, name: ref.name, from });
+        const text = truncateCodePointPrefix(parsed.text, textBudget) || "(empty)";
+        textBudget -= [...text].length;
+        nodes.push({ id, label, text });
+        if (msg.parent_id === undefined)
+            reachedRoot = true;
+        next = msg.parent_id;
+    }
+    nodes.reverse(); // fetched leaf→root; rendered oldest first, the way a transcript reads
+    const lines = nodes.map((node) => `(msg ${node.id}${node.label ? `, from ${node.label}` : ""}): ${node.text}`);
+    // One line for every way of ending short of the root — cap, budget, unreadable, cycle. It names no
+    // cause on purpose: the model needs the SHAPE (there is more above), the operator log has the why.
+    if (!reachedRoot)
+        lines.unshift("(…the chain continues above this point)");
+    return {
+        block: `\n[reply chain above it, oldest first:\n${lines.join("\n")}]`,
+        images,
+        files,
+        // Walked (fetched) order = nearest first — nodes were reversed for RENDERING above, so read the
+        // hint order off the rendered list backwards.
+        ids: nodes.map((node) => node.id).reverse(),
+    };
+}
 /**
- * Resolve a turn's inputs (module header): fetch the reply referent's content, then load every image
- * (vision) and file (disk). Primary failures throw; buffered resources degrade independently.
+ * Resolve a turn's inputs (module header): fetch the reply referent's content and resolve its reply
+ * chain, then load every image (vision) and file (disk). Primary failures throw; buffered resources
+ * degrade independently.
  */
 async function resolveTurnInputs(t, attachments) {
     const images = [...attachments.primary.images];
     const files = [...attachments.primary.files];
     let referentBlock = "";
+    let chain = { block: "", images: [], files: [], ids: [] };
     if (attachments.primary.parentId !== undefined) {
         const parentId = attachments.primary.parentId;
         // A referent is CONTEXT, not the ask. Losing it (deleted, restricted, unreadable) must not cost
@@ -44,11 +162,11 @@ async function resolveTurnInputs(t, attachments) {
                 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;
+            const from = fetchedSenderLabel(parent.sender, t.appId);
             referentBlock = `\n\n[replied-to message (msg ${parentId}${from ? `, from ${from}` : ""}): ${truncateCodePointPrefix(parsed.text, REFERENT_MAX_CODE_POINTS) || "(empty)"}]`;
+            // The referent's own parent starts the chain walk; the referent id seeds the cycle guard.
+            chain = await walkReplyChain(t, parent.parent_id, new Set([parentId]));
+            referentBlock += chain.block;
         }
     }
     // Primary first and fail-fast: these are resources the current user explicitly pointed at.
@@ -62,8 +180,28 @@ async function resolveTurnInputs(t, attachments) {
     // downloaded twice or rendered twice in the manifest.
     const primaryImages = new Set(images.map((ref) => `${ref.msg}\u0000${ref.key}`));
     const primaryFiles = new Set(files.map((ref) => `${ref.msg}\u0000${ref.key}`));
-    const bufferedImages = attachments.buffered.images.filter((ref) => !primaryImages.has(`${ref.messageId}\u0000${ref.key}`));
-    const bufferedFiles = attachments.buffered.files.filter((ref) => !primaryFiles.has(`${ref.messageId}\u0000${ref.key}`));
+    // Chain ancestors and the context buffer share ONE background budget: BUFFER_ATTACH_MAX per kind.
+    // The cap is part of the tier's meaning, not an accident of who collected the ref — a rich-text
+    // ancestor must not turn the walk into an unbounded fan-out of downloads. Chain refs take slots
+    // FIRST: they are the direct upstream of the message the user pointed at, buffer refs are ambient
+    // discussion. Duplicates (a chain that points back into still-buffered discussion) count once, and
+    // what the cap drops is counted into the missing-attachments note like every other unloaded ref.
+    const capMerge = (chainRefs, bufferRefs, primary) => {
+        const seen = new Set();
+        const merged = [];
+        for (const ref of [...chainRefs, ...bufferRefs]) {
+            const identity = `${ref.messageId}\u0000${ref.key}`;
+            if (primary.has(identity) || seen.has(identity))
+                continue;
+            seen.add(identity);
+            merged.push(ref);
+        }
+        return { kept: merged.slice(0, BUFFER_ATTACH_MAX), dropped: Math.max(0, merged.length - BUFFER_ATTACH_MAX) };
+    };
+    const mergedImages = capMerge(chain.images, attachments.buffered.images, primaryImages);
+    const mergedFiles = capMerge(chain.files, attachments.buffered.files, primaryFiles);
+    const bufferedImages = mergedImages.kept;
+    const bufferedFiles = mergedFiles.kept;
     const backgroundImages = [];
     const backgroundFiles = [];
     let lost = 0;
@@ -88,7 +226,7 @@ async function resolveTurnInputs(t, attachments) {
             log.warn(`${t.label} could not load an earlier (buffered) attachment: ${String(result.reason)}`);
         }
     }
-    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped);
+    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped + mergedImages.dropped + mergedFiles.dropped);
     const backgroundImageManifest = backgroundImagesManifest(imageRefs.length, backgroundImages.map(({ ref }) => ref));
     const allFiles = [
         ...downloaded,
@@ -101,6 +239,7 @@ async function resolveTurnInputs(t, attachments) {
     return {
         images: allImages.length ? allImages : undefined,
         promptSuffix: `${referentBlock}${missingNote}${backgroundImageManifest}${attachedFilesManifest(allFiles)}`,
+        referentIds: [...(attachments.primary.parentId !== undefined ? [attachments.primary.parentId] : []), ...chain.ids],
     };
 }
 /**
@@ -117,6 +256,12 @@ export async function* invokeFeishuTurn(agent, session, text, transport, attachm
         yield { type: "failed", details: `could not load attachment: ${String(e)}`, retryable: true };
         return;
     }
-    const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
-    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
+    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 });
 }

package/dist/channels/feishu/normalize.js

@@ -1,3 +1,62 @@
+/**
+ * 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.
+ */
+function renderNodes(nodes, resources) {
+    if (!Array.isArray(nodes))
+        return "";
+    const parts = [];
+    for (const raw of nodes) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const node = raw;
+        if (node.tag === "at") {
+            parts.push(`@${nonEmptyString(node.user_name) ?? nonEmptyString(node.user_id) ?? "user"}`);
+        }
+        else if (node.tag === "a") {
+            parts.push(node.href ? `${nonEmptyString(node.text) ?? node.href} (${node.href})` : (node.text ?? ""));
+        }
+        else if (node.tag === "img") {
+            const key = nonEmptyString(node.image_key);
+            if (key)
+                resources?.push({ kind: "image", key });
+            parts.push("[image]");
+        }
+        else if (node.tag === "media") {
+            const key = nonEmptyString(node.file_key);
+            if (key)
+                resources?.push({ kind: "video", key, name: nonEmptyString(node.file_name) });
+            parts.push("[video]");
+        }
+        else if (node.tag === "code_block") {
+            parts.push(`\n\`\`\`${nonEmptyString(node.language)?.toLowerCase() ?? ""}\n${nonEmptyString(node.text) ?? ""}\n\`\`\`\n`);
+        }
+        else if (node.tag === "note") {
+            const nested = renderNodes(node.elements, resources);
+            if (nested)
+                parts.push(nested);
+        }
+        else if (nonEmptyString(node.text)) {
+            parts.push(node.text);
+        }
+        else if (nonEmptyString(node.placeholder)) {
+            parts.push(node.placeholder);
+        }
+    }
+    return parts.join("").trim();
+}
 function nonEmptyString(value) {
     return typeof value === "string" && value !== "" ? value : undefined;
 }
@@ -37,43 +96,49 @@ export function decodeFeishuContent(message) {
                 lines.push(title);
             const paragraphs = Array.isArray(content.content) ? content.content : [];
             for (const paragraph of paragraphs) {
-                if (!Array.isArray(paragraph))
-                    continue;
-                const parts = [];
-                for (const node of paragraph) {
-                    if (typeof node !== "object" || node === null)
-                        continue;
-                    if (node.tag === "at") {
-                        parts.push(`@${nonEmptyString(node.user_name) ?? nonEmptyString(node.user_id) ?? "user"}`);
-                    }
-                    else if (node.tag === "a") {
-                        parts.push(node.href ? `${nonEmptyString(node.text) ?? node.href} (${node.href})` : (node.text ?? ""));
-                    }
-                    else if (node.tag === "img") {
-                        const key = nonEmptyString(node.image_key);
-                        if (key)
-                            resources.push({ kind: "image", key });
-                        parts.push("[image]");
-                    }
-                    else if (node.tag === "media") {
-                        const key = nonEmptyString(node.file_key);
-                        if (key)
-                            resources.push({ kind: "video", key, name: nonEmptyString(node.file_name) });
-                        parts.push("[video]");
-                    }
-                    else if (node.tag === "code_block") {
-                        parts.push(`\n\`\`\`${nonEmptyString(node.language)?.toLowerCase() ?? ""}\n${nonEmptyString(node.text) ?? ""}\n\`\`\`\n`);
-                    }
-                    else if (nonEmptyString(node.text)) {
-                        parts.push(node.text);
-                    }
-                }
-                const line = parts.join("").trim();
+                const line = renderNodes(paragraph, resources);
                 if (line)
                     lines.push(line);
             }
             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.
+        case "interactive":
+        case "card": {
+            const lines = [];
+            const title = nonEmptyString(content.title);
+            if (title)
+                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.
+                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".
+            return { text: lines.length > 0 ? lines.join("\n") : `[${rawType} message]`, resources };
+        }
         case "image": {
             const key = nonEmptyString(content.image_key);
             if (key)

package/dist/channels/feishu/parse.js

@@ -52,6 +52,12 @@ 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 — sessions.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.
+        `msg ${message.message_id}`,
     ]
         .filter(Boolean)
         .join(", ");

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

@@ -15,9 +15,10 @@ export type MountedFeishuPreview = {
     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.
+ * 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.
  */
 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).

package/dist/channels/feishu/preview.js

@@ -1,8 +1,10 @@
 /**
  * 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
+ * streaming CARD of TWO elements — the volatile `process` block and the append-only `answer` (see
+ * card.ts for why the split is the prefix-stability fix) — (create entity → mount it with a
+ * reply/send → stream full-text snapshots per 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 alone (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.
@@ -21,10 +23,10 @@
  */
 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 { ANSWER_ELEMENT_ID, CARD_MARKDOWN_MAX_BYTES, PROCESS_ELEMENT_ID, cardEntityContent, finalCardJson, streamingCardJson, } from "./card.js";
 import { chunkFeishuText, isCardStreamingClosed } from "./feishu-api.js";
 import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../preview-kit.js";
-import { truncateUtf8 } from "../text.js";
+import { truncateCodePointPrefix, 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
@@ -33,12 +35,41 @@ export { defaultErrorMessage };
 const STREAM_THROTTLE_MS = 1000;
 /** How much of the (growing) reasoning to peek at in the live view — the most recent tail. */
 const THINKING_PREVIEW = 280;
-/** 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. */
+/** Cap (code points) on the whole process block — thinking tail + tool lines + retry notice. It
+ *  redraws wholly on change anyway (it is volatile by nature), so over budget the newest COMPLETE
+ *  lines win (see tailLines). ≤1000 points is ≤4 KB UTF-8, which together with the answer's byte cap
+ *  stays inside the 30 KB entity budget. */
+const PROCESS_MAX_POINTS = 1000;
+/** Cap the live answer 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 answer freezes at its head rather than sliding a
+ *  tail window (which would re-type the element every frame). The full answer still lands at settle. */
 function capBytes(s, maxBytes) {
     return truncateUtf8(s, maxBytes);
 }
+/** Tail-select COMPLETE lines within a code-point budget — the process block's cap. The block's
+ *  lines are semantic units (a `🔧` tool call, the `💭` peek, the `⏳` notice): cutting mid-line
+ *  would orphan a marker or tear a label, so elision happens only at line boundaries, newest lines
+ *  kept, with a leading `…` line marking what was dropped. The in-line guard cannot trigger with the
+ *  bounded renderers (a thinking tail ≤ ~283 points, a tool line ≤ ~135) — it exists so a future
+ *  unbounded line degrades to a head-preserving cut instead of an empty block. */
+function tailLines(text, maxPoints) {
+    if (Array.from(text).length <= maxPoints)
+        return text;
+    const lines = text.split("\n");
+    const kept = [];
+    let used = 2; // the leading "…\n" elision marker
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i] ?? "";
+        const cost = Array.from(line).length + (kept.length > 0 ? 1 : 0); // +1 joining newline
+        if (used + cost > maxPoints)
+            break;
+        used += cost;
+        kept.unshift(line);
+    }
+    if (kept.length === 0)
+        return truncateCodePointPrefix(lines.at(-1) ?? "", maxPoints);
+    return `…\n${kept.join("\n")}`;
+}
 /**
  * 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
@@ -90,9 +121,10 @@ async function finalize(api, target, preview, text, seq) {
     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.
+ * 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.
  */
 export async function mountFeishuPreview(api, target, initial, label = "[feishu]") {
     try {
@@ -151,17 +183,27 @@ export async function settleFeishuPreview(api, target, preview, text) {
  */
 export async function streamFeishuReply(events, api, target, formatError, initialPreview, label = "[feishu]") {
     // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal
-    // policy, the card-budget cap, and delivery below.
+    // policy, the card-budget caps, and delivery below. The card is TWO elements (card.ts): the process
+    // block's head changes every frame (sliding thinking tail, `…`→`✓` flips), so it must never share
+    // an element with the answer — the client would re-type the whole card from the divergence point
+    // once a second. Each view feeds its own element; only the changed one is written.
     const turn = createTurnView();
-    const view = () => {
+    const processView = () => {
         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);
+        if (v !== "")
+            return tailLines(v, PROCESS_MAX_POINTS);
+        // No process content: the placeholder covers only the silence BEFORE the answer reveals — once
+        // the answer is streaming, an empty block goes (stays) empty; "Thinking…" pinned above a live
+        // answer would misstate the phase. The empty frame is a real write: it clears a mounted
+        // placeholder. (The block cannot otherwise flicker: thinking and tools only grow — only the
+        // retry notice toggles, and its empty state resolves through this same rule.)
+        return revealedAnswer(turn, STREAM_THROTTLE_MS).trim() === "" ? THINKING_PLACEHOLDER : "";
     };
+    const answerView = () => capBytes(revealedAnswer(turn, STREAM_THROTTLE_MS), 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
@@ -172,22 +214,34 @@ export async function streamFeishuReply(events, api, target, formatError, initia
     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 = "";
+    let lastProcess = "";
+    let lastAnswer = "";
     const flushPreview = async () => {
-        const text = view();
+        const process = processView();
         if (!setupAttempted) {
             setupAttempted = true;
-            preview = await mountFeishuPreview(api, target, text, label);
-            lastSent = text;
+            // The mount seeds the process element with the current view; the answer element starts empty
+            // (card.ts), so the first answer snapshot is a clean prefix extension.
+            preview = await mountFeishuPreview(api, target, process, label);
+            lastProcess = process;
             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());
+            // `last*` advances BEFORE each write: a frame that fails for a non-streaming reason is logged
+            // once (the pump's onError) and not re-sent until its content actually changes. An EMPTY
+            // process frame is written like any other — it is the placeholder being cleared (processView).
+            if (process !== lastProcess) {
+                lastProcess = process;
+                await api.updateCardElement(preview.cardId, PROCESS_ELEMENT_ID, process, nextSeq());
+            }
+            const answer = answerView();
+            // Never write an empty answer snapshot — the element is born empty and the answer only grows.
+            if (answer !== "" && answer !== lastAnswer) {
+                lastAnswer = answer;
+                await api.updateCardElement(preview.cardId, ANSWER_ELEMENT_ID, answer, nextSeq());
+            }
         }
         catch (e) {
             if (isCardStreamingClosed(e)) {

package/dist/channels/feishu/scaffold/feishu-send.ts

@@ -56,12 +56,15 @@ async function tenantToken(): Promise<string> {
 
 export default defineTool({
   description:
-    "Send a message to a Feishu chat: plain `text`, or `markdown` (rendered as a card — headings, " +
-    "bold, code blocks, links). Exactly one of the two. Use it for a turn NO channel is carrying — a " +
-    "scheduled or self-scheduled (wake) turn — or to reach a chat OTHER than the one you are " +
-    "answering. In a normal chat turn the channel already delivers your reply, so do NOT call this to " +
-    "answer (it would post the message twice). chatId comes from the [feishu: chat …] context line in a " +
-    "chat turn; a scheduled/woken turn has no context line, so name the destination in your instruction.",
+    "Send a message to a Feishu chat, OUTSIDE the normal reply path. Call it only for a turn NO " +
+    "channel is carrying — a scheduled or self-scheduled (wake) turn, whose plain reply goes " +
+    "nowhere — or to reach a chat OTHER than the one you are answering. In a normal chat turn the " +
+    "channel streams and delivers your reply itself, so do NOT call this to answer the current " +
+    "chat: it would post the message twice, outside the conversation thread. `chatId` (oc_…) names " +
+    "the DESTINATION and must come from your instructions (the asking message, the schedule prompt, " +
+    "or memory); the [feishu: chat …] context line only identifies the chat you are answering — the " +
+    "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
+    "`markdown` (rendered as a card: headings, bold, code blocks, links).",
   input: z.object({
     chatId: z.string().describe("target chat id (oc_…)"),
     text: z.string().optional().describe("plain text message to send"),

package/dist/channels/http.js

@@ -56,14 +56,27 @@ export function createInvokeHandler(agent) {
         catch {
             return text("invalid json\n", 400);
         }
-        const { session, text: promptText } = (payload ?? {});
+        const { session, text: promptText, parentSession, branchHints, } = (payload ?? {});
         if (typeof session !== "string" || typeof promptText !== "string") {
             return text('need { "session": string, "text": string }\n', 400);
         }
         // ^ the request shape INVOKE_EXAMPLE_BODY (below) must keep satisfying.
+        // The OPTIONAL lineage extension (Scope): malformed values are a 400, not a silent drop — a
+        // caller that sent them meant them.
+        if (parentSession !== undefined && typeof parentSession !== "string") {
+            return text('"parentSession" must be a string\n', 400);
+        }
+        if (branchHints !== undefined && !(Array.isArray(branchHints) && branchHints.every((h) => typeof h === "string"))) {
+            return text('"branchHints" must be an array of strings\n', 400);
+        }
         // Take the iterator explicitly so the stream's cancel() (consumer disconnect) can return() it and
         // run invoke's cancellation cleanup (SPEC MUST 3). pull = backpressure: the next event is produced on demand.
-        const iterator = agent.invoke({ session }, { text: promptText })[Symbol.asyncIterator]();
+        const iterator = agent
+            .invoke({
+            session,
+            ...(parentSession !== undefined ? { parentSession } : {}),
+            ...(branchHints !== undefined ? { branchHints } : {}),
+        }, { text: promptText })[Symbol.asyncIterator]();
         // Heartbeats: a QUIET stream (a long tool call, no events) is normal here — remote consumers
         // distinguish "quiet but alive" from a dead connection by byte arrival, so silence must not
         // look identical to a black hole (SSE comments are ignored by spec-conforming parsers).

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

@@ -10,7 +10,7 @@
  * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
  * message-scoped Feishu keys, Slack file objects) are real differences.
  */
-import { type Agent, type AgentEvent, type Prompt } from "../agent.ts";
+import { type Agent, type AgentEvent, type Prompt, type Scope } from "../agent.ts";
 /** 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
@@ -35,7 +35,10 @@ export declare const DEFAULT_BUSY_RETRY: BusyRetry;
  * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
  * is ever re-run.
  */
-export declare function streamTurnWithBusyRetry(agent: Agent, session: string, prompt: Prompt, options: {
+export declare function streamTurnWithBusyRetry(agent: Agent, 
+/** The full scope, not a session string — channels that set extension fields (lineage) pass them
+ *  through here; channels that don't pass `{ session }` and nothing changes. */
+scope: Scope, prompt: Prompt, options: {
     label: string;
     onCompleted?: () => void;
     busyRetry?: BusyRetry;