@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/channels/feishu/feishu.js

@@ -1,18 +1,21 @@
 /**
- * Canonical Feishu bot-channel engine: verify webhook → answer url_verification → dedup → route → persist → run
- * the turn → stream a live card → ACK 200. Feishu (open.feishu.cn) is the reference cloud. Lark
+ * Canonical Feishu bot-channel engine: verified webhook or official-SDK WebSocket → dedup → route →
+ * persist → enqueue → stream a live card. Feishu (open.feishu.cn) is the reference cloud. Lark
  * international binds this engine through an explicit compatibility profile because its control plane
  * trails Feishu; protocol reuse does not make Lark the design center.
  *
  * The channel kind remains the unit of route, env namespace, state home, logs, and onboarding, so one
- * workspace may mount both without sharing state. Webhook mode only; WebSocket long connection needs
- * the official SDK and a non-HTTP ingress seam. See docs/feishu.md.
+ * workspace may run both without sharing state. Webhook returns the existing route factory; WebSocket
+ * returns an explicit long-connection module. Both feed the same acceptance/turn engine. See docs/feishu.md.
  */
 import { isAbsolute, join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
-import { ensureStateHome } from "../state.js";
+import { createSeenRing } from "../seen.js";
+import { createTaskTracker } from "../tasks.js";
+import { ensureStateHome, removeRetiredStateFile } from "../state.js";
+import { dispatchStop, isStopText } from "../stop-command.js";
 import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "../turn-store.js";
 import { FEISHU_CLOUD } from "./cloud.js";
@@ -21,10 +24,11 @@ import { decryptEvent, timingSafeEqualStr, verifySignature } from "./crypto.js";
 import { invokeFeishuTurn } from "./invoke-turn.js";
 import { createFeishuApi } from "./feishu-api.js";
 import { normalizeFeishuMessage } from "./normalize.js";
-import { createOwnedFeishuThreads } from "./owned-threads.js";
-import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderLabel, } from "./parse.js";
+import { createThreadParticipants } from "../thread-participants.js";
+import { FEISHU_GROUP_CONTEXT_SCOPE, FEISHU_MESSAGE_READ_REQUEST, FEISHU_MESSAGE_READ_SCOPE, scopeSatisfied, } from "./setup-mode.js";
+import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderId, senderLabel, } from "./parse.js";
 import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, streamFeishuReply, } from "./preview.js";
-import { createSeenRing } from "./seen.js";
+import { connectFeishuWs } from "./ws-ingress.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
@@ -48,7 +52,7 @@ function isStoredFeishuTurn(t) {
         typeof r.seq === "number" &&
         typeof r.session === "string" &&
         typeof r.baseText === "string" &&
-        (r.bufferKey === undefined || typeof r.bufferKey === "string") &&
+        typeof r.bufferKey === "string" &&
         typeof r.chatId === "string" &&
         (r.replyTo === undefined || typeof r.replyTo === "string") &&
         (r.queueReplyTo === undefined || typeof r.queueReplyTo === "string") &&
@@ -58,40 +62,66 @@ function isStoredFeishuTurn(t) {
         refs(r.files) &&
         typeof r.attempts === "number");
 }
-/** Build the canonical Feishu channel. Lark calls the internal profile-bound builder below. */
+/** Build the canonical Feishu Request-URL webhook channel. */
 export function feishuChannel(opts) {
     return buildFeishuChannel(FEISHU_CLOUD, opts, feishuChannel.name);
 }
-/** Internal compatibility seam: protocol behavior comes from Feishu; the profile binds cloud edges. */
-export function buildFeishuChannel(profile, { appId, appSecret, verificationToken, encryptKey, directMessageSession = "threaded", groupMessageSession = "threaded", route, onError, baseUrl = profile.apiBase, queueNoticeDelayMs = QUEUE_NOTICE_DELAY_MS, }, factoryName) {
-    const { kind, envPrefix } = profile;
-    const label = `[${kind}]`;
-    // All three are mandatory: without the app credentials no reply can be sent; without the verification
-    // token a plaintext-mode endpoint would accept forged events. Fail at construction (startup), not
-    // silently at the first event.
-    if (!appId || !appSecret) {
-        throw new Error(`${factoryName} requires appId + appSecret (developer console → Credentials & Basic Info)`);
-    }
-    if (!verificationToken) {
-        throw new Error(`${factoryName} requires a non-empty verificationToken (console → Events & Callbacks; an unset one accepts forged events)`);
-    }
-    if (directMessageSession !== "continuous" && directMessageSession !== "threaded") {
-        throw new Error(`${factoryName} directMessageSession must be "continuous" or "threaded"`);
-    }
-    if (groupMessageSession !== "continuous" && groupMessageSession !== "threaded") {
-        throw new Error(`${factoryName} groupMessageSession must be "continuous" or "threaded"`);
+/** Build the canonical Feishu WebSocket long-connection channel. */
+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)");
     }
