@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/channels/discover.js

@@ -5,10 +5,9 @@
  * Engine-neutral, and living here rather than under `engines/` because of it: reading `channels/*.ts`
  * is the Channel contract plus a directory, with no engine in sight.
  */
-import { readdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { assertRouteKey, routeKeysConflict } from "./serve.js";
-import { isModuleFile, loadModuleDir } from "../loader.js";
+import { loadModuleDir, moduleInventory } from "../loader.js";
 import { assertInsideAgentDir } from "../paths.js";
 function longConnectionModule(value) {
     return value !== null && typeof value === "object" && typeof value.connect === "function";
@@ -18,28 +17,29 @@ function validateLongConnectionModule(value, label) {
         throw new Error(`${label}: long-connection channel name must be a non-empty string`);
     }
 }
+/** Declared channels from basenames that share one ingress: the serving surface's mounted route list
+ *  (a long-connection channel mounts no HTTP route, so every route IS a webhook channel), and fixtures. */
+export function declaredChannels(names, ingress = "webhook") {
+    return names.map((name) => ({ name, ingress }));
+}
 /**
  * Import channel files without mounting route factories or opening connections. Deployment needs only
- * the authored structural fact: function exports are route channels; `{ connect() }` exports are
+ * the authored structural fact: function exports are webhook channels; `{ connect() }` exports are
  * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
  */
 export async function inspectChannels(dir) {
     await assertInsideAgentDir(dir, "channels");
     const { modules, failures } = await loadModuleDir(join(dir, "channels"));
     const channels = [];
-    const routeChannels = [];
-    const longConnectionChannels = [];
     for (const { name, label, file, mod } of modules) {
         try {
             if (typeof mod.default === "function") {
-                channels.push(name);
-                routeChannels.push(name);
+                channels.push({ name, ingress: "webhook" });
                 continue;
             }
             if (longConnectionModule(mod.default)) {
                 validateLongConnectionModule(mod.default, label);
-                channels.push(name);
-                longConnectionChannels.push(name);
+                channels.push({ name, ingress: "long-connection" });
                 continue;
             }
             throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
@@ -48,7 +48,7 @@ export async function inspectChannels(dir) {
             failures.push({ label, file, message: error.message });
         }
     }
-    return { channels, routeChannels, longConnectionChannels, failures };
+    return { channels, failures };
 }
 /**
  * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
@@ -56,19 +56,8 @@ export async function inspectChannels(dir) {
  */
 export async function discoverChannelFiles(dir) {
     await assertInsideAgentDir(dir, "channels");
-    let names;
-    try {
-        names = await readdir(join(dir, "channels"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-    return names
-        .filter(isModuleFile)
-        .map((name) => name.replace(/\.(ts|js|mjs)$/, ""))
-        .sort();
+    const entries = await moduleInventory(join(dir, "channels"));
+    return entries.map((entry) => entry.name);
 }
 function validateRoutes(value, label) {
     if (value === null || typeof value !== "object" || value instanceof Map) {
@@ -96,7 +85,6 @@ export async function loadChannels(dir, ctx) {
     const routes = {};
     const longConnections = [];
     const routeChannels = [];
-    const longConnectionChannels = [];
     const collisions = [];
     for (const { name, label, file, mod } of modules) {
         try {
@@ -107,7 +95,6 @@ export async function loadChannels(dir, ctx) {
                     name: channel.name,
                     connect: (signal) => channel.connect(ctx, signal),
                 });
-                longConnectionChannels.push(name);
                 continue;
             }
             if (typeof mod.default !== "function") {
@@ -135,5 +122,5 @@ export async function loadChannels(dir, ctx) {
             failures.push({ label, file, message: error.message });
         }
     }
-    return { routes, longConnections, routeChannels, longConnectionChannels, collisions, failures };
+    return { routes, longConnections, routeChannels, collisions, failures };
 }

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

@@ -1,3 +1,9 @@
+/**
+ * Feishu/Lark's half of the shared context buffer (mechanics + consume protocol:
+ * ../kit/context-buffer.ts): the entry shape, its fold-line rendering, place-key derivation, and
+ * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
+ * concrete thread root) and folded into the next answered turn in that place.
+ */
 import { type ContextBuffer } from "../kit/context-buffer.ts";
 import type { NormalizedFeishuMessage } from "./model.ts";
 export interface FeishuBufferedResource {

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

@@ -4,9 +4,7 @@
  * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
  * concrete thread root) and folded into the next answered turn in that place.
  */
-import { log } from "../../log.js";
 import { BUFFER_ATTACH_MAX, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
-import { loadStateFile, saveStateFile } from "../kit/state.js";
 import { truncateCodePointPrefix } from "../kit/text.js";
 function bufferLine(entry) {
     const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
@@ -80,43 +78,7 @@ function isEntry(value) {
         resources(entry.files) &&
         resources(entry.images));
 }
-/**
- * Buckets from the pre-participant-model keying (`<chat>:root:<root_id>`) can never be produced again —
- * a place is `<chat>` or `<chat>:thread:<thread_id>` — so nothing could ever fold or clear them, and
- * they would hold chat content on disk forever. Dropped here, before the buffer loads, so the shared
- * kernel never learns about a key shape one channel retired.
- *
- * TWO one-time losses, both accepted and both logged by count. (1) The retired shape covered every
- * thread bucket and every main-chat quoted-reply bucket, so buffered discussion in threads does not
- * survive the upgrade — it becomes unreachable BECAUSE of the re-keying, not before it. (2)
- * `turns.json` persists each in-flight turn's `bufferKey` verbatim and this runs before turn recovery,
- * so a turn spanning the upgrade finds its bucket already gone. Sparing referenced keys would couple
- * the buffer to the turn store to protect a single upgrade, and would not help (1) at all.
- *
- * PERMANENT, unlike the `owned-threads.json` cleanup it otherwise resembles. That one leaves an inert
- * orphan file, so deleting it a release later is free; this one is what stops user chat content
- * lingering, and a deployment that skips from before the model to well after it would never run an
- * expired version of this code. The standing cost is one key scan at load, and nothing when no retired
- * key is present.
- */
-function dropRetiredBuckets(path, label) {
-    const raw = loadStateFile(path);
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
-        return;
-    const live = Object.entries(raw).filter(([placeKey]) => !placeKey.includes(":root:"));
-    const dropped = Object.keys(raw).length - live.length;
-    if (dropped === 0)
-        return;
-    log.info(`${label} dropped ${dropped} context bucket(s) with a retired key shape`);
-    try {
-        saveStateFile(path, Object.fromEntries(live));
-    }
-    catch (error) {
-        log.warn(`${label} could not rewrite ${path} after dropping retired buckets: ${String(error)}`);
-    }
-}
 export function createFeishuContextBuffer(path, label) {
-    dropRetiredBuckets(path, label);
     return createGenericContextBuffer({
         path,
         label,

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

@@ -1,5 +1,3 @@
-/** 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

package/dist/channels/feishu/crypto.js

@@ -14,13 +14,8 @@
  * 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);
-}
+import { createDecipheriv, createHash } from "node:crypto";
+import { secretEquals } from "../secret.js";
 /** 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
@@ -39,5 +34,5 @@ export function eventSignature(encryptKey, timestamp, nonce, rawBody) {
 }
 /** 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);
+    return secretEquals(headers.signature, eventSignature(encryptKey, headers.timestamp, headers.nonce, rawBody));
 }

package/dist/channels/feishu/feishu-api.js

@@ -14,13 +14,11 @@
  *  5. Every failure is a {@link FeishuApiError} naming the call; self-description is a property of the
  *     error type, not per-call-site string assembly.
  *
- * On top of the pipeline sit thin typed methods (send/reply/edit/card/resource) — adding one is adding
- * a wrapper, not wire code. SDK tripwire: if this surface ever needs WebSocket long-connection ingress
- * or grows past ~a dozen methods, adopt @larksuiteoapi/node-sdk instead of growing it — the methods
- * here are shape-compatible with the SDK's `client.im.*` style, so the policy layer survives that swap.
+ * Typed methods cover messages, cards, resources and app configuration. Proactive tools share this
+ * transport through shared-api.ts. The official SDK handles WebSocket ingress in ws-ingress.ts.
  */
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { attachmentPath } from "../kit/attachment-path.js";
 import { utf8Prefix } from "../kit/text.js";
 /** Per-attempt timeout for a JSON API call — small JSON round-trips, so 30s is generous. */
 const API_TIMEOUT_MS = 30_000;
@@ -283,13 +281,10 @@ export function createFeishuApi(opts) {
         },
         async fetchFile(messageId, fileKey, name, chatId, filesDir) {
             const { bytes } = await api.downloadResource(messageId, fileKey, "file");
-            // The name is external input destined for a filesystem path — keep only its basename-safe core.
-            const safe = name.replace(/[/\\]/g, "_").replace(/^\.+/, "_") || "file";
-            const dir = join(filesDir, chatId);
-            await mkdir(dir, { recursive: true });
-            const dest = join(dir, safe);
-            await writeFile(dest, bytes);
-            return { path: dest, name: safe, size: bytes.byteLength };
+            const dest = attachmentPath(filesDir, chatId, name);
+            await mkdir(dest.dir, { recursive: true });
+            await writeFile(dest.path, bytes);
+            return { path: dest.path, name: dest.name, size: bytes.byteLength };
         },
         async getAppConfig(appId) {
             // v6 app detail — the one read surface that returns the event-security material (under data.app).

package/dist/channels/feishu/feishu.js

@@ -12,15 +12,18 @@ import { isAbsolute, join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
+import { secretEquals } from "../secret.js";
 import { createSeenRing } from "../kit/seen.js";
 import { createTaskTracker } from "../kit/tasks.js";
 import { ensureStateHome, loadStateFile, saveStateFile } from "../kit/state.js";
+import { signatureIsFresh } from "../kit/signature.js";
 import { dispatchStop, isStopText } from "../kit/stop-command.js";
-import { createTurnQueue } from "../kit/turn-queue.js";
+import { createTurnRunner } from "../kit/turn-runner.js";
 import { createTurnStore } from "../kit/turn-store.js";
+import { discussionBlock } from "../kit/context-buffer.js";
 import { FEISHU_CLOUD } from "./cloud.js";
 import { collectFeishuBufferedAttachments, createFeishuContextBuffer, feishuBufferPlaceKey, feishuBufferText, } from "./context-buffer.js";
-import { decryptEvent, timingSafeEqualStr, verifySignature } from "./crypto.js";
+import { decryptEvent, verifySignature } from "./crypto.js";
 import { invokeFeishuTurn } from "./invoke-turn.js";
 import { createFeishuApi } from "./feishu-api.js";
 import { normalizeFeishuMessage } from "./normalize.js";
@@ -29,14 +32,20 @@ import { FEISHU_GROUP_CONTEXT_SCOPE, FEISHU_MESSAGE_READ_REQUEST, FEISHU_MESSAGE
 import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderId, senderLabel, } from "./parse.js";
 import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, streamFeishuReply, } from "./preview.js";
 import { connectFeishuWs } from "./ws-ingress.js";
+import { registerFeishuApi } from "./shared-api.js";
 // Canonical public surface; the Lark subpath aliases these types/functions at its compatibility boundary.
 export { defaultFeishuRoute, feishuEnvelope };
-/** Execution ceiling: a turn that has STARTED running this many times without finishing is dropped
- *  rather than run again (a poison turn must not loop forever under a restart policy). Counted per turn
- *  at dequeue, so a never-run turn queued behind a poison one keeps its full budget. */
-const MAX_TURN_ATTEMPTS = 3;
 /** Event body cap — events are small JSON; 1 MiB is generous and guards a public endpoint. */
 const MAX_EVENT_BYTES = 1 << 20;
+/**
+ * Replay window for a SIGNED event, sized by the OPEN PLATFORM'S REDELIVERY SCHEDULE, not by Slack's
+ * 5 minutes: a failed push is retried at 15s / 5min / 1h / 6h. It is not established whether a retry
+ * is re-signed with a fresh timestamp or replays the original one, and only the second case is safe
+ * to guess wrong about in one direction — a window under 6h would 401 three of the four retries, i.e.
+ * turn one transient fault into a permanently lost user message (and a callback-health alarm). Wide
+ * enough to cover the chain, still bounded, and the `seen` ring dedups an event_id inside it.
+ */
+const MAX_SIGNATURE_AGE_S = 7 * 60 * 60;
 /** Queue feedback is immediate by default: it is the user's acknowledgement that this exact ask was
  *  accepted behind another turn. The same reply-quoted card becomes the preview/final answer, so there
  *  is no extra message or recall tombstone to avoid. Authors may still configure a delay explicitly. */
@@ -72,16 +81,6 @@ export function feishuChannel(opts) {
 export function feishuWebSocketChannel(opts) {
     return buildFeishuWebSocketChannel(FEISHU_CLOUD, opts, feishuWebSocketChannel.name);
 }
-/** The participant model removed the session modes (docs/design/participant-model.md §12). An upgraded
- *  workspace still passing one would otherwise start fine and silently get different placement AND a
- *  different memory boundary — the one breaking change most likely to be hit, and invisible. */
-function rejectRemovedSessionOptions(opts, factoryName) {
-    const removed = ["directMessageSession", "groupMessageSession"].filter((name) => opts[name] !== undefined);
-    if (removed.length > 0) {
-        throw new Error(`${factoryName} no longer accepts ${removed.join(" / ")}: a chat is one session and a thread is another, ` +
-            "and the summon rule no longer depends on the mode — remove the option (see docs/design/participant-model.md)");
-    }
-}
 function createFeishuRuntimeFactory(profile, opts, factoryName) {
     const { appId, appSecret, route, onError, queueNoticeDelayMs = QUEUE_NOTICE_DELAY_MS } = opts;
     const baseUrl = opts.apiBaseUrl ?? profile.apiBase;
@@ -220,11 +219,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         });
         const seen = createSeenRing(join(stateHome, "seen.json"), label);
         // Side tasks (stop feedback) run off the ingress path but drain in turnsIdle.
-        const sideTasks = createTaskTracker();
-        const toStored = (r) => {
-            const { preview: _live, ...intent } = r; // drop the live-only field; TS enforces the rest is complete
-            return { ...intent, attempts: 0 };
-        };
+        const sideTasks = createTaskTracker(label);
         const targetOf = (r) => ({
             chatId: r.chatId,
             replyTo: r.replyTo,
@@ -235,18 +230,28 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             replyTo: r.queueReplyTo,
             replyInThread: r.replyInThread,
         });
-        // In-memory: the pending queue-preview mount per turn. Immediate by default; with an explicit delay,
-        // it mounts only if the turn is still waiting when the timer fires and is cancelled unsent otherwise.
-        // `done` settles either way, awaited at dequeue so the runner reliably receives the mounted preview
-        // instead of racing it and double-posting.
-        const notices = new Map();
-        const queue = createTurnQueue({
+        // Tell the asker when a turn is dropped at the execution ceiling: the chain's end needs a signal,
+        // not just an operator log line. Take over its queue preview in place if present (else send fresh) —
+        // leaving it pinned at "Queued" while sending a separate failure would double-post.
+        const notifyDropped = (r) => {
+            const body = "⚠️ I couldn’t complete an earlier request — please ask again.";
+            void settleFeishuPreview(api, targetOf(r), r.preview, body).catch((e) => log.warn(`${label} could not notify a dropped turn (session=${r.session}): ${String(e)}`));
+        };
+        const runner = createTurnRunner({
             label,
-            // Queue feedback: when this session already has a turn running/queued, a silent wait reads as
-            // "the bot ignored me" once the current turn runs long — mount that turn's preview early with a
-            // queue status. It reply-quotes the exact source message (including p2p), then the runner mutates
-            // the SAME card/text into Thinking → final answer. Best-effort and post-ACK: a failed mount is a
-            // log line, never a failed event delivery; the turn later mounts its normal preview.
+            store,
+            buffer,
+            seen,
+            toStored: ({ preview: _live, ...intent }) => ({ ...intent, attempts: 0 }),
+            fromStored: ({ attempts: _a, ...intent }) => ({ ...intent, preview: undefined }),
+            bufferKey: (rec) => rec.bufferKey,
+            where: (rec) => `chat=${rec.chatId}`,
+            // Queue feedback: mount that turn's preview early with a queue status. It reply-quotes the exact
+            // source message (including p2p), then the runner mutates the SAME card/text into Thinking →
+            // final answer. Immediate by default; with an explicit delay it mounts only if the turn is still
+            // waiting when the timer fires and is cancelled unsent otherwise. Best-effort and post-ACK: a
+            // failed mount is a log line, never a failed event delivery; the turn later mounts its normal
+            // preview.
             onQueuedBehind: (rec) => {
                 let fired = false;
                 let settle = () => { };
@@ -264,8 +269,9 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 const timer = queueNoticeDelayMs > 0 ? setTimeout(mount, queueNoticeDelayMs) : undefined;
                 if (timer === undefined)
                     mount();
-                notices.set(rec.id, {
-                    // Cancel is a no-op once mounting started — the send is in flight and `done` settles with it.
+                return {
+                    done,
+                    // A no-op once mounting started — the send is in flight and `done` settles with it.
                     cancel: () => {
                         if (!fired) {
                             if (timer !== undefined)
@@ -273,109 +279,47 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                             settle();
                         }
                     },
-                    done,
-                });
+                };
             },
-            run: async (rec) => {
-                // Runs at DEQUEUE time (serialized). The turn's queue wait is over: cancel a not-yet-mounted
-                // preview (fast turnover skips the Queued frame), then settle so rec.preview is final — in the
-                // common path this await is instant. BEFORE the ceiling check so drop/defer can take it over too.
-                const notice = notices.get(rec.id);
-                notice?.cancel();
-                await notice?.done;
-                notices.delete(rec.id);
-                // Count this execution against the durable record (poison-turn ceiling) before running it again.
-                const decision = store.startAttempt(rec.id, MAX_TURN_ATTEMPTS);
-                if (decision === "exceeded") {
-                    notifyDropped(rec);
-                    return;
-                }
-                if (decision === "defer") {
-                    // Couldn't record the attempt (disk failure): skip this cycle; a restart replays it. Do not
-                    // recall an existing queue preview (the client exposes a confusing tombstone): settle it in
-                    // place to an honest delayed status. The eventual replay mounts a fresh preview.
-                    if (rec.preview !== undefined) {
-                        void settleFeishuPreview(api, targetOf(rec), rec.preview, DEFERRED_PLACEHOLDER).catch((e) => log.warn(`${label} could not update a deferred turn's queue preview: ${String(e)}`));
-                    }
-                    return;
+            // Do not recall an existing queue preview (the client exposes a confusing tombstone): settle it in
+            // place to an honest delayed status. The eventual replay mounts a fresh preview.
+            onDeferred: (rec) => {
+                if (rec.preview !== undefined) {
+                    void settleFeishuPreview(api, targetOf(rec), rec.preview, DEFERRED_PLACEHOLDER).catch((e) => log.warn(`${label} could not update a deferred turn's queue preview: ${String(e)}`));
                 }
-                const startedAt = Date.now();
-                log.info(`${label} turn start: turn=${rec.id} session=${rec.session} chat=${rec.chatId}`);
-                // Snapshot background discussion at dequeue. Commit only this snapshot on `completed`, so a
-                // message arriving while the turn runs remains buffered for the next answered turn.
-                // ponytail: independent threaded roots in one main chat dequeue concurrently and may both fold
-                // this snapshot before either commits it. That fan-out loses nothing; claiming by buffer key
-                // would instead couple otherwise-independent root sessions and require failure rollback.
-                const { text: recent, consumed } = buffer.peek(rec.bufferKey);
+            },
+            notifyDropped,
+            execute: (rec, discussion, onCompleted) => {
                 // PEEK and never commit: the room still owes this discussion to its OWN memory (§8).
+                // ponytail: independent threaded roots in one main chat dequeue concurrently and may both fold
+                // the thread's snapshot before either commits it. That fan-out loses nothing; claiming by buffer
+                // key would instead couple otherwise-independent root sessions and require failure rollback.
                 const room = rec.roomBufferKey !== undefined ? buffer.peek(rec.roomBufferKey) : undefined;
                 const roomBlock = room?.text
                     ? `[recent discussion in the room this thread branched from — not yet answered there:\n${room.text}\n]\n\n`
                     : "";
-                const threadBlock = recent ? `[recent group discussion:\n${recent}\n]\n\n` : "";
-                const prompt = `${roomBlock}${threadBlock}${rec.baseText}`;
+                const prompt = `${roomBlock}${discussionBlock(discussion.text)}${rec.baseText}`;
                 // Room entries FIRST: the collector keeps the TAIL under its cap, so the thread's own
                 // attachments win the slots.
-                const buffered = collectFeishuBufferedAttachments([...(room?.consumed ?? []), ...consumed], {
+                const buffered = collectFeishuBufferedAttachments([...(room?.consumed ?? []), ...discussion.consumed], {
                     images: rec.images.map((ref) => ({ messageId: ref.msg, key: ref.key })),
                     files: rec.files.map((ref) => ({ messageId: ref.msg, key: ref.key, name: ref.name })),
                 });
                 // Recorded at ingress (see submit) — never re-derived from the session key, which may be a
                 // routed OPAQUE id that only looks like a place key.
                 const parentSession = rec.parentSession;
-                try {
-                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, {
-                        api,
-                        chatId: rec.chatId,
-                        filesDir: join(stateHome, "files"),
-                        label,
-                        appId,
-                        ...(parentSession !== undefined ? { parentSession } : {}),
-                    }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
-                        // Drop intent first: a crash between these writes may re-fold answered context later,
-                        // but can never replay this turn after its context was removed.
-                        store.remove(rec.id);
-                        buffer.commit(rec.bufferKey, consumed);
-                    }), api, targetOf(rec), formatError, rec.preview, label);
-                    log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
-                }
-                catch (error) {
-                    log.error(`${label} turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error)}`);
-                }
-                finally {
-                    // Fallback removal for the caught-error paths (a `failed` event or a transport throw): those
-                    // never reach the completed hook above. Idempotent — a second remove is a no-op. Only an
-                    // INTERRUPTED run (this finally never runs — a crash or SIGTERM deploy) leaves the record for
-                    // replay; a transport throw is dropped, not retried (safe retry needs an L2 delivery key).
-                    store.remove(rec.id);
-                }
+                return streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, {
+                    api,
+                    chatId: rec.chatId,
+                    filesDir: join(stateHome, "files"),
+                    label,
+                    appId,
+                    ...(parentSession !== undefined ? { parentSession } : {}),
+                }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, onCompleted), api, targetOf(rec), formatError, rec.preview, label);
             },
         });
-        // Accept a turn: persist its intent before the ACK, then record the platform delivery id and enqueue
-        // it. The ordering is deliberate: recording first could turn a failed intent write into silent loss
-        // when the platform redelivers. Recovery re-enqueues a crash survivor without re-persisting it.
-        const submit = (rec, persist) => {
-            if (persist) {
-                store.add(toStored(rec)); // failed write → HTTP/WS 500 → platform re-push
-                seen.add(rec.id); // post-persist, best-effort protection from documented duplicate pushes
-            }
-            queue.accept(rec);
-        };
-        // Tell the asker when a turn is dropped at the execution ceiling: the chain's end needs a signal,
-        // not just an operator log line. Take over its queue preview in place if present (else send fresh) —
-        // leaving it pinned at "Queued" while sending a separate failure would double-post.
-        const notifyDropped = (r) => {
-            const body = "⚠️ I couldn’t complete an earlier request — please ask again.";
-            void settleFeishuPreview(api, targetOf(r), r.preview, body).catch((e) => log.warn(`${label} could not notify a dropped turn (session=${r.session}): ${String(e)}`));
-        };
-        // Re-enqueue turns a prior crash left mid-flight (ACKed but unfinished). Synchronous at construction:
-        // the queue runs them on the next tick. The execution ceiling is enforced per turn at dequeue.
-        const recovered = store.recover();
-        if (recovered.length > 0)
-            log.info(`${label} recovering ${recovered.length} unfinished turn(s) from a prior run`);
-        let seqCounter = recovered.reduce((max, r) => Math.max(max, r.seq), 0);
-        for (const { attempts: _a, ...intent } of recovered)
-            submit({ ...intent, preview: undefined }, false);
+        registerFeishuApi(stateRoot, kind, api);
+        let seqCounter = runner.recover().reduce((max, r) => Math.max(max, r.seq), 0);
         // Who the agent has heard in a thread decides whether a bare message addresses it (participant
         // model §3), and it comes from what this channel observed — see thread-participants.ts.
         let warnedUnidentified = false;
@@ -523,7 +467,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             const baseText = r.text ?? cloudEnvelope(event, kind);
             if (baseText.trim() === "" && images.length === 0 && files.length === 0)
                 return;
-            submit({
+            runner.submit({
                 id: m.message_id,
                 seq: ++seqCounter, // arrival order; the turn store replays by it
                 session,
@@ -576,13 +520,19 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 threadParticipants.merge(heard.key, { agentSpoke: true, humans: [heard.speaker] });
             }
         };
-        return { acceptEvent, turnsIdle: () => Promise.all([queue.idle(), sideTasks.drain()]).then(() => undefined) };
+        return { acceptEvent, turnsIdle: () => Promise.all([runner.idle(), sideTasks.drain()]).then(() => undefined) };
     };
 }
 function createFeishuWebhookRoutes(profile, opts, runtime) {
     const { verificationToken, encryptKey } = opts;
     const { kind, envPrefix } = profile;
     const label = `[${kind}]`;
+    if (!encryptKey) {
+        // Said once at wiring, not per request: without an encrypt key events arrive in plaintext and
+        // carry no signature, so the freshness window below never runs and a captured body replays for
+        // as long as the verification token lives.
+        log.warn(`${label} no ${envPrefix}_ENCRYPT_KEY: events are accepted unsigned, with no replay window — set one in the console to enable it`);
+    }
     const handler = async (req) => {
         if (req.method !== "POST")
             return text("POST only\n", 405);
@@ -609,9 +559,19 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
                 nonce: req.headers.get("x-lark-request-nonce") ?? "",
                 signature: req.headers.get("x-lark-signature") ?? "",
             };
-            if (sig.signature && !verifySignature(encryptKey, sig, body.text)) {
-                log.warn(`${label} rejected an event: invalid X-Lark-Signature (encrypt key mismatch, or a forgery)`);
-                return text("invalid signature\n", 401);
+            if (sig.signature) {
+                // Freshness BEFORE the signature: the signature covers the timestamp but proves nothing about
+                // it, so without a window a captured body + its three x-lark-* headers replays forever. The
+                // `seen` ring is not that defence — it is bounded, and past its rollover a replay re-runs the
+                // turn (a re-sent message, a re-fired tool).
+                if (!signatureIsFresh(sig.timestamp, MAX_SIGNATURE_AGE_S)) {
+                    log.warn(`${label} rejected an event: X-Lark-Request-Timestamp outside the ±${MAX_SIGNATURE_AGE_S / 3600} h replay window`);
+                    return text("stale signature\n", 401);
+                }
+                if (!verifySignature(encryptKey, sig, body.text)) {
+                    log.warn(`${label} rejected an event: invalid X-Lark-Signature (encrypt key mismatch, or a forgery)`);
+                    return text("invalid signature\n", 401);
+                }
             }
             try {
                 envelope = JSON.parse(decryptEvent(encryptKey, outer.encrypt));
@@ -639,7 +599,7 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
             (typeof envelope.header?.token === "string"
                 ? envelope.header.token
                 : undefined);
-        if (!token || !timingSafeEqualStr(token, verificationToken)) {
+        if (!secretEquals(token, verificationToken)) {
             log.warn(`${label} rejected an event: verification token mismatch (check ${envPrefix}_VERIFICATION_TOKEN against the console)`);
             return text("invalid token\n", 401);
         }
@@ -659,7 +619,6 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
     return { [`POST /${kind}`]: handler };
 }
 export function buildFeishuChannel(profile, opts, factoryName) {
-    rejectRemovedSessionOptions(opts, factoryName);
     const createRuntime = createFeishuRuntimeFactory(profile, opts, factoryName);
     return (ctx) => {
         if (!opts.verificationToken) {
@@ -669,7 +628,6 @@ export function buildFeishuChannel(profile, opts, factoryName) {
     };
 }
 export function buildFeishuWebSocketChannel(profile, opts, factoryName, deps = {}) {
-    rejectRemovedSessionOptions(opts, factoryName);
     const createRuntime = createFeishuRuntimeFactory(profile, opts, factoryName);
     return {
         name: `${profile.kind} websocket`,

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

@@ -35,9 +35,10 @@ export declare function senderId(sender: FeishuSender | undefined): string | und
  *
  * Branded with the channel kind, like Slack's twin, because session ids share ONE namespace across
  * every channel in a deployment: without it a `feishu` and a `lark` chat carrying the same platform id
- * would answer into the same memory. The length bound is the FILENAME the id becomes (sessions.ts
- * percent-encodes it, so each `:` costs three), and the worst case here — brand + a 35-char chat id +
- * a 36-char thread id — encodes to well under 100 bytes against the filesystem's 255.
+ * would answer into the same memory. The length bound is the FILENAME the id becomes (session-store.ts
+ * `piSessionId` escapes every character outside `[A-Za-z0-9.-]` as `_XX` / `_uXXXX`, so each `:` costs
+ * three), and the worst case here — brand + a 35-char chat id + a 36-char thread id — encodes to well
+ * under 100 bytes against the filesystem's 255.
  */
 export declare function placeKey(kind: string, message: Pick<FeishuMessage, "chat_id" | "thread_id">): string;
 /** The canonical Feishu-branded prompt envelope. */

package/dist/channels/feishu/parse.js

@@ -30,9 +30,10 @@ export function senderId(sender) {
  *
  * Branded with the channel kind, like Slack's twin, because session ids share ONE namespace across
  * every channel in a deployment: without it a `feishu` and a `lark` chat carrying the same platform id
- * would answer into the same memory. The length bound is the FILENAME the id becomes (sessions.ts
- * percent-encodes it, so each `:` costs three), and the worst case here — brand + a 35-char chat id +
- * a 36-char thread id — encodes to well under 100 bytes against the filesystem's 255.
+ * would answer into the same memory. The length bound is the FILENAME the id becomes (session-store.ts
+ * `piSessionId` escapes every character outside `[A-Za-z0-9.-]` as `_XX` / `_uXXXX`, so each `:` costs
+ * three), and the worst case here — brand + a 35-char chat id + a 36-char thread id — encodes to well
+ * under 100 bytes against the filesystem's 255.
  */
 export function placeKey(kind, message) {
     const chat = `${kind}:${message.chat_id}`;
@@ -54,7 +55,7 @@ export function cloudEnvelope(event, tag) {
         from ? `from ${from}` : undefined,
         // The message's own id is LOAD-BEARING, not decoration: it is the only way this message's id
         // enters the session transcript, and session inheritance locates a thread's branch point by
-        // searching the parent transcript for exactly these ids (scope.branchHints — sessions.ts).
+        // searching the parent transcript for exactly these ids (scope.branchHints — session-inheritance.ts).
         // Remove it and every thread quietly inherits from the room's present instead of the branch
         // point. It also lets the model name what it is answering in a busy chat.
         `msg ${message.message_id}`,