@fastagent-sh/fastagent 0.12.1 → 0.14.0

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

@@ -0,0 +1,157 @@
+/**
+ * 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 { parseContent } from "./parse.js";
+import { codePointPrefix } from "./text.js";
+/** Appended to the prompt (not the system prompt): the channel renders the reply in a card, and the
+ *  card's markdown element is the natural fit for LLM output — steer away from HTML/plain. */
+const MARKDOWN_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card.)";
+/**
+ * Resolve a turn's inputs (module header): fetch the reply referent's content, then load every image
+ * (vision) and file (disk). Primary failures throw; buffered resources degrade independently.
+ */
+async function resolveTurnInputs(t, attachments) {
+    const images = [...attachments.primary.images];
+    const files = [...attachments.primary.files];
+    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,
+        });
+        // 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)"}]`;
+    }
+    // Primary first and fail-fast: these are resources the current user explicitly pointed at.
+    const imageRefs = [];
+    for (const ref of images)
+        imageRefs.push(await t.api.fetchImage(ref.msg, ref.key));
+    const downloaded = [];
+    for (const ref of files)
+        downloaded.push(await t.api.fetchFile(ref.msg, ref.key, ref.name ?? ref.key, t.chatId, t.filesDir));
+    // A replied-to buffered message is now primary. Filter by message-scoped identity so it is not
+    // 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}`));
+    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 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 allFiles = [
+        ...downloaded,
+        ...backgroundFiles.map(({ file, ref }) => ({
+            ...file,
+            name: `${file.name} (from ${ref.from}, msg ${ref.messageId}, earlier discussion)`,
+        })),
+    ];
+    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}`,
+    };
+}
+// 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.
+ */
+export async function* invokeFeishuTurn(agent, session, text, transport, attachments, onCompleted, busyRetry = DEFAULT_BUSY_RETRY) {
+    let resolved;
+    try {
+        resolved = await resolveTurnInputs(transport, attachments);
+    }
+    catch (e) {
+        yield { type: "failed", details: `could not load attachment: ${String(e)}`, retryable: true };
+        return;
+    }
+    const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
+    const deadline = Date.now() + busyRetry.maxWaitMs;
+    for (;;) {
+        let retryBusy = false;
+        let first = true;
+        for await (const e of agent.invoke({ session }, prompt)) {
+            if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
+                retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
+                break;
+            }
+            first = false;
+            if (e.type === "completed")
+                onCompleted?.(); // the turn is durably in the session — commit point
+            yield e;
+        }
+        if (!retryBusy)
+            return;
+        log.info(`${transport.label} session ${session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
+        await new Promise((r) => setTimeout(r, busyRetry.delayMs));
+    }
+}

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

