@fastagent-sh/fastagent 0.13.0 → 0.14.0

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

@@ -6,11 +6,10 @@
  * half touches the Open API + disk; split from feishu.ts so the factory keeps only wiring and the
  * per-turn lifecycle.
  *
- * Everything here is PRIMARY input — the summoning message's own attachments and the message the user
- * explicitly replied to — so any load failure THROWS and the caller sees a `failed` event: the agent
- * never runs on inputs the user pointed at but we failed to load. (The telegram channel's second,
- * degrade-per-attachment tier is its context BUFFER — background material; Feishu grows that tier only
- * with the buffer itself, which needs the sensitive all-group-messages scope.)
+ * 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";
@@ -21,16 +20,17 @@ import { codePointPrefix } from "./text.js";
 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). Throws on any failure — primary inputs, no silent drops.
+ * (vision) and file (disk). Primary failures throw; buffered resources degrade independently.
  */
 async function resolveTurnInputs(t, attachments) {
-    const images = [...attachments.images];
-    const files = [...attachments.files];
+    const images = [...attachments.primary.images];
+    const files = [...attachments.primary.files];
     let referentBlock = "";
-    if (attachments.parentId !== undefined) {
-        const parent = await t.api.getMessage(attachments.parentId);
+    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 ${attachments.parentId} is not readable`);
+            throw new Error(`replied-to message ${parentId} is not readable`);
         const parsed = parseContent({
             message_type: parent.msg_type ?? "unknown",
             content: parent.body?.content ?? "",
@@ -38,33 +38,84 @@ async function resolveTurnInputs(t, attachments) {
         });
         // 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: attachments.parentId, key });
+            images.push({ msg: parentId, key });
         for (const ref of parsed.fileRefs)
-            files.push({ msg: attachments.parentId, key: ref.key, name: ref.name });
+            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 ${attachments.parentId}${from ? `, from ${from}` : ""}): ${codePointPrefix(parsed.text, 560) || "(empty)"}]`;
+        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));
-    const manifest = downloaded.length
-        ? `\n\n[attached files — read them with your tools:\n${downloaded.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
+    // 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]`
         : "";
-    return { images: imageRefs.length ? imageRefs : undefined, promptSuffix: `${referentBlock}${manifest}` };
+    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. An input failure surfaces as a `failed`
- * event (never a silent drop). `onCompleted` (if given) fires on the turn's `completed` event — the
+ * 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.
  *

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

@@ -1,124 +1,42 @@
 /**
- * Canonical Feishu protocol parsing — PURE: event field extraction, message-content decoding, prompt
- * envelope, and summon/route policy. Lark compatibility events reuse these wire shapes. Feishu
- * messages carry their payload as a JSON-ENCODED STRING in `content`, shaped by `message_type`
- * (text / post / image / file / audio / media / …). {@link parseContent} is the single decoder: it
- * yields the readable text (mention placeholders restored), the vision image keys, and the downloadable
- * file refs — the envelope, the turn record, and the parent-message resolution all read through it.
+ * 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";
-/** One entry of a message's `mentions` array: the platform's parsed @-mention (the `key` is the
- *  placeholder in the text content, e.g. `@_user_1`). */
-export interface FeishuMention {
-    key: string;
-    id?: {
-        open_id?: string;
-        user_id?: string;
-        union_id?: string;
-    };
-    name?: string;
-    [k: string]: unknown;
-}
-/** A received message (the `im.message.receive_v1` event's `message`, common subset; `[k]` keeps the
- *  rest reachable without a types dependency). */
-export interface FeishuMessage {
-    message_id: string;
-    /** The replied-to message, when this message is a reply. Content is NOT included — the channel
-     *  fetches it via the API (the IO half, invoke-turn.ts). */
-    parent_id?: string;
-    root_id?: string;
-    chat_id: string;
-    /** Present in topic groups — reply into the same topic to stay threaded. */
-    thread_id?: string;
-    chat_type: string;
-    message_type: string;
-    /** JSON-encoded string, shaped by message_type — decode with {@link parseContent}. */
-    content: string;
-    mentions?: FeishuMention[];
-    [k: string]: unknown;
-}
-export interface FeishuSender {
-    sender_id?: {
-        open_id?: string;
-        user_id?: string;
-        union_id?: string;
-    };
-    /** "user" for humans; apps/bots have other values — the default route ignores those (anti-loop). */
-    sender_type?: string;
-    [k: string]: unknown;
-}
-/** The `im.message.receive_v1` event body (`event` of the v2.0 envelope). */
-export interface FeishuMessageEvent {
-    sender?: FeishuSender;
-    message?: FeishuMessage;
-    [k: string]: unknown;
-}
-/** What `route` returns: act with these (every field optional — omitted ones default from the message),
- *  or null to ignore. */
-export interface FeishuRoute {
-    /** Conversation identity (default: `chat` or `chat:thread`). */
-    session?: string;
-    /** Reply target chat (default: the message's chat). */
-    chatId?: string;
-    /** Base prompt (default: {@link feishuEnvelope}); the channel still appends attachments. */
-    text?: string;
-}
-/** A downloadable attachment reference: the resource key inside its carrying message (the resource API
- *  addresses a file by message_id + key). */
+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;
 }