-    return ({ agent, stateRoot }) => {
+}
+function createFeishuRuntimeFactory(profile, opts, factoryName) {
+    const { appId, appSecret, route, onError, queueNoticeDelayMs = QUEUE_NOTICE_DELAY_MS } = opts;
+    const baseUrl = opts.apiBaseUrl ?? profile.apiBase;
+    const { kind } = profile;
+    const label = `[${kind}]`;
+    return ({ agent, stateRoot, control }) => {
+        // Credential checks run when serving starts, not while the authored module is imported: deployment
+        // can inspect the module shape before secrets exist, while serving still fails before ready.
+        if (!appId || !appSecret) {
+            throw new Error(`${factoryName} requires appId + appSecret (developer console → Credentials & Basic Info)`);
+        }
         const formatError = onError ?? defaultErrorMessage;
         const api = createFeishuApi({ kind, baseUrl, appId, appSecret });
         // One bot/v3/info at startup: the bot's open_id drives the default route's group @mention summon.
-        // Until it resolves (or if it fails), group summon stays off — fail-closed — while p2p works.
+        // Until it resolves (or if it fails), group summon stays off — fail-closed — while p2p works. A
+        // mention landing in that first moment is buffered as context rather than answered; it is folded
+        // into the next answered turn in that place, so the ask is delayed, never lost.
         let botOpenId;
         void api.botInfo().then((me) => {
             botOpenId = me.openId;
             if (!botOpenId)
                 log.warn(`${label} bot/v3/info returned no open_id — group @mention summon stays off`);
         }, (e) => log.warn(`${label} bot/v3/info failed; group @mention summon stays off until restart: ${String(e)}`));
+        void api.listAppScopes().then((scopes) => {
+            const grantedScope = (name) => scopes.some((scope) => scope.name === name && scope.grantStatus === 1 && (scope.type === undefined || scope.type === "tenant"));
+            if (grantedScope(FEISHU_GROUP_CONTEXT_SCOPE)) {
+                // This scope settles the rule's whole input: it delivers the un-mentioned group messages the
+                // channel buffers, which is also what lets it HEAR a thread. Nothing is fetched, so nothing
+                // is pending — the only bootstrap left is social, one mention inside a thread. The read scope
+                // is a separate, softer dependency, so it is reported separately rather than folded in.
+                log.info(`${label} group visibility: context-aware — buffered discussion enabled; bare replies work in a thread once the agent has been mentioned in it`);
+            }
+            else {
+                log.warn(`${label} group visibility: @mentions only — ${FEISHU_GROUP_CONTEXT_SCOPE} is not granted; bare replies in the agent's threads + group context buffering are unavailable`);
+            }
+            // Reported OUTSIDE the branch above: the quoted-message read runs in every chat type and every
+            // posture (a p2p thread's opening ask, any quoted @mention in a group), so pairing this warning
+            // with the group scope would leave a mention-only deployment silently losing every referent.
+            if (!scopeSatisfied(FEISHU_MESSAGE_READ_REQUEST, grantedScope)) {
+                log.warn(`${label} ${FEISHU_MESSAGE_READ_SCOPE} is not granted — a message quoted by an ask cannot be read, and degrades to a marker in the prompt`);
+            }
+        }, (error) => log.warn(`${label} could not inspect group visibility: ${String(error)}`));
         const decide = route ?? ((event) => defaultFeishuRoute(event, { botOpenId }));
         // The channel-state convention: this channel's durable home is `<stateRoot>/channels/<kind>`
         // (engine state at the root, channel state under `channels/<kind>/`) — derived, not an option, so
@@ -100,8 +130,16 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
             throw new Error(`${factoryName} requires an absolute ctx.stateRoot, got "${stateRoot}"`);
         }
         const stateHome = join(stateRoot, "channels", kind);
-        ensureStateHome(stateHome); // create + self-ignore — buffers/files may carry chat content
-        const ownedThreads = createOwnedFeishuThreads(join(stateHome, "owned-threads.json"), label);
+        ensureStateHome(stateHome); // buffers/files may carry chat content; the agent .gitignore covers .state/
+        // The participant model replaced the owned-thread index (a cache, so nothing is lost). REMOVE THIS
+        // after the release following the participant model ships — by then no live deployment can still
+        // be carrying the file. test/migration-deadline.test.ts fails when due.
+        removeRetiredStateFile(stateHome, "owned-threads.json", label);
+        const threadParticipants = createThreadParticipants(join(stateHome, "thread-participants.json"), label);
+        /** This channel's place key for a thread (the shared store is key-agnostic). */
+        // The SAME identity the session uses (`placeKey`) — a thread's place. Defining it twice would let a
+        // future re-keying silently split participation from the sessions it is supposed to describe.
+        const threadKey = (chatId, threadId) => placeKey(kind, { chat_id: chatId, thread_id: threadId });
         const buffer = createFeishuContextBuffer(join(stateHome, "buffers.json"), label);
         const store = createTurnStore(join(stateHome, "turns.json"), {
             label,
@@ -109,6 +147,8 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
             order: (a, b) => a.seq - b.seq,
         });
         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 };
