@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/channels/feishu/parse.js

@@ -1,175 +1,65 @@
-/** Restore the platform's mention placeholders (`@_user_1`) in a text body to readable `@Name`. */
-function restoreMentions(text, mentions) {
-    let out = text;
-    for (const m of mentions ?? []) {
-        if (!m.key)
-            continue;
-        out = out.split(m.key).join(`@${m.name ?? "user"}`);
-    }
-    return out;
-}
+import { decodeFeishuContent } from "./normalize.js";
 /**
- * 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 function parseContent(m) {
-    let c;
-    try {
-        c = JSON.parse(m.content);
-        if (typeof c !== "object" || c === null)
-            throw new Error("not an object");
-    }
-    catch {
-        return { text: `[unreadable ${m.message_type} message]`, imageKeys: [], fileRefs: [] };
-    }
-    const imageKeys = [];
-    const fileRefs = [];
-    const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
-    switch (m.message_type) {
-        case "text":
-            return { text: restoreMentions(str(c.text) ?? "", m.mentions), imageKeys, fileRefs };
-        case "post": {
-            // A post is paragraphs of typed nodes; renders as text lines with inline markers. Mentions in a
-            // post are `at` NODES (user_name inline), not placeholders — no restore pass needed.
-            const lines = [];
-            const title = str(c.title);
-            if (title)
-                lines.push(title);
-            const paragraphs = Array.isArray(c.content) ? c.content : [];
-            for (const para of paragraphs) {
-                if (!Array.isArray(para))
-                    continue;
-                const parts = [];
-                for (const node of para) {
-                    if (typeof node !== "object" || node === null)
-                        continue;
-                    if (node.tag === "at")
-                        parts.push(`@${str(node.user_name) ?? str(node.user_id) ?? "user"}`);
-                    else if (node.tag === "a")
-                        parts.push(node.href ? `${str(node.text) ?? node.href} (${node.href})` : (str(node.text) ?? ""));
-                    else if (node.tag === "img") {
-                        if (str(node.image_key))
-                            imageKeys.push(node.image_key);
-                        parts.push("[image]");
-                    }
-                    else if (node.tag === "media") {
-                        if (str(node.file_key))
-                            fileRefs.push({ key: node.file_key, name: str(node.file_name) });
-                        parts.push("[video]");
-                    }
-                    else if (node.tag === "code_block")
-                        parts.push(`\n\`\`\`${str(node.language)?.toLowerCase() ?? ""}\n${str(node.text) ?? ""}\n\`\`\`\n`);
-                    else if (str(node.text))
-                        parts.push(node.text);
-                }
-                const line = parts.join("").trim();
-                if (line)
-                    lines.push(line);
-            }
-            return { text: lines.join("\n"), imageKeys, fileRefs };
-        }
-        case "image": {
-            if (str(c.image_key))
-                imageKeys.push(c.image_key);
-            return { text: "[image]", imageKeys, fileRefs };
-        }
-        case "file": {
-            const name = str(c.file_name);
-            if (str(c.file_key))
-                fileRefs.push({ key: c.file_key, name });
-            return { text: `[file: ${name ?? "file"}]`, imageKeys, fileRefs };
-        }
-        case "audio": {
-            if (str(c.file_key))
-                fileRefs.push({ key: c.file_key, name: "voice-message" });
-            return { text: "[voice message]", imageKeys, fileRefs };
-        }
-        case "media": {
-            const name = str(c.file_name);
-            if (str(c.file_key))
-                fileRefs.push({ key: c.file_key, name });
-            return { text: `[video: ${name ?? "video"}]`, imageKeys, fileRefs };
-        }
-        case "location": {
-            const name = str(c.name);
-            return {
-                text: `[location: ${name ? `${name} — ` : ""}${str(c.latitude) ?? "?"},${str(c.longitude) ?? "?"}]`,
-                imageKeys,
-                fileRefs,
-            };
-        }
-        default:
-            // sticker / share_chat / share_user / system / … — name the type so the agent can say what it got.
-            return { text: `[${m.message_type} message]`, imageKeys, fileRefs };
-    }
+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. 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. */
+/** 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 default session key. */
-export function placeKey(m) {
-    return m.thread_id ? `${m.chat_id}:${m.thread_id}` : m.chat_id;
+/** 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 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 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 m = event.message;
-    if (!m)
+    const message = event.message;
+    if (!message)
         return "";
+    const from = senderLabel(event.sender);
     const meta = [
-        `chat ${m.chat_id} (${m.chat_type})`,
-        m.thread_id ? `topic ${m.thread_id}` : undefined,
-        senderLabel(event.sender) ? `from ${senderLabel(event.sender)}` : undefined,
+        `chat ${message.chat_id} (${message.chat_type})`,
+        message.thread_id ? `topic ${message.thread_id}` : undefined,
+        from ? `from ${from}` : undefined,
     ]
         .filter(Boolean)
         .join(", ");
-    const scope = m.chat_type === "group" ? "\n[group chat — multiple people; each message is prefixed with its sender]" : "";
-    const replyTo = m.parent_id ? `\n[in reply to msg ${m.parent_id}]` : "";
-    return `[${tag}: ${meta}]${scope}${replyTo}\n${parseContent(m).text}`;
+    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 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 function mentionsBot(m, botOpenId) {
+/** Whether the parsed mention list contains this bot's app-scoped open_id. */
+export function mentionsBot(message, botOpenId) {
     if (!botOpenId)
         return false;
-    return (m.mentions ?? []).some((x) => x.id?.open_id === botOpenId);
+    return (message.mentions ?? []).some((mention) => mention.id?.open_id === botOpenId);
 }
 /**
- * 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 function defaultFeishuRoute(event, options) {
-    const m = event.message;
-    if (!m)
+    const message = event.message;
+    if (!message)
         return null;
     if (event.sender?.sender_type !== "user")
         return null;
-    const summoned = m.chat_type === "p2p" || mentionsBot(m, options?.botOpenId);
+    const summoned = message.chat_type === "p2p" || mentionsBot(message, options?.botOpenId);
     return summoned ? {} : null;
 }

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

@@ -1,12 +1,9 @@
 import type { AgentEvent } from "../../agent.ts";
 import { type FeishuApi, type FeishuTarget } from "./feishu-api.ts";
-/** A terminal failure, as the channel hands it to `onError`. */
-export interface FeishuFailure {
-    details: string;
-    retryable: boolean;
-}
-/** The customer-facing default: neutral, no leaked internals; differentiate only on whether to retry. */
-export declare function defaultErrorMessage(failed: FeishuFailure): string;
+import { type ChannelFailure, defaultErrorMessage } from "../preview-kit.ts";
+/** A terminal failure, as the channel hands it to `onError` — the shared channel shape. */
+export type FeishuFailure = ChannelFailure;
+export { defaultErrorMessage };
 /** A visible preview mounted into the chat. Exported only for the channel wiring: a queued turn mounts
  * one before execution, then hands the exact entity/message to {@link streamFeishuReply} for takeover. */
 export type MountedFeishuPreview = {

package/dist/channels/feishu/preview.js

@@ -23,41 +23,16 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "../../log.js";
 import { ANSWER_ELEMENT_ID, CARD_MARKDOWN_MAX_BYTES, cardEntityContent, finalCardJson, streamingCardJson, } from "./card.js";
 import { chunkFeishuText, isCardStreamingClosed } from "./feishu-api.js";
-import { truncateCodePointPrefix, truncateCodePointSuffix, truncateUtf8 } from "./text.js";
-/** The customer-facing default: neutral, no leaked internals; differentiate only on whether to retry. */
-export function defaultErrorMessage(failed) {
-    return failed.retryable ? "⚠️ Temporary problem — please try again." : "⚠️ Sorry, something went wrong.";
-}
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../preview-kit.js";
+import { truncateUtf8 } from "../text.js";
+export { defaultErrorMessage };
 /** How often (ms) to push a live-preview snapshot; tool events still flush on the next loop. Cardkit
  *  allows 10 QPS per card entity (50 per app), but one snapshot a second reads smoothly (the client
  *  animates between snapshots).
  *  Doubles as the answer-preview aging window (see answerView). */
 const STREAM_THROTTLE_MS = 1000;
-/** Max length of a tool's arg preview in the live view. */
-const TOOL_ARG_MAX = 48;
 /** How much of the (growing) reasoning to peek at in the live view — the most recent tail. */
 const THINKING_PREVIEW = 280;
-/** The placeholder shown before any reasoning/tool/text arrives. */
-const THINKING_PLACEHOLDER = "💭 Thinking…";
-/** One-line, truncated: collapse whitespace so a multi-line command/arg stays on one line. */
-function clip(s) {
-    const one = s.replace(/\s+/g, " ").trim();
-    return truncateCodePointPrefix(one, TOOL_ARG_MAX);
-}
-/**
- * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
- * rather than just `🔧 read`. Generic (the channel knows no tool schemas): show the salient value — the
- * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
- */
-function summarizeArgs(args) {
-    if (args === null || typeof args !== "object" || Array.isArray(args))
-        return clip(String(args));
-    const values = Object.values(args);
-    const primary = values.find((v) => typeof v === "string" || typeof v === "number");
-    if (primary !== undefined)
-        return clip(String(primary));
-    return values.length > 0 ? clip(JSON.stringify(args)) : "";
-}
 /** Cap a live view to the card budget, PREFIX-STABLE: the streaming client animates only when the old
  *  text is a prefix of the new, so an over-budget view freezes at its head rather than sliding a tail
  *  window (which would redraw the whole card every frame). The full answer still lands at settle. */
@@ -88,8 +63,8 @@ async function finalize(api, target, preview, text, seq) {
             // Settle failed (card expired / rejected) — fall through to delete + fresh send below.
         }
         if (settled) {
-            // Topic continuations must keep reply_in_thread; ordinary group continuations intentionally avoid
-            // repeating the quote on every chunk. sendText owns the same distinction for its own chunking.
+            // Threaded continuations must keep reply_in_thread; continuous top-level group replies intentionally
+            // avoid repeating the quote on every chunk. sendText owns the same distinction for its own chunking.
             // A continuation failure propagates: the card is already authoritative, so deleting it and sending
             // the full answer again would deterministically duplicate every continuation that already landed.
             const continuationTarget = target.replyInThread ? target : { chatId: target.chatId };
@@ -174,35 +149,16 @@ export async function settleFeishuPreview(api, target, preview, text) {
  * than recalling it and posting another reply.
  */
 export async function streamFeishuReply(events, api, target, formatError, initialPreview, label = "[feishu]") {
-    const tools = [];
-    const toolIndexById = new Map();
-    let thinking = "";
-    let answer = "";
-    let answerPreviewSince;
-    const mark = { running: "…", ok: "✓", error: "✗" };
-    const toolView = () => tools.map((t) => `🔧 ${t.label} ${mark[t.status]}`).join("\n");
-    // Reasoning is process, not the answer: shown (capped to its tail) in the live preview only, never
-    // in the settled final card (which is `answer` alone).
-    const thinkingView = () => {
-        const t = thinking.replace(/\s+/g, " ").trim();
-        if (t === "")
-            return "";
-        return `💭 ${truncateCodePointSuffix(t, THINKING_PREVIEW)}`;
-    };
-    // The answer is hidden until its first delta has aged one STREAM_THROTTLE_MS: the pump's leading-edge
-    // flush would otherwise turn the very first content delta (often a lone character) into its own frame
-    // — the short-reply flicker. Aging is anchored at delta ARRIVAL (set in the event loop, not here) so
-    // an in-flight update can't skew the clock; a turn completing within the window settles directly.
-    const answerView = () => {
-        if (answer.trim() === "" || answerPreviewSince === undefined)
-            return "";
-        return Date.now() - answerPreviewSince >= STREAM_THROTTLE_MS ? answer : "";
-    };
+    // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal
+    // policy, the card-budget cap, and delivery below.
+    const turn = createTurnView();
     const view = () => {
-        const v = [thinkingView(), toolView(), answerView()]
-            .filter((s) => s.trim() !== "")
-            .join("\n\n")
-            .trim();
+        const v = composeTurnBody([
+            thinkingLine(turn, THINKING_PREVIEW),
+            toolLines(turn),
+            turn.retrying ? RETRY_NOTICE : "",
+            revealedAnswer(turn, STREAM_THROTTLE_MS),
+        ]);
         return capBytes(v === "" ? THINKING_PLACEHOLDER : v, CARD_MARKDOWN_MAX_BYTES);
     };
     // The live preview is ONE message: either the queue card/text handed in by the wiring, or a preview
@@ -243,105 +199,31 @@ export async function streamFeishuReply(events, api, target, formatError, initia
             throw e;
         }
     };
-    // ── Live-preview pump: a SINGLE serialized writer. ──────────────────────────────────────────
-    // Events mutate state (thinking / tools / answer) and mark the preview dirty; the pump pushes the
-    // LATEST view() with at most ONE update in flight, paced by a throttle. One-in-flight also guarantees
-    // the card's strictly-increasing `sequence` lands in order (no concurrent frames).
-    let dirty = false;
-    let pumping = false;
-    let stopped = false;
-    let previewErrLogged = false;
-    let pumpDone;
-    let wakeThrottle; // set while the pump is mid-throttle; finish() cuts it short
-    const runPump = async () => {
-        pumping = true;
-        try {
-            while (dirty && !stopped) {
-                dirty = false;
-                try {
-                    await flushPreview();
-                }
-                catch (e) {
-                    // Best-effort preview (the final write is authoritative), but a failing update must be visible —
-                    // log once per turn so a never-rendering preview is diagnosable, not silent.
-                    if (!previewErrLogged) {
-                        previewErrLogged = true;
-                        log.warn(`${label} live preview failed (final reply still sends): ${String(e)}`);
-                    }
-                }
-                if (dirty && !stopped) {
-                    // Pace + coalesce a burst into one snapshot. Interruptible: finish() cuts this short so the
-                    // final write is not delayed by up to STREAM_THROTTLE_MS after the turn completes.
-                    await new Promise((resolve) => {
-                        const t = setTimeout(resolve, STREAM_THROTTLE_MS);
-                        wakeThrottle = () => {
-                            clearTimeout(t);
-                            resolve();
-                        };
-                    });
-                    wakeThrottle = undefined;
-                }
-            }
-        }
-        finally {
-            pumping = false;
-        }
-    };
-    // Mark the preview dirty and ensure the single writer is running (an update already in flight picks
-    // up the new state on its next loop). Synchronous — callers never await a network write.
-    const touch = () => {
-        dirty = true;
-        if (!pumping)
-            pumpDone = runPump();
-    };
+    // The shared single-writer pump (preview-kit) serializes snapshots to the one preview — which also
+    // guarantees the card's strictly-increasing `sequence` lands in order (no concurrent frames).
+    const { touch, finish } = createPreviewPump({
+        flush: flushPreview,
+        throttleMs: STREAM_THROTTLE_MS,
+        onError: (e) => log.warn(`${label} live preview failed (final reply still sends): ${String(e)}`),
+    });
     touch(); // mount the "💭 Thinking…" preview immediately
-    // Stop the pump and await any in-flight update, so the final write below is strictly the LAST one to
-    // the preview (no stale frame landing after the answer).
-    const finish = async () => {
-        stopped = true;
-        wakeThrottle?.(); // cut an in-flight throttle so the final write is not delayed up to STREAM_THROTTLE_MS
-        await pumpDone?.catch(() => { });
-    };
     /** Terminal write, whatever tier the preview reached. */
     const settle = async (text) => {
         await finalize(api, target, preview, text, nextSeq);
     };
     try {
         for await (const e of events) {
-            if (e.type === "text") {
-                answer += e.delta;
-                if (answerPreviewSince === undefined && answer.trim() !== "")
-                    answerPreviewSince = Date.now();
-                touch();
-            }
-            else if (e.type === "thinking") {
-                thinking += e.delta;
-                touch();
-            }
-            else if (e.type === "tool_started") {
-                const arg = summarizeArgs(e.args);
-                toolIndexById.set(e.id, tools.length);
-                tools.push({ label: arg ? `${e.name} ${arg}` : e.name, status: "running" });
-                touch();
-            }
-            else if (e.type === "tool_ended") {
-                const i = toolIndexById.get(e.id);
-                const t = i === undefined ? undefined : tools[i];
-                if (t)
-                    t.status = e.isError ? "error" : "ok";
-                touch();
-            }
-            else if (e.type === "completed") {
+            if (e.type === "completed") {
                 await finish();
                 // Settle the preview into the final answer; the persisted card is the answer alone — the
                 // process (thinking/tools) was preview-only. Mark finalized BEFORE delivering: the terminal was
                 // reached, so a delivery failure here is a plain failure, not an "abnormal exit" (which would
                 // wrongly fire the finally's neutral-notice fallback = double delivery + wrong text).
                 finalized = true;
-                await settle(answer.trim() !== "" ? answer : "(no reply)");
+                await settle(turn.answer.trim() !== "" ? turn.answer : "(no reply)");
                 return;
             }
-            else if (e.type === "failed") {
+            if (e.type === "failed") {
                 await finish();
                 // Two audiences: the chat (customer-facing — formatError, neutral by default) and the operator
                 // log (dev-facing — the full details, via the throw below + the handler's catch). Same terminal
@@ -361,6 +243,8 @@ export async function streamFeishuReply(events, api, target, formatError, initia
                 }
                 throw new Error(`agent failed: ${e.details} (retryable=${e.retryable})`);
             }
+            if (applyTurnEvent(turn, e))
+                touch();
         }
         throw new Error("stream ended without a terminal event"); // violates SPEC MUST 1
     }

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

@@ -21,7 +21,7 @@
  * encoding (JSON → gzip → base64url) follow the official SDKs (provenance: node-sdk
  * scene/registration); item names unknown to the platform catalog are silently dropped by the page.
  */
-export interface FeishuAppAddons {
+interface FeishuAppAddons {
     scopes?: {
         tenant?: string[];
         user?: string[];
@@ -68,3 +68,4 @@ export interface RegisteredFeishuApp {
  * abort, or a transport failure — every rejection is a plain Error whose message says what to do.
  */
 export declare function registerFeishuApp(options: RegisterFeishuAppOptions): Promise<RegisteredFeishuApp>;
+export {};

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

@@ -7,7 +7,7 @@ import { type FeishuCloudKind } from "./cloud.ts";
  *
  * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
-export interface FeishuManualRegistration {
+interface FeishuManualRegistration {
     consoleUrl: string;
     requestUrl: string;
 }
@@ -20,3 +20,4 @@ export interface RegisterFeishuWebhookOptions {
     onManualRegistration?: (info: FeishuManualRegistration) => void;
 }
 export declare function registerFeishuWebhook(baseUrl: string, kind: FeishuCloudKind, opts?: RegisterFeishuWebhookOptions): Promise<RegistrationOutcome>;
+export {};

package/dist/channels/feishu/scaffold/channel.ts

@@ -7,7 +7,9 @@ import { feishuChannel } from "@fastagent-sh/fastagent/feishu";
 //   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
 //   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
 //      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
-//      card scope ("Create and update card" — the live preview streams through a card)
+//      card scope ("Create and update card" — the live preview streams through a card). To answer bare
+//      messages in Agent-managed threads and buffer other unsummoned group/thread context, also add the
+//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version.
 //   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
 //      .env; RECOMMENDED: set an Encrypt Key there and mirror it in FEISHU_ENCRYPT_KEY
 //   4. the event Request URL (https://your.host/feishu) is registered AUTOMATICALLY by
@@ -21,14 +23,19 @@ export default feishuChannel({
   appSecret: process.env.FEISHU_APP_SECRET ?? "",
   verificationToken: process.env.FEISHU_VERIFICATION_TOKEN ?? "", // authenticates inbound events
   encryptKey: process.env.FEISHU_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
+  // Direct and group chats default to one Agent session/thread per top-level ask. Opt out independently:
+  // directMessageSession: "continuous",
+  // groupMessageSession: "continuous",
   // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
   // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
   // full details always go to the server log regardless.
   onError: (failed) => `⚠️ ${failed.details}`,
   // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
   // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
-  // p2p chats always answer, groups only on an @mention of this bot (matched by open_id, resolved at
-  // startup). Override to customise, reusing the export:
+  // p2p chats always answer; groups answer on @this-bot, plus bare continuations in Agent-managed
+  // threads. Other human group/thread discussion buffers until that place's next answered turn;
+  // @other-only messages in managed threads buffer rather than triggering the Agent.
+  // Override to customise explicit routing, reusing the export:
   //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
   //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },
 });

package/dist/channels/feishu/setup-mode.d.ts

@@ -0,0 +1,8 @@
+/** Feishu/Lark app-level event subscription choice used by onboarding and scaffolding. */
+export type FeishuSubscriptionMode = "webhook" | "websocket";
+/** Onboarding choice for group visibility. `context` needs the tenant-wide group-message scope; the
+ * runtime remains capability-driven because the platform, not channel source, decides which events
+ * are delivered. */
+export type FeishuGroupBehavior = "context" | "mentions";
+/** The sensitive tenant scope behind both managed-thread bare replies and group context buffering. */
+export declare const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";

package/dist/channels/feishu/setup-mode.js

@@ -0,0 +1,2 @@
+/** The sensitive tenant scope behind both managed-thread bare replies and group context buffering. */
+export const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";

package/dist/channels/feishu/ws-ingress.d.ts

@@ -0,0 +1,28 @@
+import type { LongConnection } from "../../host/node.ts";
+import type { FeishuCloudKind } from "./cloud.ts";
+import type { FeishuMessageEvent } from "./parse.ts";
+interface FeishuWsClient {
+    start(): Promise<void>;
+    close(): void;
+}
+interface FeishuWsClientCallbacks {
+    onReady(): void;
+    onError(error: Error): void;
+    onReconnecting(): void;
+    onReconnected(): void;
+    onEvent(event: FeishuMessageEvent): void | Promise<void>;
+}
+export type CreateFeishuWsClient = (callbacks: FeishuWsClientCallbacks) => FeishuWsClient | Promise<FeishuWsClient>;
+export interface FeishuWsConnectionOptions {
+    kind: FeishuCloudKind;
+    appId: string;
+    appSecret: string;
+    domain: string;
+    onEvent(event: FeishuMessageEvent): void | Promise<void>;
+    /** Internal SDK seam for deterministic tests. */
+    createClient?: CreateFeishuWsClient;
+}
+/** Open Feishu/Lark's official-SDK WebSocket connection. The SDK ACKs only after `onEvent` settles;
+ * a persistence throw therefore becomes a 500 response frame and the platform re-pushes the event. */
+export declare function connectFeishuWs(options: FeishuWsConnectionOptions, signal: AbortSignal): LongConnection;
+export {};