-/** A message's decoded payload — see the module header. */
 export interface ParsedFeishuContent {
-    /** Readable text: the text/post body with mention placeholders restored to `@Name`; marker lines
-     *  (`[image]`, `[file: …]`) for non-text payloads, so a media-only message is never blank. */
     text: string;
-    /** Vision images: `image_key`s from an image message or a post's inline images. */
     imageKeys: string[];
-    /** Files to download to disk (file / audio / media). */
     fileRefs: FeishuAttachmentRef[];
 }
 /**
- * Decode a message's `content` by its `message_type` — the single decoder (module header). Unknown or
- * malformed content degrades to a visible marker (`[sticker message]`), never a throw: the payload is
- * external input, and a message the agent cannot read should still say WHAT it couldn't read.
+ * 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(m: Pick<FeishuMessage, "message_type" | "content" | "mentions">): ParsedFeishuContent;
-/** A stable sender label for attribution. The receive event carries only ids (a display name needs a
- *  contacts-API scope), so the label is the open_id — stable across turns, which is what a shared
- *  multi-user session needs to tell participants apart. */
+export 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 default session key. */
-export declare function placeKey(m: Pick<FeishuMessage, "chat_id" | "thread_id">): string;
-/**
- * The default base prompt: a context envelope (chat/thread/sender + a group note + a reply marker),
- * then the message's decoded body. The sender is named on every message and a group chat is flagged —
- * in a shared multi-user session that is how the model tells participants apart and knows it is not a
- * 1:1. A reply carries only `[in reply to msg …]` here: the referent's CONTENT is not in the event, so
- * the channel fetches and appends it in the IO half (invoke-turn.ts), keeping this layer pure. Exported
- * so a custom Feishu `route` can reuse it, e.g. `text: `${feishuEnvelope(event)}\n\n[extra]``. The
- * internal compatibility seam binds the same shape to `[lark: …]`; each kind's send tool reads the
- * chat id from its own branded line.
- */
+/** 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;
 /**
- * Whether the message @mentions the bot — read from the `mentions` array the platform already parsed
- * (never a regex over the text: a pasted `@bot` in a code block is not a mention entry), matched on the
- * bot's open_id (stable identity; names are mutable). No id → fail closed (false): answering "is this
- * mention me?" with "I don't know who I am, so yes" would mis-summon in every multi-bot group.
- */
-export declare function mentionsBot(m: Pick<FeishuMessage, "mentions">, botOpenId: string | undefined): boolean;
-/**
- * The default routing policy (used when `route` is omitted; exported so a custom route can reuse it):
- * answer humans only (a non-`user` sender is another bot/app — two bots answering each other loop
- * forever), p2p chats always, a group only on an @mention of THIS bot (matched by open_id, which
- * feishuChannel resolves via bot/v3/info). NOTE the platform side of the same coin: with the default
- * `im:message.group_at_msg` scope, un-mentioned group messages are never even delivered — receiving
- * everything needs the sensitive `im:message.group_msg` scope. Returns `{}` (act; the channel fills
- * session/target/prompt from the message) or `null` (ignore).
+ * 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;