@fastagent-sh/fastagent 0.20.0 → 0.21.0

package/dist/channels/control.js

@@ -1,10 +1,11 @@
 import { INVALID_COMMAND_CODE, SESSIONS_UNAVAILABLE_CODE, UNSUPPORTED_CAPABILITY_CODE, UPDATE_FIELDS, } from "../session.js";
-import { timingSafeEqual } from "node:crypto";
 import { parseRouteKey, withoutBody } from "./serve.js";
 import { log } from "../log.js";
 import { readBodyCapped } from "./body.js";
-import { MAX_BODY_BYTES, createInvokeHandler, sseHeartbeat } from "./http.js";
+import { MAX_BODY_BYTES, createInvokeHandler } from "./http.js";
+import { sseResponse } from "./sse.js";
 import { text } from "./respond.js";
+import { secretEquals } from "./secret.js";
 /** The prefix this plane OWNS: everything under it is the plane's to answer. */
 const CONTROL_PREFIX = "/control";
 /** The one variable segment in this plane's paths: a percent-encoded session id. Written into route
@@ -266,13 +267,10 @@ export function controlPlaneRoutes(control, options) {
     if (!token)
         throw new Error("createControlPlane: a bearer token is required (empty tokens are not a mode)");
     const epoch = crypto.randomUUID();
-    // Timing-safe: the bearer token is this surface's ONLY auth (and the --tunnel warning names it
-    // as the sole protection on a public URL) — a plain === would leak byte-by-byte via timing.
-    const expected = Buffer.from(`Bearer ${token}`);
-    const authed = (req) => {
-        const header = Buffer.from(req.headers.get("authorization") ?? "");
-        return header.length === expected.length && timingSafeEqual(header, expected);
-    };
+    // The bearer token is this surface's ONLY auth (and the --tunnel warning names it as the sole
+    // protection on a public URL).
+    const expected = `Bearer ${token}`;
+    const authed = (req) => secretEquals(req.headers.get("authorization"), expected);
     const invokeHandler = options.agent ? createInvokeHandler(options.agent) : undefined;
     /** Authenticate, then hand the handler the pieces every route wants: the request, the URL (for
      *  query parameters), and the session the PATH named — `""` on the routes that have no id in
@@ -404,60 +402,13 @@ export function controlPlaneRoutes(control, options) {
             }
         }),
         [`GET /control/sessions/${SESSION_SEGMENT}/events`]: guard((_req, _url, session) => {
-            const iterator = control.sessions.get(session).events()[Symbol.asyncIterator]();
-            // EAGER registration: issue the first pull NOW, before the Response (and thus the client's
-            // fetch resolution) exists — hub subscription is registered synchronously inside next(), so
-            // "the client saw response headers" implies "events from that moment on will be delivered".
-            // Shrinks the subscribe/backfill race to network reordering instead of a full pull cycle.
-            let pending = iterator.next();
-            // Observed here so a client that disconnects BEFORE the first pull cannot turn a rejecting
-            // events iterator (this is the neutral contract face — any implementation may reject) into a
-            // process-killing unhandledRejection; awaiting `pending` at pull still surfaces the error.
-            pending.catch(() => { });
             let seq = 0;
-            let stopHeartbeat = () => { };
-            const encoder = new TextEncoder();
-            const stream = new ReadableStream({
-                start(controller) {
-                    stopHeartbeat = sseHeartbeat(controller);
-                },
-                async pull(controller) {
-                    let next;
-                    try {
-                        next = await (pending ?? iterator.next());
-                    }
-                    catch (error) {
-                        // A rejecting implementation (the neutral contract permits it) must not leak its
-                        // subscription: an errored stream never gets cancel(), so the unsubscribe and the
-                        // heartbeat teardown happen HERE.
-                        stopHeartbeat();
-                        void iterator.return?.(undefined)?.catch?.(() => { });
-                        controller.error(error);
-                        return;
-                    }
-                    pending = undefined;
-                    if (next.done) {
-                        stopHeartbeat();
-                        controller.close();
-                        return;
-                    }
-                    const wire = { sessionId: session, epoch, seq: seq++, event: next.value };
-                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(wire)}\n\n`));
-                },
-                cancel() {
-                    stopHeartbeat();
-                    // Same neutral-contract defense as the pull error path: a rejecting return() on client
-                    // disconnect must not become a process-level unhandledRejection.
-                    void iterator.return?.(undefined)?.catch?.(() => { });
-                },
-            });
-            return new Response(stream, {
-                headers: {
-                    "content-type": "text/event-stream",
-                    "cache-control": "no-cache",
-                    connection: "keep-alive",
-                },
-            });
+            return sseResponse(control.sessions.get(session).events(), (event) => ({
+                sessionId: session,
+                epoch,
+                seq: seq++,
+                event,
+            }));
         }),
     };
 }

package/dist/channels/discover.d.ts

@@ -53,7 +53,6 @@ export declare function loadChannels(dir: string, ctx: ChannelContext): Promise<
     routes: Routes;
     longConnections: LoadedLongConnectionChannel[];
     routeChannels: string[];
-    longConnectionChannels: string[];
     collisions: ChannelCollision[];
     failures: ModuleLoadFailure[];
 }>;

package/dist/channels/discover.js

@@ -85,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 {
@@ -96,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") {
@@ -124,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,10 +14,8 @@
  *  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 { attachmentPath } from "../kit/attachment-path.js";

package/dist/channels/feishu/feishu.js

@@ -12,17 +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 { commitAnsweredTurn, createTurnStore } from "../kit/turn-store.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";
@@ -31,6 +32,7 @@ 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 };
 /** Event body cap — events are small JSON; 1 MiB is generous and guards a public endpoint. */
@@ -79,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;
@@ -228,10 +220,6 @@ 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(label);
-        const toStored = (r) => {
-            const { preview: _live, ...intent } = r; // drop the live-only field; TS enforces the rest is complete
-            return { ...intent, attempts: 0 };
-        };
         const targetOf = (r) => ({
             chatId: r.chatId,
             replyTo: r.replyTo,
@@ -242,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 = () => { };
@@ -271,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)
@@ -280,103 +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);
-                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 prompt = `${roomBlock}${discussionBlock(recent)}${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 }, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey: 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;
@@ -524,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,
@@ -577,7 +520,7 @@ 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) {
@@ -656,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);
         }
@@ -676,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) {
@@ -686,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}`,

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

@@ -1,9 +1,10 @@
-import type { RegistrationOutcome } from "../registration.ts";
+import { type RegistrationOutcome } from "../registration.ts";
 import { type FeishuCloudKind } from "./cloud.ts";
 /**
  * Register `<baseUrl>/<kind>` as the app's event Request URL (webhook mode). Missing credentials print
- * the manual instruction instead of failing. `opts` exist for tests: timeouts + `apiBase` (a fake
- * platform — production derives it from the kind).
+ * the manual instruction instead of failing. `opts` carries the attempt budget — `--tunnel` takes the
+ * default, `deploy --run` passes `DEPLOY_REGISTRATION_ATTEMPTS` (a host starts slower than a tunnel) —
+ * plus `apiBase`, which is a test's fake platform (production derives it from the kind).
  *
  * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
@@ -12,8 +13,7 @@ interface FeishuManualRegistration {
     requestUrl: string;
 }
 export interface RegisterFeishuWebhookOptions {
-    readyTimeoutMs?: number;
-    readyIntervalMs?: number;
+    attempts?: number;
     retryMs?: number;
     apiBase?: string;
     /** Manual fallback after a definitive config error or exhausted retries. Local dev opens this App. */