@@ -0,0 +1,97 @@
+/**
+ * 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. */
+export interface FeishuEventHeader {
+    event_id?: string;
+    event_type?: string;
+    create_time?: string;
+    token?: string;
+    app_id?: string;
+    tenant_key?: string;
+    [k: string]: unknown;
+}
+/** One entry of a message's `mentions` array. `key` is the placeholder carried in text content. */
+export interface FeishuMention {
+    key: string;
+    id?: {
+        open_id?: string;
+        user_id?: string;
+        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`. */
+export interface FeishuMessage {
+    message_id: string;
+    root_id?: string;
+    parent_id?: string;
+    create_time?: string;
+    update_time?: string;
+    chat_id: string;
+    thread_id?: string;
+    chat_type: string;
+    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 {
+    sender_id?: {
+        open_id?: string;
+        user_id?: string;
+        union_id?: string;
+    };
+    sender_type?: string;
+    tenant_key?: string;
+    [k: string]: unknown;
+}
+/** The `event` member of a v2 `im.message.receive_v1` envelope. */
+export interface FeishuMessageEvent {
+    sender?: FeishuSender;
+    message?: FeishuMessage;
+    [k: string]: unknown;
+}
+/** Existing public route result: act with these overrides, or return null to ignore the message. */
+export interface FeishuRoute {
+    session?: string;
+    chatId?: string;
+    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.
+ */
+export interface FeishuResourceRef {
+    kind: FeishuResourceKind;
+    messageId: string;
+    key: string;
+    name?: string;
+}
+/** Narrow internal representation shared by the Feishu reference and Lark compatibility clouds. */
+export interface NormalizedFeishuMessage {
+    conversation: {
+        chatId: string;
+        threadId?: string;
+        rootId?: string;
+    };
+    content: {
+        text: string;
+        hasMentions: boolean;
+        resources: FeishuResourceRef[];
+    };
+}

package/dist/channels/feishu/model.js

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export {};

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

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+import type { FeishuMessage, FeishuMessageEvent, FeishuResourceKind, NormalizedFeishuMessage } from "./model.ts";
+export interface DecodedFeishuResource {
+    kind: FeishuResourceKind;
+    key: string;
+    name?: string;
+}
+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.
+ */
+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;

package/dist/channels/feishu/normalize.js

@@ -0,0 +1,132 @@
+function nonEmptyString(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/** Restore text-message mention placeholders to readable names. */
+function restoreMentions(text, mentions) {
+    let out = text;
+    for (const mention of mentions ?? []) {
+        if (!mention.key)
+            continue;
+        out = out.split(mention.key).join(`@${mention.name ?? "user"}`);
+    }
+    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.
+ */
+export function decodeFeishuContent(message) {
+    const rawType = typeof message.message_type === "string" ? message.message_type : "unknown";
+    let content;
+    try {
+        content = JSON.parse(message.content);
+        if (typeof content !== "object" || content === null)
+            throw new Error("not an object");
+    }
+    catch {
+        return { text: `[unreadable ${rawType} message]`, resources: [] };
+    }
+    const resources = [];
+    switch (rawType) {
+        case "text":
+            return { text: restoreMentions(nonEmptyString(content.text) ?? "", message.mentions), resources };
+        case "post": {
+            const lines = [];
+            const title = nonEmptyString(content.title);
+            if (title)
+                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();
+                if (line)
+                    lines.push(line);
+            }
+            return { text: lines.join("\n"), resources };
+        }
+        case "image": {
+            const key = nonEmptyString(content.image_key);
+            if (key)
+                resources.push({ kind: "image", key });
+            return { text: "[image]", resources };
+        }
+        case "file": {
+            const key = nonEmptyString(content.file_key);
+            const name = nonEmptyString(content.file_name);
+            if (key)
+                resources.push({ kind: "file", key, name });
+            return { text: `[file: ${name ?? "file"}]`, resources };
+        }
+        case "audio": {
+            const key = nonEmptyString(content.file_key);
+            if (key)
+                resources.push({ kind: "audio", key, name: "voice-message" });
+            return { text: "[voice message]", resources };
+        }
+        case "media": {
+            const key = nonEmptyString(content.file_key);
+            const name = nonEmptyString(content.file_name);
+            if (key)
+                resources.push({ kind: "video", key, name });
+            return { text: `[video: ${name ?? "video"}]`, resources };
+        }
+        case "location": {
+            const name = nonEmptyString(content.name);
+            return {
+                text: `[location: ${name ? `${name} — ` : ""}${nonEmptyString(content.latitude) ?? "?"},${nonEmptyString(content.longitude) ?? "?"}]`,
+                resources,
+            };
+        }
+        default:
+            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")
+        return null;
+    const decoded = decodeFeishuContent(message);
+    return {
+        conversation: {
+            chatId: message.chat_id,
+            threadId: message.thread_id,
+            rootId: message.root_id,
+        },
+        content: {
+            text: decoded.text,
+            hasMentions: (message.mentions?.length ?? 0) > 0,
+            resources: decoded.resources.map((resource) => ({ ...resource, messageId: message.message_id })),
+        },
+    };
+}

package/dist/channels/feishu/owned-threads.d.ts

@@ -0,0 +1,11 @@
+export interface OwnedFeishuThread {
+    rootId: string;
+    chatId: string;
+    createdAt: number;
+}
+export interface OwnedFeishuThreads {
+    has(chatId: string, rootId: string): boolean;
+    /** Idempotent, synchronous, pre-ACK persistence. A failed write throws so the platform redelivers. */
+    add(chatId: string, rootId: string): void;
+}
+export declare function createOwnedFeishuThreads(path: string, label: string, now?: () => number): OwnedFeishuThreads;

package/dist/channels/feishu/owned-threads.js

@@ -0,0 +1,47 @@
+/**
+ * Durable ownership index for group threads the channel created from a top-level summon. Feishu/Lark
+ * deliver an ordinary thread continuation as `thread_id + root_id`; the root is the original user
+ * message the channel reply-threaded under. Keeping that root across restarts lets the default route
+ * admit unmentioned continuations only inside Agent-managed threads, never across the whole group.
+ */
+import { log } from "../../log.js";
+import { loadStateFile, saveStateFile } from "../state.js";
+function isRecord(value) {
+    const record = value;
+    return (typeof record?.rootId === "string" &&
+        typeof record.chatId === "string" &&
+        typeof record.createdAt === "number" &&
+        Number.isFinite(record.createdAt));
+}
+export function createOwnedFeishuThreads(path, label, now = Date.now) {
+    const raw = loadStateFile(path);
+    let records = new Map();
+    if (raw !== undefined) {
+        if (typeof raw === "object" &&
+            raw !== null &&
+            !Array.isArray(raw) &&
+            Object.entries(raw).every(([rootId, record]) => isRecord(record) && record.rootId === rootId)) {
+            records = new Map(Object.entries(raw));
+        }
+        else {
+            log.warn(`${label} unexpected shape in ${path} — starting with no managed group threads`);
+        }
+    }
+    return {
+        has(chatId, rootId) {
+            const record = records.get(rootId);
+            return record?.chatId === chatId;
+        },
+        add(chatId, rootId) {
+            const existing = records.get(rootId);
+            if (existing?.chatId === chatId)
+                return;
+            const next = new Map(records);
+            next.set(rootId, { rootId, chatId, createdAt: now() });
+            // Persist the staged copy first: an IO failure must not leave memory claiming durability the file
+            // does not have. The webhook remains un-ACKed and the platform can redeliver after recovery.
+            saveStateFile(path, Object.fromEntries(next));
+            records = next;
+        },
+    };
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+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 {
+    key: string;
+    name?: string;
+}
+export interface ParsedFeishuContent {
+    text: string;
+    imageKeys: string[];
+    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.
+ */
+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;
+/** 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. */
+export declare function cloudEnvelope(event: FeishuMessageEvent, tag: FeishuCloudKind): string;
+/** 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 continuations from its managed-root index.
+ */
+export declare function defaultFeishuRoute(event: FeishuMessageEvent, options?: {
+    botOpenId?: string;
+}): FeishuRoute | null;

package/dist/channels/feishu/parse.js

@@ -0,0 +1,65 @@
+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.
+ */
+export function parseContent(message) {
+    const decoded = decodeFeishuContent(message);
+    return {
+        text: decoded.text,
+        imageKeys: decoded.resources.filter((resource) => resource.kind === "image").map((resource) => resource.key),
+        fileRefs: decoded.resources
+            .filter((resource) => resource.kind === "file" || resource.kind === "audio" || resource.kind === "video")
+            .map((resource) => ({ key: resource.key, name: resource.name })),
+    };
+}
+/** 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;
+    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;
+}
+/** The canonical Feishu-branded prompt envelope. */
+export function feishuEnvelope(event) {
+    return cloudEnvelope(event, "feishu");
+}
+/** Internal compatibility seam: bind the canonical envelope shape to one cloud's branded tag. */
+export function cloudEnvelope(event, tag) {
+    const message = event.message;
+    if (!message)
+        return "";
+    const from = senderLabel(event.sender);
+    const meta = [
+        `chat ${message.chat_id} (${message.chat_type})`,
+        message.thread_id ? `topic ${message.thread_id}` : undefined,
+        from ? `from ${from}` : undefined,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    const scope = message.chat_type === "group" ? "\n[group chat — multiple people; each message is prefixed with its sender]" : "";
+    const replyTo = message.parent_id ? `\n[in reply to msg ${message.parent_id}]` : "";
+    return `[${tag}: ${meta}]${scope}${replyTo}\n${parseContent(message).text}`;
+}
+/** Whether the parsed mention list contains this bot's app-scoped open_id. */
+export function mentionsBot(message, botOpenId) {
+    if (!botOpenId)
+        return false;
+    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 continuations from its managed-root index.
+ */
+export function defaultFeishuRoute(event, options) {
+    const message = event.message;
+    if (!message)
+        return null;
+    if (event.sender?.sender_type !== "user")
+        return null;
+    const summoned = message.chat_type === "p2p" || mentionsBot(message, options?.botOpenId);
+    return summoned ? {} : null;
+}

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

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