@fastagent-sh/fastagent 0.15.0 → 0.16.0

package/dist/channels/feishu/feishu.js

@@ -14,7 +14,7 @@ import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { createSeenRing } from "../seen.js";
 import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome } from "../state.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";
@@ -24,9 +24,9 @@ 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 { FEISHU_GROUP_CONTEXT_SCOPE } from "./setup-mode.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 { connectFeishuWs } from "./ws-ingress.js";
 // Canonical public surface; the Lark subpath aliases these types/functions at its compatibility boundary.
@@ -52,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") &&
@@ -70,17 +70,19 @@ export function feishuChannel(opts) {
 export function feishuWebSocketChannel(opts) {
     return buildFeishuWebSocketChannel(FEISHU_CLOUD, opts, feishuWebSocketChannel.name);
 }
-function validateSessionOptions(opts, factoryName) {
-    if (opts.directMessageSession !== undefined && !["continuous", "threaded"].includes(opts.directMessageSession)) {
-        throw new Error(`${factoryName} directMessageSession must be "continuous" or "threaded"`);
-    }
-    if (opts.groupMessageSession !== undefined && !["continuous", "threaded"].includes(opts.groupMessageSession)) {
-        throw new Error(`${factoryName} groupMessageSession must be "continuous" or "threaded"`);
+/** 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, directMessageSession = "threaded", groupMessageSession = "threaded", route, onError, queueNoticeDelayMs = QUEUE_NOTICE_DELAY_MS, } = opts;
-    const baseUrl = opts.apiBaseUrl ?? opts.baseUrl ?? profile.apiBase;
+    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 }) => {
@@ -92,7 +94,9 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         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;
@@ -100,14 +104,22 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 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 contextAware = scopes.some((scope) => scope.name === FEISHU_GROUP_CONTEXT_SCOPE &&
-                scope.grantStatus === 1 &&
-                (scope.type === undefined || scope.type === "tenant"));
-            if (contextAware) {
-                log.info(`${label} group visibility: context-aware — bare managed-thread replies + buffered discussion enabled`);
+            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 managed-thread replies + group context buffering are unavailable`);
+                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 }));
@@ -118,8 +130,16 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             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,
@@ -264,14 +284,45 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         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);
-        }
-        // Transport-neutral acceptance boundary. It performs only the fast pre-ACK work: normalize,
-        // route, persist intent/context, and enqueue. The minutes-long Agent turn remains fire-and-forget.
+        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`);
+            }
+            // 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)
@@ -286,13 +337,20 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 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);
-            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);
@@ -330,20 +388,18 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 }
                 return;
             }
-            const threadedP2p = directMessageSession === "threaded" && m.chat_type === "p2p";
-            const threadedGroup = groupMessageSession === "threaded" && m.chat_type === "group";
-            const threadedConversation = threadedP2p || threadedGroup;
-            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;
+            // 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;
-            const replyTo = sameTarget && (m.chat_type === "group" || threadedP2p) ? m.message_id : undefined;
-            const replyInThread = replyTo !== undefined && (threadedConversation || m.thread_id !== undefined) ? true : undefined;
+            // 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
@@ -365,12 +421,9 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             const baseText = r.text ?? cloudEnvelope(event, kind);
             if (baseText.trim() === "" && images.length === 0 && files.length === 0)
                 return;
-            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,
+                seq: ++seqCounter, // arrival order; the turn store replays by it
                 session,
                 baseText,
                 bufferKey,
@@ -378,10 +431,46 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 replyTo,
                 queueReplyTo,
                 replyInThread,
-                parentId: threadedConversation && m.thread_id !== undefined ? undefined : m.parent_id,
+                // 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) };
     };
@@ -466,7 +555,7 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
     return { [`POST /${kind}`]: handler };
 }
 export function buildFeishuChannel(profile, opts, factoryName) {
-    validateSessionOptions(opts, factoryName);
+    rejectRemovedSessionOptions(opts, factoryName);
     const createRuntime = createFeishuRuntimeFactory(profile, opts, factoryName);
     return (ctx) => {
         if (!opts.verificationToken) {
@@ -476,7 +565,7 @@ export function buildFeishuChannel(profile, opts, factoryName) {
     };
 }
 export function buildFeishuWebSocketChannel(profile, opts, factoryName, deps = {}) {
-    validateSessionOptions(opts, factoryName);
+    rejectRemovedSessionOptions(opts, factoryName);
     const createRuntime = createFeishuRuntimeFactory(profile, opts, factoryName);
     return {
         name: `${profile.kind} websocket`,
@@ -486,7 +575,7 @@ export function buildFeishuWebSocketChannel(profile, opts, factoryName, deps = {
                 kind: profile.kind,
                 appId: opts.appId,
                 appSecret: opts.appSecret,
-                domain: opts.apiBaseUrl ?? opts.baseUrl ?? profile.apiBase,
+                domain: opts.apiBaseUrl ?? profile.apiBase,
                 onEvent: runtime.acceptEvent,
             }, signal);
         },

package/dist/channels/feishu/invoke-turn.js

@@ -1,7 +1,7 @@
 import { log } from "../../log.js";
 import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
 import { parseContent } from "./parse.js";
-import { codePointPrefix } from "../text.js";
+import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../text.js";
 /** Appended to the prompt (not the system prompt): the channel renders the reply in a card, and the
  *  card's markdown element is the natural fit for LLM output — steer away from HTML/plain. */
 const MARKDOWN_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card.)";
@@ -15,24 +15,41 @@ async function resolveTurnInputs(t, attachments) {
     let referentBlock = "";
     if (attachments.primary.parentId !== undefined) {
         const parentId = attachments.primary.parentId;
-        const parent = await t.api.getMessage(parentId);
-        if (!parent)
-            throw new Error(`replied-to message ${parentId} is not readable`);
-        const parsed = parseContent({
-            message_type: parent.msg_type ?? "unknown",
-            content: parent.body?.content ?? "",
-            mentions: parent.mentions,
+        // A referent is CONTEXT, not the ask. Losing it (deleted, restricted, unreadable) must not cost
+        // the user their answer — every first message of a thread carries one, so a hard failure here
+        // would turn an ordinary platform edge into a lost turn. Degrade visibly instead: the operator
+        // gets a warning, and the model is told the quote could not be read rather than being left to
+        // guess what "about that" refers to.
+        // A deleted or invisible message comes back as an EMPTY item list rather than an error, so the
+        // warning belongs on the branch that renders the marker — that is the one the operator must see.
+        let failure;
+        const parent = await t.api.getMessage(parentId).catch((error) => {
+            failure = String(error);
+            return undefined;
         });
-        // The referent's own resources join the turn as primary inputs, carried by the PARENT message id.
-        for (const key of parsed.imageKeys)
-            images.push({ msg: parentId, key });
-        for (const ref of parsed.fileRefs)
-            files.push({ msg: parentId, key: ref.key, name: ref.name });
-        // getMessage's sender is `{ id, id_type, sender_type }` — a DIFFERENT shape from the event's
-        // sender (`{ sender_id: { open_id } }`), so the label is built here, not via parse.senderLabel.
-        const senderId = parent.sender?.id;
-        const from = senderId ? `user ${senderId}` : undefined;
-        referentBlock = `\n\n[replied-to message (msg ${parentId}${from ? `, from ${from}` : ""}): ${codePointPrefix(parsed.text, 560) || "(empty)"}]`;
+        if (!parent) {
+            log.warn(`${t.label} could not read replied-to message ${parentId} (${failure ?? "no such message"}) — the model is told the quote is unreadable`);
+            // Fall THROUGH: the resources this turn carries are the ask itself. Returning here would drop
+            // the images and files the user explicitly attached along with the referent they merely quoted.
+            referentBlock = `\n\n[replied-to message (msg ${parentId}) could not be read]`;
+        }
+        else {
+            const parsed = parseContent({
+                message_type: parent.msg_type ?? "unknown",
+                content: parent.body?.content ?? "",
+                mentions: parent.mentions,
+            });
+            // The referent's own resources join the turn as primary inputs, carried by the PARENT message id.
+            for (const key of parsed.imageKeys)
+                images.push({ msg: parentId, key });
+            for (const ref of parsed.fileRefs)
+                files.push({ msg: parentId, key: ref.key, name: ref.name });
+            // getMessage's sender is `{ id, id_type, sender_type }` — a DIFFERENT shape from the event's
+            // sender (`{ sender_id: { open_id } }`), so the label is built here, not via parse.senderLabel.
+            const senderId = parent.sender?.id;
+            const from = senderId ? `user ${senderId}` : undefined;
+            referentBlock = `\n\n[replied-to message (msg ${parentId}${from ? `, from ${from}` : ""}): ${truncateCodePointPrefix(parsed.text, REFERENT_MAX_CODE_POINTS) || "(empty)"}]`;
+        }
     }
     // Primary first and fail-fast: these are resources the current user explicitly pointed at.
     const imageRefs = [];

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

@@ -87,7 +87,6 @@ export interface NormalizedFeishuMessage {
     conversation: {
         chatId: string;
         threadId?: string;
-        rootId?: string;
     };
     content: {
         text: string;

package/dist/channels/feishu/normalize.js

@@ -121,7 +121,6 @@ export function normalizeFeishuMessage(event) {
         conversation: {
             chatId: message.chat_id,
             threadId: message.thread_id,
-            rootId: message.root_id,
         },
         content: {
             text: decoded.text,

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

@@ -7,8 +7,8 @@
 import type { FeishuCloudKind } from "./cloud.ts";
 import type { FeishuMention, FeishuMessage, FeishuMessageEvent, FeishuRoute, FeishuSender } from "./model.ts";
 export type { FeishuMention, FeishuMessage, FeishuMessageEvent, FeishuRoute, FeishuSender };
-/** Legacy compatibility shape returned by {@link parseContent}. New internal code consumes normalized
- * resource refs, which retain resource kind + carrying message id. */
+/** A resource reduced to what a caller needs to fetch and name it — the kind and carrying message id
+ * that {@link decodeFeishuContent} attaches are supplied by the caller's own context. */
 interface FeishuAttachmentRef {
     key: string;
     name?: string;
@@ -19,14 +19,27 @@ export interface ParsedFeishuContent {
     fileRefs: FeishuAttachmentRef[];
 }
 /**
- * Compatibility decoder for existing helpers/tests and parent-message resolution. The canonical
- * decoder now emits typed resources; this wrapper projects them onto the historical parallel arrays.
+ * The decoder projected onto flat per-kind arrays, for callers that resolve a message on their own
+ * (the prompt envelope, and the quoted parent whose resources are carried by the PARENT message id).
+ * `decodeFeishuContent` stays canonical: this only reshapes what it returns.
  */
 export declare function parseContent(message: Pick<FeishuMessage, "message_type" | "content" | "mentions">): ParsedFeishuContent;
 /** A stable sender label for attribution. Display names require an additional contacts permission. */
 export declare function senderLabel(sender: FeishuSender | undefined): string | undefined;
-/** The place a message lives (chat, or chat:topic in a topic group) — the legacy default session key. */
-export declare function placeKey(message: Pick<FeishuMessage, "chat_id" | "thread_id">): string;
+/** Whichever id flavour the tenant populates. `sender_id` is a union and which members are filled is
+ *  app configuration, not an invariant — callers only ever compare these for distinctness. */
+export declare function senderId(sender: FeishuSender | undefined): string | undefined;
+/**
+ * The place a message lives (the chat, or a thread within it) — the session key (participant model §5),
+ * and the key thread participation is recorded under, since that record is a claim about this session.
+ *
+ * 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.
+ */
+export declare function placeKey(kind: string, message: Pick<FeishuMessage, "chat_id" | "thread_id">): string;
 /** The canonical Feishu-branded prompt envelope. */
 export declare function feishuEnvelope(event: FeishuMessageEvent): string;
 /** Internal compatibility seam: bind the canonical envelope shape to one cloud's branded tag. */
@@ -36,7 +49,8 @@ export declare function mentionsBot(message: Pick<FeishuMessage, "mentions">, bo
 /**
  * Default EXPLICIT-summon policy: ignore non-user senders, always answer p2p, and answer groups only
  * when THIS bot is structurally mentioned. No bot identity means group routing fails closed. The
- * stateful channel wiring may additionally admit unmentioned continuations from its managed-root index.
+ * stateful channel wiring may additionally admit unmentioned messages in a thread it takes part in
+ * (docs/design/participant-model.md §3).
  */
 export declare function defaultFeishuRoute(event: FeishuMessageEvent, options?: {
     botOpenId?: string;

package/dist/channels/feishu/parse.js

@@ -1,7 +1,8 @@
 import { decodeFeishuContent } from "./normalize.js";
 /**
- * Compatibility decoder for existing helpers/tests and parent-message resolution. The canonical
- * decoder now emits typed resources; this wrapper projects them onto the historical parallel arrays.
+ * The decoder projected onto flat per-kind arrays, for callers that resolve a message on their own
+ * (the prompt envelope, and the quoted parent whose resources are carried by the PARENT message id).
+ * `decodeFeishuContent` stays canonical: this only reshapes what it returns.
  */
 export function parseContent(message) {
     const decoded = decodeFeishuContent(message);
@@ -15,12 +16,27 @@ export function parseContent(message) {
 }
 /** A stable sender label for attribution. Display names require an additional contacts permission. */
 export function senderLabel(sender) {
-    const id = sender?.sender_id?.open_id ?? sender?.sender_id?.user_id ?? sender?.sender_id?.union_id;
+    const id = senderId(sender);
     return id ? `user ${id}` : undefined;
 }
-/** The place a message lives (chat, or chat:topic in a topic group) — the legacy default session key. */
-export function placeKey(message) {
-    return message.thread_id ? `${message.chat_id}:${message.thread_id}` : message.chat_id;
+/** Whichever id flavour the tenant populates. `sender_id` is a union and which members are filled is
+ *  app configuration, not an invariant — callers only ever compare these for distinctness. */
+export function senderId(sender) {
+    return sender?.sender_id?.open_id ?? sender?.sender_id?.user_id ?? sender?.sender_id?.union_id;
+}
+/**
+ * The place a message lives (the chat, or a thread within it) — the session key (participant model §5),
+ * and the key thread participation is recorded under, since that record is a claim about this session.
+ *
+ * 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.
+ */
+export function placeKey(kind, message) {
+    const chat = `${kind}:${message.chat_id}`;
+    return message.thread_id ? `${chat}:${message.thread_id}` : chat;
 }
 /** The canonical Feishu-branded prompt envelope. */
 export function feishuEnvelope(event) {
@@ -52,7 +68,8 @@ export function mentionsBot(message, botOpenId) {
 /**
  * Default EXPLICIT-summon policy: ignore non-user senders, always answer p2p, and answer groups only
  * when THIS bot is structurally mentioned. No bot identity means group routing fails closed. The
- * stateful channel wiring may additionally admit unmentioned continuations from its managed-root index.
+ * stateful channel wiring may additionally admit unmentioned messages in a thread it takes part in
+ * (docs/design/participant-model.md §3).
  */
 export function defaultFeishuRoute(event, options) {
     const message = event.message;

package/dist/channels/feishu/preview.js

@@ -63,8 +63,9 @@ async function finalize(api, target, preview, text, seq) {
             // Settle failed (card expired / rejected) — fall through to delete + fresh send below.
         }
         if (settled) {
-            // Threaded continuations must keep reply_in_thread; continuous top-level group replies intentionally
-            // avoid repeating the quote on every chunk. sendText owns the same distinction for its own chunking.
+            // Threaded continuations must keep reply_in_thread; top-level group replies (target.replyInThread
+            // unset — a custom route, or an ask outside a thread) intentionally avoid repeating the quote on
+            // every chunk. sendText owns the same distinction for its own chunking.
             // A continuation failure propagates: the card is already authoritative, so deleting it and sending
             // the full answer again would deterministically duplicate every continuation that already landed.
             const continuationTarget = target.replyInThread ? target : { chatId: target.chatId };

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

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

package/dist/channels/feishu/scaffold/feishu-send.ts

@@ -6,7 +6,7 @@ import { defineTool, z } from "@fastagent-sh/fastagent";
 // context line in a chat turn; a scheduled turn has no such line, so the schedule's prompt must name
 // the target chat id. tools/ is auto-discovered.
 
-// Standalone copy of the channel transport's discipline: a timeout so a wedged connection can't hang
+// Embedded copy of the channel transport's discipline: a timeout so a wedged connection can't hang
 // the tool call (and the turn), named errors, and success gated on the body's own code===0.
 // Deliberately NO rate-limit retry — a tool error goes back to the agent, which can decide to retry;
 // fail-fast beats a silently sleeping tool.
@@ -57,9 +57,11 @@ async function tenantToken(): Promise<string> {
 export default defineTool({
   description:
     "Send a message to a Feishu chat: plain `text`, or `markdown` (rendered as a card — headings, " +
-    "bold, code blocks, links). Exactly one of the two. In a chat turn take chatId from the " +
-    "[feishu: chat …] context line; in a scheduled/woken turn (no context line) the chat id must come " +
-    "from your instruction.",
+    "bold, code blocks, links). Exactly one of the two. Use it for a turn NO channel is carrying — a " +
+    "scheduled or self-scheduled (wake) turn — or to reach a chat OTHER than the one you are " +
+    "answering. In a normal chat turn the channel already delivers your reply, so do NOT call this to " +
+    "answer (it would post the message twice). chatId comes from the [feishu: chat …] context line in a " +
+    "chat turn; a scheduled/woken turn has no context line, so name the destination in your instruction.",
   input: z.object({
     chatId: z.string().describe("target chat id (oc_…)"),
     text: z.string().optional().describe("plain text message to send"),