@@ -226,7 +266,7 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
         // 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 → webhook 500 → platform redelivery
+                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);
@@ -244,122 +284,73 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
         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) {
-            // A pre-buffer-version record has no trustworthy place identity. Give it an empty private bucket
-            // rather than risk consuming new main-chat context that arrived after this restart.
-            const bufferKey = intent.bufferKey ?? `${intent.chatId}:legacy-turn:${intent.id}`;
-            submit({ ...intent, bufferKey, preview: undefined }, false);
-        }
-        const handler = async (req) => {
-            if (req.method !== "POST")
-                return text("POST only\n", 405);
-            const body = await readBodyCapped(req, MAX_EVENT_BYTES);
-            if ("tooLarge" in body)
-                return text("payload too large\n", 413);
-            let outer;
-            try {
-                outer = JSON.parse(body.text);
-                if (typeof outer !== "object" || outer === null)
-                    throw new Error("not an object");
-            }
-            catch {
-                return text("invalid json\n", 400);
-            }
-            // ── Verification. Two modes, decided by the CONSOLE's Encrypt Key setting, mirrored here. ──────
-            let envelope;
-            if (typeof outer.encrypt === "string") {
-                if (!encryptKey) {
-                    log.error(`${label} received an ENCRYPTED event but no encryptKey is configured — set ${envPrefix}_ENCRYPT_KEY`);
-                    return text("encrypt key not configured\n", 400);
-                }
-                const sig = {
-                    timestamp: req.headers.get("x-lark-request-timestamp") ?? "",
-                    nonce: req.headers.get("x-lark-request-nonce") ?? "",
-                    signature: req.headers.get("x-lark-signature") ?? "",
-                };
-                // Ordinary encrypted events MUST verify the signature over the raw body before decryption.
-                // Feishu's documented exception is Request URL verification: its encrypted challenge carries
-                // no event-signature headers, so it is decrypted first and admitted ONLY when its type is
-                // url_verification; the common constant-time Token check below then authenticates it.
-                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);
-                }
-                try {
-                    envelope = JSON.parse(decryptEvent(encryptKey, outer.encrypt));
-                }
-                catch {
-                    if (!sig.signature) {
-                        log.warn(`${label} rejected an unsigned encrypted request that could not be decrypted`);
-                        return text("invalid encrypted payload\n", 401);
-                    }
-                    return text("invalid encrypted payload\n", 400);
-                }
-                if (!sig.signature && envelope.type !== "url_verification") {
-                    log.warn(`${label} rejected an encrypted event: missing X-Lark-Signature`);
-                    return text("invalid signature\n", 401);
-                }
-            }
-            else {
-                if (encryptKey) {
-                    // With an Encrypt Key configured, a PLAINTEXT event can only be a forgery (or a console
-                    // mismatch — surfaced in the log): accepting it would let a sender skip the signature.
-                    log.warn(`${label} rejected a plaintext event while encryptKey is set (console mismatch, or a forgery)`);
-                    return text("plaintext events not accepted\n", 401);
-                }
-                envelope = outer;
-            }
-            // The Verification Token authenticates plaintext mode and the platform-documented unsigned,
-            // encrypted URL challenge; on signed encrypted events it is defense in depth. V2 events carry it
-            // in header.token, while url_verification carries it at the top level. Fail closed when absent.
-            const token = (typeof envelope.token === "string" ? envelope.token : undefined) ??
-                (typeof envelope.header?.token === "string"
-                    ? envelope.header.token
-                    : undefined);
-            if (!token || !timingSafeEqualStr(token, verificationToken)) {
-                // Loud on purpose: the send side gets an opaque 401 and the platform just retries — this line is
-                // the operator's ONLY signal that LARK_VERIFICATION_TOKEN does not match the console.
-                log.warn(`${label} rejected an event: verification token mismatch (check ${envPrefix}_VERIFICATION_TOKEN against the console)`);
-                return text("invalid token\n", 401);
-            }
-            // ── The console's URL-verification challenge (fires when the operator saves the Request URL). ──
-            if (envelope.type === "url_verification" && typeof envelope.challenge === "string") {
-                // The console fires this when the operator saves the Request URL; without this line a PASSING
-                // handshake is invisible and "did the challenge even arrive?" becomes guesswork.
-                log.info(`${label} answered the console's url_verification challenge`);
-                return Response.json({ challenge: envelope.challenge });
-            }
-            // ── Events. Only im.message.receive_v1 is consumed; everything else is ACKed and dropped
-            // (a non-2xx would just make the platform retry an event this channel will never act on). ──────
-            const header = envelope.header;
-            if (header?.event_type !== "im.message.receive_v1") {
-                log.debug(`${label} ignoring event type ${header?.event_type ?? "(none)"}`);
-                return new Response(null, { status: 200 });
+        for (const { attempts: _a, ...intent } of recovered)
+            submit({ ...intent, preview: undefined }, false);
+        // 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;
+        /**
+         * What this delivery contributes to thread participation, or undefined when it contributes nothing.
+         *
+         * ONE gate for BOTH writes (the humans observation on the way in, and the `agentSpoke` merge once
+         * the turn is durable), and one definition of the synthetic speaker id — hand-written conditions in
+         * two places is the drift that has already bitten this branch once. Structural facts only; see
+         * thread-participants.ts for why configuration must not appear here.
+         *
+         * Feishu-specific: p2p is excluded (nothing reads those records), and a custom route may admit a
+         * bot the default route filters out — answering one is not participation the summon rule should
+         * act on, so such a thread keeps no record and the first human still needs the mention bootstrap.
+         */
+        const heardIn = (m, sender) => {
+            if (m.chat_type !== "group" || m.thread_id === undefined || sender?.sender_type !== "user")
+                return undefined;
+            const speakerId = senderId(sender);
+            if (speakerId === undefined && !warnedUnidentified) {
+                // Once per MOUNT — the flag lives in this channel's closure on purpose: the condition is a
+                // property of THIS app's event configuration, so a `feishu` and a `lark` mount must each be
+                // able to report it. A per-thread set would instead grow without bound to repeat one fact.
+                warnedUnidentified = true;
+                log.warn(`${label} human senders arrive with no usable id (first seen in thread ${m.thread_id}) — each counts as a distinct speaker, so affected threads permanently require an @mention until thread-participants.json is deleted`);
             }
-            const event = (envelope.event ?? {});
+            // A human whose id no tenant flavour carries still SPOKE, and no human may speak unrecorded. A
+            // per-MESSAGE synthetic id keeps them distinct; a per-thread one would collapse every human on an
+            // id-less tenant into one, which is the direction that barges into a crowd. Its cost is PERMANENT
+            // — two such messages fill MAX_HUMANS and records never shed, so that thread needs an @mention
+            // from then on and only deleting the file resets it (§3).
+            return { key: threadKey(m.chat_id, m.thread_id), speaker: speakerId ?? `unidentified:${m.message_id}` };
+        };
+        // Transport-neutral acceptance boundary: normalize, route, persist intent/context, enqueue. It
+        // touches no network, so it stays synchronous inside the platform's ACK window and the delivery
+        // dedup ring alone is enough — there is no await for a duplicate push to race through. The
+        // minutes-long Agent turn remains fire-and-forget.
+        const acceptEvent = (event) => {
             const m = event.message;
             if (!m?.message_id || !m.chat_id)
-                return new Response(null, { status: 200 });
+                return;
             if (seen.has(m.message_id)) {
                 log.debug(`${label} duplicate push for message ${m.message_id} — already persisted, skipping`);
-                return new Response(null, { status: 200 });
+                return;
             }
             let r = decide(event);
             const normalized = normalizeFeishuMessage(event);
             if (!normalized)
-                return new Response(null, { status: 200 });
+                return;
             const bufferKey = feishuBufferPlaceKey(normalized.conversation);
             const isHumanGroup = event.sender?.sender_type === "user" && m.chat_type === "group";
-            const managedThread = groupMessageSession === "threaded" &&
+            // Listening is not speaking: every message the channel can see refines who takes part in its
+            // thread, whether or not it is answered. The sender counts toward the rule immediately — a
+            // second human speaking is exactly what makes addressing ambiguous again.
+            const heard = heardIn(m, event.sender);
+            if (heard)
+                threadParticipants.merge(heard.key, { humans: [heard.speaker] });
+            if (!r &&
+                route === undefined &&
                 isHumanGroup &&
                 m.thread_id !== undefined &&
-                m.root_id !== undefined &&
-                ownedThreads.has(m.chat_id, m.root_id);
-            // In an Agent-created thread, a bare user continuation still summons. Any explicit mention changes
-            // that intent: only defaultFeishuRoute's structural @THIS-bot match summons; @other-only discussion
-            // is buffered like unsummoned group context. A custom route remains fully authoritative.
-            if (!r && route === undefined && managedThread && !normalized.content.hasMentions)
+                !normalized.content.hasMentions &&
+                threadParticipants.admitsBareMessage(threadKey(m.chat_id, m.thread_id))) {
                 r = {};
+            }
             if (!r) {
                 if (route === undefined && isHumanGroup) {
                     const bodyText = feishuBufferText(normalized.content.text);
@@ -375,7 +366,8 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
                             key: resource.key,
                             name: resource.name,
                         }));
-                        // Pre-ACK persistence: a write failure rejects the webhook so the platform can redeliver.
+                        // A write failure escapes this boundary. HTTP turns it into a 500 response; the official WS
+                        // SDK turns it into a 500 ACK frame. Both transports therefore ask the platform to re-push.
                         buffer.push(bufferKey, {
                             sender: senderLabel(event.sender) ?? "someone",
                             body: bodyText,
@@ -384,7 +376,7 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
                             files: files.length ? files : undefined,
                             images: images.length ? images : undefined,
                         });
-                        seen.add(m.message_id); // post-persist: a redelivery cannot duplicate buffered context
+                        seen.add(m.message_id);
                         log.debug(`${label} buffered unsummoned group message ${m.message_id} (place ${bufferKey})`);
                     }
                     else {
@@ -394,79 +386,198 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
                 else {
                     log.debug(`${label} not summoned — ignoring message ${m.message_id} (chat ${m.chat_id}, ${m.chat_type})`);
                 }
-                return new Response(null, { status: 200 });
+                return;
             }
