@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/README.md

@@ -39,7 +39,7 @@ FastAgent is the missing bridge from local agent directory to live service.
 - **Channels.** Serve the same agent as a GitHub PR reviewer, a Telegram bot, an HTTP/SSE endpoint, or your own adapter — verified webhooks, streaming replies, group-aware.
 - **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key; typed tools discovered from `tools/` (the filename is the name, Zod-validated); Agent Skills loaded on demand. Built on the open-source [pi](https://github.com/earendil-works/pi) harness.
 - **App embedding — your stack, we plug in.** Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler, or call `invoke` like any function from your own code — your auth, your database, your infra. FastAgent composes with your app, never owns it.
-- **Deploy anywhere.** No build step — the directory is the deployable unit. `fastagent deploy fly|railway` generates the deploy config + a runbook (`--run` drives it to completion); idle agents scale to zero and resume in hundreds of milliseconds on the next webhook. The generated container runs on any Docker host.
+- **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; optional `--tunnel` adds an ephemeral Quick Tunnel service for webhook channels. Durable ingress remains yours.
 
 ## Design philosophy
 
@@ -145,7 +145,7 @@ const agent = createPiAgent({
 | [Embedding](https://fastagent.sh/docs/embedding/) | Use FastAgent as a library inside your own app |
 | [Channels](https://fastagent.sh/docs/channels/) | Add webhook/bot channels |
 | [Deploy](https://fastagent.sh/docs/deploy/) | Ship the directory to Fly, Railway, or any Docker host |
-| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) | First-party channel guides |
+| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) / [Feishu and Lark](https://fastagent.sh/docs/feishu/) | First-party channel guides |
 | [Channel development](https://fastagent.sh/docs/channel-development/) | Build custom channel adapters |
 | [API reference](https://fastagent.sh/docs/api-reference/) | Public TypeScript API reference |
 | [Troubleshooting](https://fastagent.sh/docs/troubleshooting/) | Common setup/runtime issues |
@@ -170,7 +170,9 @@ Subpath exports:
 - `@fastagent-sh/fastagent/core` — engine-neutral contract, consumption helpers, channel/host kit, schedules;
 - `@fastagent-sh/fastagent/pi` — the pi reference implementation;
 - `@fastagent-sh/fastagent/github` — GitHub webhook channel;
-- `@fastagent-sh/fastagent/telegram` — Telegram bot channel.
+- `@fastagent-sh/fastagent/telegram` — Telegram bot channel;
+- `@fastagent-sh/fastagent/feishu` — canonical Feishu bot channel (飞书, open.feishu.cn);
+- `@fastagent-sh/fastagent/lark` — Lark-international compatibility profile over the Feishu engine.
 
 ## Repository layout
 
@@ -196,7 +198,7 @@ The neutral contract leaves room for capabilities that are not complete product
 - **Sandboxed execution** — `ExecutionEnv` is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter is future work.
 - **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
 - **More harness bindings and channels** — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.
-- **More deploy targets** — Fly and Railway ship today; the generated container is the portable path for other hosts.
+- **More deploy targets** — local Docker, Fly, and Railway ship today; the generated container is the portable path for other hosts.
 
 See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md) if one of these is the problem you want to work on.
 

package/dist/channels/feishu/bootstrap-token.d.ts

@@ -0,0 +1,42 @@
+import type { FeishuCloudKind } from "./cloud.ts";
+/** What the bootstrap needs from the API pipeline (subset of FeishuApi; injectable in tests). */
+interface EventSubscriptionPatcher {
+    updateEventSubscription(appId: string, cfg: {
+        subscriptionType: "webhook";
+        requestUrl: string;
+    }): Promise<void>;
+}
+export interface FeishuBootstrapTokenOptions {
+    api: EventSubscriptionPatcher;
+    appId: string;
+    /** Canonical Feishu by default; Lark compatibility binds its own route explicitly. */
+    kind?: FeishuCloudKind;
+    /** Expose local `port` on a public URL (production: startCloudflareTunnel; tests: loopback). */
+    startTunnel: (port: number) => Promise<{
+        url: string;
+        close(): void;
+    } | undefined>;
+    /** Budget for the whole capture (the challenge normally lands within the PATCH round-trip). */
+    timeoutMs?: number;
+    /** PATCH attempts × delay — the PATCH is the one and only readiness probe (see below). */
+    patchAttempts?: number;
+    patchRetryMs?: number;
+    /** Retry classifier. Default: retry every PATCH failure (Feishu edge warm-up compatibility).
+     * Lark onboarding rejects a definitive config-route 404 immediately so it can fall back by hand. */
+    shouldRetryPatch?: (error: unknown) => boolean;
+    /** Progress hooks: production prints the assigned URL/retries; tests keep transport IO injected. */
+    onTunnelReady?: (url: string) => void;
+    onPatchRetry?: (info: {
+        error: unknown;
+        attempt: number;
+        attempts: number;
+        retryMs: number;
+    }) => void;
+}
+/**
+ * Run the bootstrap (module header). Resolves with the app's Verification Token; rejects with a
+ * plain, actionable Error (tunnel unavailable, PATCH refused, challenge never arrived) — the caller
+ * degrades to the manual console instruction.
+ */
+export declare function bootstrapFeishuVerificationToken(options: FeishuBootstrapTokenOptions): Promise<string>;
+export {};

package/dist/channels/feishu/bootstrap-token.js

@@ -0,0 +1,94 @@
+/**
+ * Verification-Token bootstrap — the token has NO read API (field-tested 2026-07: the v6 app detail
+ * never returns `encryption`, and the v7 config route only supports PATCH). The platform's only
+ * programmatic delivery is the `url_verification` challenge it POSTs to the request URL while an
+ * event-subscription PATCH is verified — the challenge body carries `token`, the app's Verification
+ * Token. So `add feishu`'s create flow finishes the job by: standing up a throwaway local responder,
+ * exposing it on an ephemeral quick tunnel, PATCHing the app's event subscription at it, capturing
+ * the token from the challenge, and tearing everything down. `dev --tunnel` / `deploy … --run`
+ * re-PATCH the request URL onto the real server later (the token is app-level and survives that).
+ *
+ * Security: the serving path keeps its strict non-empty-token requirement — no bootstrap mode there.
+ * The throwaway URL is random (unguessable), lives for seconds, and only the FIRST challenge is
+ * accepted, immediately after our own credential-authenticated PATCH.
+ */
+import { createServer } from "node:http";
+/**
+ * Run the bootstrap (module header). Resolves with the app's Verification Token; rejects with a
+ * plain, actionable Error (tunnel unavailable, PATCH refused, challenge never arrived) — the caller
+ * degrades to the manual console instruction.
+ */
+export async function bootstrapFeishuVerificationToken(options) {
+    let capturedToken;
+    const token = new Promise((resolve) => {
+        capturedToken = resolve;
+    });
+    // The throwaway responder: answers /health (diagnostics) and the url_verification challenge
+    // (echo `challenge` back), capturing `token` from the FIRST challenge only.
+    const server = createServer((req, res) => {
+        if (req.method === "GET") {
+            res.end("ok");
+            return;
+        }
+        let body = "";
+        req.on("data", (d) => {
+            body += String(d);
+        });
+        req.on("end", () => {
+            try {
+                const j = JSON.parse(body);
+                if (j.type === "url_verification" && typeof j.challenge === "string" && typeof j.token === "string") {
+                    capturedToken?.(j.token);
+                    capturedToken = undefined; // first challenge only
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ challenge: j.challenge }));
+                    return;
+                }
+            }
+            catch {
+                /* not the challenge — fall through to the empty ACK */
+            }
+            res.end("{}");
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    const port = typeof address === "object" && address !== null ? address.port : 0;
+    const tunnel = await options.startTunnel(port);
+    try {
+        if (!tunnel)
+            throw new Error("no tunnel came up (is cloudflared installed?)");
+        options.onTunnelReady?.(tunnel.url);
+        // Do NOT health-poll the edge here: "can WE reach it" says nothing about platform→edge, the path
+        // the challenge uses (field-tested: local negative-DNS caching failed while that path worked).
+        // PATCH immediately; it is the real probe because success requires the challenge round-trip.
+        const attempts = options.patchAttempts ?? 8;
+        for (let attempt = 1;; attempt++) {
+            try {
+                await options.api.updateEventSubscription(options.appId, {
+                    subscriptionType: "webhook",
+                    requestUrl: `${tunnel.url}/${options.kind ?? "feishu"}`,
+                });
+                break;
+            }
+            catch (e) {
+                if (attempt >= attempts || options.shouldRetryPatch?.(e) === false)
+                    throw e;
+                const retryMs = options.patchRetryMs ?? 10_000;
+                options.onPatchRetry?.({ error: e, attempt, attempts, retryMs });
+                await new Promise((resolve) => setTimeout(resolve, retryMs));
+            }
+        }
+        const winner = await Promise.race([
+            token,
+            new Promise((resolve) => setTimeout(() => resolve(undefined), options.timeoutMs ?? 30_000)),
+        ]);
+        if (winner === undefined)
+            throw new Error("the registration challenge never arrived");
+        return winner;
+    }
+    finally {
+        tunnel?.close();
+        server.close();
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled
+ * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
+ * the card DSL is data-in → string-out and testable without the pump.
+ *
+ * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
+ * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
+ * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
+ * element, `streaming_mode` off — one write flips content and mode together.
+ *
+ * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
+ * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
+ */
+/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+export declare const ANSWER_ELEMENT_ID = "answer";
+/** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
+export declare const CARD_MARKDOWN_MAX_BYTES: number;
+/**
+ * The answer's first line as plain text — what the chat list and the push notification show for the
+ * settled card (`config.summary.content`). Without it a card message previews as a generic "[Card]"
+ * placeholder: the user's notification would never carry the actual answer. Markdown is stripped
+ * lightly (this is a one-line teaser, not a renderer): fenced code dropped, links/images → their text,
+ * emphasis/heading/list markers removed.
+ */
+export declare function cardSummary(markdown: string): string;
+/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
+export declare function streamingCardJson(initial: string): string;
+/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
+ *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+export declare function finalCardJson(markdown: string): string;
+/** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
+export declare function cardEntityContent(cardId: string): string;

package/dist/channels/feishu/card.js

@@ -0,0 +1,66 @@
+/**
+ * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled
+ * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
+ * the card DSL is data-in → string-out and testable without the pump.
+ *
+ * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
+ * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
+ * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
+ * element, `streaming_mode` off — one write flips content and mode together.
+ *
+ * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
+ * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
+ */
+import { truncateCodePointPrefix } from "./text.js";
+/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+export const ANSWER_ELEMENT_ID = "answer";
+/** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
+export const CARD_MARKDOWN_MAX_BYTES = 20 * 1024;
+/** Character budget for the settled card's summary (the chat-list / push-notification preview). */
+const SUMMARY_MAX_CHARS = 60;
+/**
+ * The answer's first line as plain text — what the chat list and the push notification show for the
+ * settled card (`config.summary.content`). Without it a card message previews as a generic "[Card]"
+ * placeholder: the user's notification would never carry the actual answer. Markdown is stripped
+ * lightly (this is a one-line teaser, not a renderer): fenced code dropped, links/images → their text,
+ * emphasis/heading/list markers removed.
+ */
+export function cardSummary(markdown) {
+    const line = markdown
+        .replace(/```[\s\S]*?(```|$)/g, " ") // fenced code is never a readable one-line preview
+        .split("\n")
+        .map((l) => l
+        .replace(/^\s{0,3}(?:#{1,6}|>|[-*+]|\d+[.)])\s+/, "") // heading / quote / list markers
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // images → alt text
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // links → link text
+        .replace(/[*_~`]/g, "")
+        .trim())
+        .find((l) => l !== "") ?? "";
+    return truncateCodePointPrefix(line, SUMMARY_MAX_CHARS);
+}
+function cardJson(markdown, streaming, summary) {
+    return JSON.stringify({
+        schema: "2.0",
+        config: {
+            streaming_mode: streaming,
+            update_multi: true,
+            // Only the settled card sets a summary — while streaming, the platform's default (a localized
+            // "[Generating…]") is better than any fixed text we could pin.
+            ...(summary ? { summary: { content: summary } } : {}),
+        },
+        body: { elements: [{ tag: "markdown", content: markdown, element_id: ANSWER_ELEMENT_ID }] },
+    });
+}
+/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
+export function streamingCardJson(initial) {
+    return cardJson(initial, true);
+}
+/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
+ *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+export function finalCardJson(markdown) {
+    return cardJson(markdown, false, cardSummary(markdown));
+}
+/** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
+export function cardEntityContent(cardId) {
+    return JSON.stringify({ type: "card", data: { card_id: cardId } });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Feishu is the canonical implementation. Lark international speaks the same protocol but trails the
+ * primary cloud in control-plane capabilities, so it binds the Feishu engine through this explicit
+ * compatibility profile instead of becoming the engine's naming/design center.
+ */
+export type FeishuCloudKind = "feishu" | "lark";
+export interface FeishuCloudProfile {
+    kind: FeishuCloudKind;
+    envPrefix: "FEISHU" | "LARK";
+    apiBase: string;
+    capabilities: {
+        appCreation: "scan-to-create" | "guided-console";
+    };
+}
+export declare const FEISHU_CLOUD: FeishuCloudProfile;
+export declare const LARK_COMPAT_CLOUD: FeishuCloudProfile;
+export declare function cloudFor(kind: FeishuCloudKind): FeishuCloudProfile;

package/dist/channels/feishu/cloud.js

@@ -0,0 +1,19 @@
+export const FEISHU_CLOUD = {
+    kind: "feishu",
+    envPrefix: "FEISHU",
+    apiBase: "https://open.feishu.cn",
+    capabilities: {
+        appCreation: "scan-to-create",
+    },
+};
+export const LARK_COMPAT_CLOUD = {
+    kind: "lark",
+    envPrefix: "LARK",
+    apiBase: "https://open.larksuite.com",
+    capabilities: {
+        appCreation: "guided-console",
+    },
+};
+export function cloudFor(kind) {
+    return kind === "feishu" ? FEISHU_CLOUD : LARK_COMPAT_CLOUD;
+}

package/dist/channels/feishu/context-buffer.d.ts

@@ -0,0 +1,46 @@
+import type { NormalizedFeishuMessage } from "./model.ts";
+export interface FeishuBufferedResource {
+    messageId: string;
+    key: string;
+    name?: string;
+}
+export interface FeishuBufferEntry {
+    sender: string;
+    body: string;
+    messageId: string;
+    replyTo?: string;
+    files?: FeishuBufferedResource[];
+    images?: FeishuBufferedResource[];
+}
+/** A background resource carried into a later turn, with attribution for its prompt manifest. */
+export interface FeishuBufferedRef extends FeishuBufferedResource {
+    from: string;
+}
+/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
+export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "rootId" | "threadId">): string;
+/** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
+export declare function feishuBufferText(text: string): string;
+/**
+ * Select the most recent background resources, excluding resources already primary on this turn. A
+ * resource is message-scoped in Feishu/Lark, so identity is `message_id + key`, never the bare key.
+ */
+export declare function collectFeishuBufferedAttachments(consumed: FeishuBufferEntry[], primary: {
+    files: FeishuBufferedResource[];
+    images: FeishuBufferedResource[];
+}): {
+    files: FeishuBufferedRef[];
+    images: FeishuBufferedRef[];
+    skipped: number;
+};
+export interface FeishuContextBuffer {
+    /** Persist before webhook ACK. A failed write throws and rolls memory back for safe redelivery. */
+    push(placeKey: string, entry: FeishuBufferEntry): void;
+    /** Render and snapshot without clearing. */
+    peek(placeKey: string): {
+        text: string;
+        consumed: FeishuBufferEntry[];
+    };
+    /** Remove only the consumed snapshot after `completed`; a post-ACK write failure is logged. */
+    commit(placeKey: string, consumed: FeishuBufferEntry[]): void;
+}
+export declare function createFeishuContextBuffer(path: string, label: string): FeishuContextBuffer;

package/dist/channels/feishu/context-buffer.js

@@ -0,0 +1,133 @@
+/**
+ * Durable context buffer for human group messages that do NOT currently summon the Feishu/Lark Agent.
+ * Entries are bucketed by conversation place (main chat, or one concrete thread root) and folded into
+ * the next answered turn in that place. The consume protocol mirrors Telegram: peek without clearing,
+ * then commit exactly that snapshot only after the Agent emits `completed`.
+ */
+import { log } from "../../log.js";
+import { loadStateFile, saveStateFile } from "../state.js";
+const BUFFER_MAX_CHARS = 4000;
+const BUFFER_ATTACH_MAX = 3;
+function bufferLine(entry) {
+    const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
+        .filter(Boolean)
+        .join(", ");
+    return `${entry.sender} (${meta}): ${entry.body}`;
+}
+/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
+export function feishuBufferPlaceKey(conversation) {
+    const topic = conversation.rootId ?? conversation.threadId;
+    return topic ? `${conversation.chatId}:root:${topic}` : conversation.chatId;
+}
+/** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
+export function feishuBufferText(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, 280);
+}
+function resourceIdentity(resource) {
+    return `${resource.messageId}\u0000${resource.key}`;
+}
+/**
+ * Select the most recent background resources, excluding resources already primary on this turn. A
+ * resource is message-scoped in Feishu/Lark, so identity is `message_id + key`, never the bare key.
+ */
+export function collectFeishuBufferedAttachments(consumed, primary) {
+    const refs = (pick, primaryRefs) => {
+        const excluded = new Set(primaryRefs.map(resourceIdentity));
+        const seen = new Set();
+        const out = [];
+        for (const entry of consumed) {
+            for (const resource of pick(entry) ?? []) {
+                const identity = resourceIdentity(resource);
+                if (excluded.has(identity) || seen.has(identity))
+                    continue;
+                seen.add(identity);
+                out.push({ ...resource, from: entry.sender });
+            }
+        }
+        return out;
+    };
+    const files = refs((entry) => entry.files, primary.files);
+    const images = refs((entry) => entry.images, primary.images);
+    return {
+        files: files.slice(-BUFFER_ATTACH_MAX),
+        images: images.slice(-BUFFER_ATTACH_MAX),
+        skipped: Math.max(0, files.length - BUFFER_ATTACH_MAX) + Math.max(0, images.length - BUFFER_ATTACH_MAX),
+    };
+}
+function isResource(value) {
+    const resource = value;
+    return (typeof resource?.messageId === "string" &&
+        typeof resource.key === "string" &&
+        (resource.name === undefined || typeof resource.name === "string"));
+}
+function isEntry(value) {
+    const entry = value;
+    const resources = (candidate) => candidate === undefined || (Array.isArray(candidate) && candidate.every(isResource));
+    return (typeof entry?.sender === "string" &&
+        typeof entry.body === "string" &&
+        typeof entry.messageId === "string" &&
+        (entry.replyTo === undefined || typeof entry.replyTo === "string") &&
+        resources(entry.files) &&
+        resources(entry.images));
+}
+export function createFeishuContextBuffer(path, label) {
+    const load = () => {
+        const raw = loadStateFile(path);
+        if (raw === undefined)
+            return new Map();
+        if (typeof raw === "object" &&
+            raw !== null &&
+            !Array.isArray(raw) &&
+            Object.values(raw).every((entries) => Array.isArray(entries) && entries.every(isEntry))) {
+            return new Map(Object.entries(raw));
+        }
+        log.warn(`${label} unexpected shape in ${path} — starting with an empty context buffer`);
+        return new Map();
+    };
+    const buffers = load();
+    const persist = () => saveStateFile(path, Object.fromEntries(buffers));
+    return {
+        push(placeKey, entry) {
+            const previous = buffers.get(placeKey);
+            const entries = previous ? [...previous] : [];
+            entries.push(entry);
+            let total = entries.reduce((sum, candidate) => sum + bufferLine(candidate).length + 1, 0);
+            while (entries.length > 1 && total > BUFFER_MAX_CHARS) {
+                const dropped = entries.shift();
+                if (dropped)
+                    total -= bufferLine(dropped).length + 1;
+            }
+            buffers.set(placeKey, entries);
+            try {
+                persist();
+            }
+            catch (error) {
+                if (previous)
+                    buffers.set(placeKey, previous);
+                else
+                    buffers.delete(placeKey);
+                throw error;
+            }
+        },
+        peek(placeKey) {
+            const entries = buffers.get(placeKey) ?? [];
+            return { text: entries.map(bufferLine).join("\n"), consumed: [...entries] };
+        },
+        commit(placeKey, consumed) {
+            const entries = buffers.get(placeKey);
+            if (!entries)
+                return;
+            const remaining = entries.filter((entry) => !consumed.includes(entry));
+            if (remaining.length === 0)
+                buffers.delete(placeKey);
+            else
+                buffers.set(placeKey, remaining);
+            try {
+                persist();
+            }
+            catch (error) {
+                log.error(`${label} context-buffer write failed post-ACK (a restart may re-fold answered discussion): ${String(error)}`);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,15 @@
+/** Constant-time string equality (padded to equal length first — timingSafeEqual demands it). */
+export declare function timingSafeEqualStr(a: string, b: string): boolean;
+/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed
+ * input or invalid padding. AES-CBC is not authenticated, so a wrong key is not mathematically
+ * guaranteed to fail padding; the caller verifies signed events before decrypting and JSON-parses every
+ * plaintext envelope, turning wrong-key garbage into a 4xx rather than a silent drop. */
+export declare function decryptEvent(encryptKey: string, encryptB64: string): string;
+/** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
+export declare function eventSignature(encryptKey: string, timestamp: string, nonce: string, rawBody: string): string;
+/** Whether a request's signature headers verify against the raw body (constant-time). */
+export declare function verifySignature(encryptKey: string, headers: {
+    timestamp: string;
+    nonce: string;
+    signature: string;
+}, rawBody: string): boolean;

package/dist/channels/feishu/crypto.js

@@ -0,0 +1,43 @@
+/**
+ * Canonical Feishu webhook security (reused by Lark compatibility) — PURE: AES event decryption and request
+ * signature, exactly as the open platform defines them. When an Encrypt Key is configured in the
+ * developer console, every event arrives as `{"encrypt": "<base64>"}` with signature headers; without
+ * one, events arrive in plaintext and carry only the verification token in the body. feishu.ts owns the
+ * fail-closed policy (which checks run when); this module owns the math.
+ *
+ *  - Decryption: AES-256-CBC. The key is sha256(encryptKey); the base64 payload is IV (16 bytes) ‖
+ *    ciphertext; the plaintext is the event JSON (PKCS#7 padding handled by the cipher).
+ *  - Signature: `X-Lark-Signature = sha256(timestamp + nonce + encryptKey + rawBody)` hex, where
+ *    rawBody is the VERBATIM request body (the encrypted form) — computed over bytes, so the caller
+ *    must pass the raw text, never a re-serialization.
+ *
+ * Comparisons are constant-time (timingSafeEqual) so neither the signature check nor the verification-
+ * token check leaks a timing signal.
+ */
+import { createDecipheriv, createHash, timingSafeEqual } from "node:crypto";
+/** Constant-time string equality (padded to equal length first — timingSafeEqual demands it). */
+export function timingSafeEqualStr(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed
+ * input or invalid padding. AES-CBC is not authenticated, so a wrong key is not mathematically
+ * guaranteed to fail padding; the caller verifies signed events before decrypting and JSON-parses every
+ * plaintext envelope, turning wrong-key garbage into a 4xx rather than a silent drop. */
+export function decryptEvent(encryptKey, encryptB64) {
+    const key = createHash("sha256").update(encryptKey, "utf8").digest();
+    const buf = Buffer.from(encryptB64, "base64");
+    if (buf.length <= 16)
+        throw new Error("encrypted event payload is too short to carry an IV + ciphertext");
+    const decipher = createDecipheriv("aes-256-cbc", key, buf.subarray(0, 16));
+    return Buffer.concat([decipher.update(buf.subarray(16)), decipher.final()]).toString("utf8");
+}
+/** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
+export function eventSignature(encryptKey, timestamp, nonce, rawBody) {
+    return createHash("sha256").update(`${timestamp}${nonce}${encryptKey}${rawBody}`, "utf8").digest("hex");
+}
+/** Whether a request's signature headers verify against the raw body (constant-time). */
+export function verifySignature(encryptKey, headers, rawBody) {
+    return timingSafeEqualStr(eventSignature(encryptKey, headers.timestamp, headers.nonce, rawBody), headers.signature);
+}