-            {
-                const threadedP2p = directMessageSession === "threaded" && m.chat_type === "p2p";
-                const threadedGroup = groupMessageSession === "threaded" && m.chat_type === "group";
-                const threadedConversation = threadedP2p || threadedGroup;
-                // A top-level threaded message has no thread_id yet. Its tenant-unique message_id is therefore
-                // the only identity available both before and after the first reply creates the thread.
-                // Continuations carry that same value as root_id (field-verified on Feishu p2p; shared protocol
-                // shape for groups/Lark). Prefix with the channel kind to isolate Feishu/Lark while keeping pi's
-                // provider-facing session/cache key under 64 characters.
-                if (threadedConversation && m.thread_id !== undefined && m.root_id === undefined) {
-                    log.warn(`${label} threaded ${m.chat_type} message ${m.message_id} has thread_id ${m.thread_id} but no root_id — session continuity cannot be guaranteed`);
-                }
-                const defaultSession = threadedConversation
-                    ? `${kind}:${m.thread_id === undefined ? m.message_id : (m.root_id ?? `missing-root:${m.thread_id}`)}`
-                    : placeKey(m);
-                const session = r.session ?? defaultSession;
-                const chatId = r.chatId ?? m.chat_id;
-                // Groups always quote the summon. Threaded groups and p2p add reply_in_thread: on a top-level
-                // message that creates the thread, and on a continuation it keeps the answer inside it. Only
-                // quote when the resolved target is the source chat — a custom redirect cannot reuse a message
-                // id there. A continuous group still keeps replies inside an already-existing platform topic.
-                const sameTarget = chatId === m.chat_id;
-                const replyTo = sameTarget && (m.chat_type === "group" || threadedP2p) ? m.message_id : undefined;
-                const replyInThread = replyTo !== undefined && (threadedConversation || m.thread_id !== undefined) ? true : undefined;
-                // Queue feedback always identifies the exact ask, including continuous modes. In threaded mode
-                // it inherits replyInThread, so an ask queued inside a root cannot leak a status card to main chat.
-                const queueReplyTo = sameTarget ? m.message_id : undefined;
-                const resources = normalized.content.resources;
-                const images = resources
-                    .filter((resource) => resource.kind === "image")
-                    .map((resource) => ({ msg: resource.messageId, key: resource.key }));
-                const files = resources
-                    .filter((resource) => resource.kind === "file" || resource.kind === "audio" || resource.kind === "video")
-                    .map((resource) => ({ msg: resource.messageId, key: resource.key, name: resource.name }));
-                const baseText = r.text ?? cloudEnvelope(event, kind);
-                if (baseText.trim() !== "" || images.length > 0 || files.length > 0) {
-                    // Persist ownership before ACK. The platform thread does not exist until the first reply lands,
-                    // but a failed reply has no continuation to misroute; pre-ACK ownership closes the opposite,
-                    // worse window (thread created, process dies, then its unmentioned continuation is forgotten).
-                    if (route === undefined &&
-                        threadedGroup &&
-                        m.thread_id === undefined &&
-                        sameTarget &&
-                        replyInThread === true) {
-                        ownedThreads.add(m.chat_id, m.message_id);
-                    }
-                    submit({
-                        id: m.message_id,
-                        seq: ++seqCounter,
-                        session,
-                        baseText,
-                        bufferKey,
-                        chatId,
-                        replyTo,
-                        queueReplyTo,
-                        replyInThread,
-                        // Inside a threaded session the root conversation history already contains the previous
-                        // turns. Reloading parent_id would duplicate that input (and its attachments). A top-level
-                        // quoted reply has no thread_id, starts a new root, and still hydrates its referent.
-                        parentId: threadedConversation && m.thread_id !== undefined ? undefined : m.parent_id,
-                        images,
-                        files,
-                    }, true);
+            // Memory follows the place (participant model §5): one session per chat, and one per thread.
+            // Keyed by `thread_id`, never `root_id` — the platform's root_id tracks the reply chain and can
+            // differ between messages of ONE thread, which would split a side conversation in two.
+            const session = r.session ?? placeKey(kind, m);
+            const chatId = r.chatId ?? m.chat_id;
+            const sameTarget = chatId === m.chat_id;
+            // Answer where asked (§4): quote in a group so the ask is identifiable among many speakers,
+            // stay plain in an ordinary direct message, and stay inside a thread whenever the question came
+            // from one — a direct message's thread is a place too, and relocating out of it is the silent
+            // move the model refuses.
+            const replyTo = sameTarget && (m.chat_type === "group" || m.thread_id !== undefined) ? m.message_id : undefined;
+            const replyInThread = replyTo !== undefined && m.thread_id !== undefined ? true : undefined;
+            const queueReplyTo = sameTarget ? m.message_id : undefined;
+            // Explicit user stop: a control action, never a turn — it must not queue behind the run it
+            // stops. Mentions arrive as @name tokens; strip them before matching the bare word. Record the
+            // message id so a platform re-push doesn't double-abort or double-notify.
+            if (isStopText(normalized.content.text.replace(/@\S+/g, " "))) {
+                seen.add(m.message_id);
+                sideTasks.track(dispatchStop(control, session, label)
+                    .then((feedback) => api.sendText({ chatId, replyTo, replyInThread }, feedback).then(() => undefined))
+                    .catch((error) => log.warn(`${label} stop feedback failed: ${String(error)}`)));
+                return;
+            }
+            const resources = normalized.content.resources;
+            const images = resources
+                .filter((resource) => resource.kind === "image")
+                .map((resource) => ({ msg: resource.messageId, key: resource.key }));
+            const files = resources
+                .filter((resource) => resource.kind === "file" || resource.kind === "audio" || resource.kind === "video")
+                .map((resource) => ({ msg: resource.messageId, key: resource.key, name: resource.name }));
+            const baseText = r.text ?? cloudEnvelope(event, kind);
+            if (baseText.trim() === "" && images.length === 0 && files.length === 0)
+                return;
+            submit({
+                id: m.message_id,
+                seq: ++seqCounter, // arrival order; the turn store replays by it
+                session,
+                baseText,
+                bufferKey,
+                chatId,
+                replyTo,
+                queueReplyTo,
+                replyInThread,
+                // A quote is the user explicitly pointing at something that may predate this session
+                // (§8 rung 2), so it is always loaded.
+                //
+                // There used to be an exception: skip it inside a thread the agent had already answered in,
+                // since the session would hold it. That needed a second fact — did the channel RECEIVE the
+                // messages in between? — which depends on a scope that changes over time, while the record it
+                // was read against is durable. Every attempt to gate it correctly failed in the same
+                // direction (a silently missing quote), for an optimisation worth one `getMessage` on a
+                // quote-reply inside an active thread. Loading it costs a call and some text the session may
+                // already have; it also pins WHICH message is being answered, which a long thread benefits
+                // from anyway.
+                parentId: m.parent_id,
+                images,
+                files,
+            }, true);
+            // Answering inside a thread makes the agent a participant of it, which is what lets the NEXT
+            // bare message address it without a mention (§3).
+            //
+            // `r.session === undefined` is what makes this fact mean what its reader assumes. Participation
+            // is keyed by THREAD while the memory it stands in for is keyed by SESSION, and those agree only
+            // when the session is derived from the place. A route supplying its own (the scaffold's
+            // `session: user:<open_id>` example) can put two people's turns in one thread into different
+            // sessions — recording `agentSpoke` from one of them would tell the summon rule the agent took
+            // part in a conversation it cannot remember. So the flag records "the agent answered into THIS
+            // THREAD'S session". Such a thread keeps a bystander record and needs the ordinary mention to
+            // bootstrap if the route is later dropped. `group` matches the observation above so the record is
+            // never half-written.
+            //
+            // Recorded only once the intent is durable: `submit` can throw, and a redelivery must still see
+            // the thread as the agent has actually left it. A later delivery failure does not undo it —
+            // entering the conversation is the intent, not the send.
+            // Reuses `heardIn` from the way in, so both writes share ONE gate by construction. The extra
+            // conditions are about the ANSWER, not the speaker: it must land in this thread (`sameTarget`,
+            // `replyInThread`) and in the place's own session, or the flag would claim a memory that never
+            // held the turn.
+            if (heard && replyInThread === true && sameTarget && r.session === undefined) {
+                // Both halves in ONE merge, like Slack's: a record that needed an earlier merge to survive
+                // could otherwise say "answered here, heard nobody" — which admits bare messages forever.
+                threadParticipants.merge(heard.key, { agentSpoke: true, humans: [heard.speaker] });
+            }
+        };
+        return { acceptEvent, turnsIdle: () => Promise.all([queue.idle(), sideTasks.drain()]).then(() => undefined) };
+    };
+}
+function createFeishuWebhookRoutes(profile, opts, runtime) {
+    const { verificationToken, encryptKey } = opts;
+    const { kind, envPrefix } = profile;
+    const label = `[${kind}]`;
+    const handler = async (req) => {
+        if (req.method !== "POST")
+            return text("POST only\n", 405);
+        const body = await readBodyCapped(req, MAX_EVENT_BYTES);
+        if ("tooLarge" in body)
+            return text("payload too large\n", 413);
+        let outer;
+        try {
+            outer = JSON.parse(body.text);
+            if (typeof outer !== "object" || outer === null)
+                throw new Error("not an object");
+        }
+        catch {
+            return text("invalid json\n", 400);
+        }
+        let envelope;
+        if (typeof outer.encrypt === "string") {
+            if (!encryptKey) {
+                log.error(`${label} received an ENCRYPTED event but no encryptKey is configured — set ${envPrefix}_ENCRYPT_KEY`);
+                return text("encrypt key not configured\n", 400);
+            }
+            const sig = {
+                timestamp: req.headers.get("x-lark-request-timestamp") ?? "",
+                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);
+            }
+            try {
+                envelope = JSON.parse(decryptEvent(encryptKey, outer.encrypt));
+            }
+            catch {
+                if (!sig.signature) {
+                    log.warn(`${label} rejected an unsigned encrypted request that could not be decrypted`);
+                    return text("invalid encrypted payload\n", 401);
                 }
+                return text("invalid encrypted payload\n", 400);
+            }
+            if (!sig.signature && envelope.type !== "url_verification") {
+                log.warn(`${label} rejected an encrypted event: missing X-Lark-Signature`);
+                return text("invalid signature\n", 401);
+            }
+        }
+        else {
+            if (encryptKey) {
+                log.warn(`${label} rejected a plaintext event while encryptKey is set (console mismatch, or a forgery)`);
+                return text("plaintext events not accepted\n", 401);
             }
-            // ACK immediately (the platform expects a fast 200; the turn may outlast it by minutes) —
-            // lifecycle goes to stderr; after the 200 those lines are the operator's only signal.
+            envelope = outer;
+        }
+        const token = (typeof envelope.token === "string" ? envelope.token : undefined) ??
+            (typeof envelope.header?.token === "string"
+                ? envelope.header.token
+                : undefined);
+        if (!token || !timingSafeEqualStr(token, verificationToken)) {
+            log.warn(`${label} rejected an event: verification token mismatch (check ${envPrefix}_VERIFICATION_TOKEN against the console)`);
+            return text("invalid token\n", 401);
+        }
+        if (envelope.type === "url_verification" && typeof envelope.challenge === "string") {
+            log.info(`${label} answered the console's url_verification challenge`);
+            return Response.json({ challenge: envelope.challenge });
+        }
+        const header = envelope.header;
+        if (header?.event_type !== "im.message.receive_v1") {
+            log.debug(`${label} ignoring event type ${header?.event_type ?? "(none)"}`);
             return new Response(null, { status: 200 });
-        };
-        // Test/observability seam: await the fire-and-forget turns this handler enqueues (see turn-queue).
-        handler.turnsIdle = () => queue.idle();
-        return { [`POST /${kind}`]: handler };
+        }
+        runtime.acceptEvent((envelope.event ?? {}));
+        return new Response(null, { status: 200 });
+    };
+    handler.turnsIdle = runtime.turnsIdle;
+    return { [`POST /${kind}`]: handler };
+}
+export function buildFeishuChannel(profile, opts, factoryName) {
+    rejectRemovedSessionOptions(opts, factoryName);
+    const createRuntime = createFeishuRuntimeFactory(profile, opts, factoryName);
+    return (ctx) => {
+        if (!opts.verificationToken) {
+            throw new Error(`${factoryName} requires a non-empty verificationToken (console → Events & Callbacks)`);
+        }
+        return createFeishuWebhookRoutes(profile, opts, createRuntime(ctx));
+    };
+}
+export function buildFeishuWebSocketChannel(profile, opts, factoryName, deps = {}) {
+    rejectRemovedSessionOptions(opts, factoryName);
+    const createRuntime = createFeishuRuntimeFactory(profile, opts, factoryName);
+    return {
+        name: `${profile.kind} websocket`,
+        connect(ctx, signal) {
+            const runtime = createRuntime(ctx);
+            return (deps.connectWs ?? connectFeishuWs)({
+                kind: profile.kind,
+                appId: opts.appId,
+                appSecret: opts.appSecret,
+                domain: opts.apiBaseUrl ?? profile.apiBase,
+                onEvent: runtime.acceptEvent,
+            }, signal);
+        },
     };
 }