@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/channels/feishu/feishu.js

@@ -2,7 +2,8 @@
  * Canonical Feishu bot-channel engine: verified webhook or official-SDK WebSocket → dedup → route → persist → enqueue
  * → stream a live card.
  */
-import { isAbsolute, join } from "node:path";
+import { join } from "node:path";
+import { Effect } from "effect";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
@@ -10,22 +11,24 @@ import { secretEquals } from "../secret.js";
 import { createSeenRing } from "../kit/seen.js";
 import { createTaskTracker } from "../kit/tasks.js";
 import { attachmentsDir } from "../kit/attachment-path.js";
-import { ensureStateHome, loadStateFile, saveStateFile } from "../kit/state.js";
+import { loadStateFile, saveStateFile } from "../../state-file.js";
 import { signatureIsFresh } from "../kit/signature.js";
 import { dispatchStop, isStopText } from "../kit/stop-command.js";
+import { createRoomThreads, registerRoomThreads } from "../kit/room-threads.js";
+import { threadForkSource } from "../kit/thread-fork.js";
 import { createTurnRunner } from "../kit/turn-runner.js";
 import { portJoin } from "../../effect-port.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 { collectFoldedAttachments, createFeishuPlaceHistory, feishuHistoryKey, feishuPlaceOf, } from "./history.js";
 import { decryptEvent, verifySignature } from "./crypto.js";
 import { feishuTurnStream } from "./invoke-turn.js";
 import { createFeishuApi } from "./feishu-api.js";
 import { normalizeFeishuMessage } from "./normalize.js";
 import { createThreadParticipants } from "../kit/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 { FEISHU_AGENT_SCOPES, feishuIngressFor, scopeSatisfied } from "./setup-mode.js";
+import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderId, } from "./parse.js";
 import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, feishuReply, } from "./preview.js";
 import { connectFeishuWs } from "./ws-ingress.js";
 import { registerFeishuApi } from "./shared-api.js";
@@ -52,16 +55,18 @@ function isStoredFeishuTurn(t) {
         v.every((x) => typeof x.msg === "string" && typeof x.key === "string");
     return (typeof r?.id === "string" &&
         typeof r.seq === "number" &&
-        typeof r.session === "string" &&
+        typeof r.conversation === "string" &&
         typeof r.baseText === "string" &&
-        typeof r.bufferKey === "string" &&
+        (r.historyKey === undefined || typeof r.historyKey === "string") &&
+        typeof r.group === "boolean" &&
+        typeof r.askAt === "number" &&
         typeof r.chatId === "string" &&
         (r.replyTo === undefined || typeof r.replyTo === "string") &&
         (r.queueReplyTo === undefined || typeof r.queueReplyTo === "string") &&
         (r.replyInThread === undefined || typeof r.replyInThread === "boolean") &&
         (r.parentId === undefined || typeof r.parentId === "string") &&
-        (r.parentSession === undefined || typeof r.parentSession === "string") &&
-        (r.roomBufferKey === undefined || typeof r.roomBufferKey === "string") &&
+        (r.parentConversation === undefined || typeof r.parentConversation === "string") &&
+        (r.roomKey === undefined || typeof r.roomKey === "string") &&
         refs(r.images) &&
         refs(r.files) &&
         typeof r.attempts === "number");
@@ -70,6 +75,10 @@ function isStoredFeishuTurn(t) {
 export function feishuChannel(opts) {
     return buildFeishuChannel(FEISHU_CLOUD, opts, feishuChannel.name);
 }
+/** How this process receives the Feishu channel: `FEISHU_INGRESS`, else WebSocket under `dev` and webhook otherwise. */
+export function feishuIngress() {
+    return feishuIngressFor("feishu");
+}
 /** Build the canonical Feishu WebSocket long-connection channel. */
 export function feishuWebSocketChannel(opts) {
     return buildFeishuWebSocketChannel(FEISHU_CLOUD, opts, feishuWebSocketChannel.name);
@@ -125,50 +134,57 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
     const baseUrl = opts.apiBaseUrl ?? profile.apiBase;
     const { kind } = profile;
     const label = `[${kind}]`;
-    return ({ agent, stateRoot, control }) => {
+    return ({ agent, sessionFor, recordedSession, stateDir: stateHome }) => {
         // Credential checks run when serving starts, not while the authored module is imported.
         if (!appId || !appSecret) {
             throw new Error(`${factoryName} requires appId + appSecret (developer console → Credentials & Basic Info)`);
         }
         const formatError = onError ?? defaultErrorMessage;
+        // Shared with the send tools (registered below). A turn's own posts go through `placeApi`.
         const api = createFeishuApi({ kind, baseUrl, appId, appSecret });
         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.
-                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`);
+            const granted = (name) => scopes.some((scope) => scope.name === name && scope.grantStatus === 1 && (scope.type === undefined || scope.type === "tenant"));
+            const missing = FEISHU_AGENT_SCOPES.filter((entry) => !scopeSatisfied(entry, granted));
+            if (missing.length === 0) {
+                log.info(`${label} permissions: every agent scope granted — the agent hears its group chats`);
             }
-        }, (error) => log.warn(`${label} could not inspect group visibility: ${String(error)}`));
-        // The channel-state convention: this channel's durable home is `<stateRoot>/channels/<kind>` (engine state at the
-        // root, channel state under `channels/<kind>/`).
-        if (!isAbsolute(stateRoot)) {
-            throw new Error(`${factoryName} requires an absolute ctx.stateRoot, got "${stateRoot}"`);
-        }
-        const stateHome = join(stateRoot, "channels", kind);
-        ensureStateHome(stateHome); // buffers/files may carry chat content; the agent .gitignore covers .state/
+            for (const entry of missing)
+                log.warn(`${label} ${entry.request} is not granted — ${entry.withoutIt}`);
+        }, (error) => log.warn(`${label} could not inspect the app's permissions: ${String(error)}`));
         const botOpenId = createBotIdentity({ api, appId, label, botFile: join(stateHome, "bot.json") });
         const decide = route ?? ((event) => defaultFeishuRoute(event, { botOpenId: botOpenId() }));
         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.
         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,
             isRecord: isStoredFeishuTurn,
             order: (a, b) => a.seq - b.seq,
         });
+        // Every message this channel took as input (a turn, a /stop): the dedup ring. A history read also leaves these out,
+        // to shape the prompt only — what keeps a queued ask out of an earlier turn is the read's bound, not this ring.
         const seen = createSeenRing(join(stateHome, "seen.json"), label);
+        const history = createFeishuPlaceHistory({
+            api,
+            appId,
+            label,
+            path: join(stateHome, "history.json"),
+            isTurnInput: (id) => seen.has(id),
+        });
+        // A group turn's room, for the thread-reading tool (`feishuThreads`): the chat it was asked in, and its threads.
+        const rooms = createRoomThreads({
+            list: (chatId) => history.threads(chatId),
+            read: async (chatId, threadId) => (await history.snapshot(feishuHistoryKey({ chatId, threadId }))).text ||
+                `(thread ${threadId} shows no messages)`,
+        });
+        registerRoomThreads(kind, stateHome, rooms);
+        /**
+         * The client a turn posts through: what it posts into its place (answer, queue notice, stop feedback) is in the
+         * session already, so the place records it and its next read leaves it out. The send tools use the plain client,
+         * so what the agent posts itself stays discussion. A routed turn has no place and reads no history.
+         */
+        const placeApi = (historyKey) => historyKey === undefined ? api : api.recordingSends((id) => history.recordOutput(historyKey, id));
         // Side tasks (stop feedback) run off the ingress path but drain in turnsIdle.
         const sideTasks = createTaskTracker(label);
         const targetOf = (r) => ({
@@ -185,16 +201,16 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         // operator log line.
         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)}`));
+            void settleFeishuPreview(placeApi(r.historyKey), targetOf(r), r.preview, body).catch((e) => log.warn(`${label} could not notify a dropped turn (conversation=${r.conversation}): ${String(e)}`));
         };
         const runner = createTurnRunner({
             label,
             store,
-            buffer,
+            discussion: history,
             seen,
             toStored: ({ preview: _live, ...intent }) => ({ ...intent, attempts: 0 }),
             fromStored: ({ attempts: _a, ...intent }) => ({ ...intent, preview: undefined }),
-            bufferKey: (rec) => rec.bufferKey,
+            discussionKey: (rec) => rec.historyKey === undefined ? undefined : { key: rec.historyKey, until: { at: rec.askAt, id: rec.id } },
             where: (rec) => `chat=${rec.chatId}`,
             // Queue feedback: mount that turn's preview early with a queue status.
             onQueuedBehind: (rec) => {
@@ -205,7 +221,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 });
                 const mount = () => {
                     fired = true;
-                    mountFeishuPreview(api, queueTargetOf(rec), QUEUED_PLACEHOLDER, label)
+                    mountFeishuPreview(placeApi(rec.historyKey), queueTargetOf(rec), QUEUED_PLACEHOLDER, label)
                         .then((preview) => {
                         rec.preview = preview;
                     }, (e) => log.warn(`${label} queue preview failed (the turn still runs): ${String(e)}`))
@@ -230,42 +246,54 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             // honest delayed status.
             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)}`));
+                    void settleFeishuPreview(placeApi(rec.historyKey), targetOf(rec), rec.preview, DEFERRED_PLACEHOLDER).catch((e) => log.warn(`${label} could not update a deferred turn's queue preview: ${String(e)}`));
                 }
             },
             notifyDropped,
             // `rec.preview`: the queue card THIS process mounted if the record waited behind another turn.
-            deliverAnswer: (rec, answer) => portJoin(() => settleFeishuPreview(api, targetOf(rec), rec.preview, answer)),
-            execute: (rec, discussion, onAnswered) => {
-                // 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 room'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;
+            deliverAnswer: (rec, answer) => portJoin(() => settleFeishuPreview(placeApi(rec.historyKey), targetOf(rec), rec.preview, answer)),
+            execute: (rec, discussion, onAnswered) => Effect.promise(async () => 
+            // Read-only: the room's own next answered turn still reads it into the room's memory (§8).
+            rec.roomKey !== undefined ? history.room(rec.roomKey) : undefined).pipe(Effect.flatMap((room) => {
                 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(discussion.text)}${rec.baseText}`;
-                // Room entries FIRST: the collector keeps the TAIL under its cap, so the thread's own attachments win the
+                // Room messages FIRST: the collector keeps the TAIL under its cap, so the thread's own attachments win the
                 // slots.
-                const buffered = collectFeishuBufferedAttachments([...(room?.consumed ?? []), ...discussion.consumed], {
+                const buffered = collectFoldedAttachments([...(room?.folded ?? []), ...discussion.consumed.flatMap((read) => read.folded)], {
                     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 })),
+                    files: rec.files.map((ref) => ({ messageId: ref.msg, key: ref.key })),
                 });
-                // 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;
-                return feishuReply(feishuTurnStream(agent, rec.session, prompt, {
-                    api,
+                // Recorded at ingress (see submit), never re-derived from the conversation key, which may be a routed
+                // OPAQUE id that only looks like a place key.
+                const parent = rec.parentConversation;
+                // A group turn under the default routing reads its chat's threads; a DM has none to read.
+                const threadsRoom = rec.group && rec.historyKey !== undefined ? feishuPlaceOf(rec.historyKey).chatId : undefined;
+                const turnApi = placeApi(rec.historyKey);
+                return feishuReply(feishuTurnStream(agent, {
+                    session: (chain) => sessionFor(rec.conversation, {
+                        forkFrom: async () => {
+                            // A thread of a room nothing was said in starts empty: there is nothing to fork.
+                            const room = parent === undefined ? undefined : recordedSession(parent);
+                            return room === undefined ? undefined : threadForkSource(agent, room, chain);
+                        },
+                    }),
+                    ...(threadsRoom === undefined
+                        ? {}
+                        : { enter: (sessionId) => rooms.enter(sessionId, threadsRoom) }),
+                    key: rec.id,
+                    text: prompt,
+                }, {
+                    api: turnApi,
                     chatId: rec.chatId,
                     filesDir: attachmentsDir(stateHome),
                     label,
                     appId,
-                    ...(parentSession !== undefined ? { parentSession } : {}),
-                }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }), api, targetOf(rec), formatError, rec.preview, label, onAnswered);
-            },
+                }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }), turnApi, targetOf(rec), formatError, rec.preview, label, onAnswered);
+            })),
         });
-        registerFeishuApi(stateRoot, kind, api);
+        registerFeishuApi(appId, 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.
@@ -296,7 +324,6 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             const normalized = normalizeFeishuMessage(event);
             if (!normalized)
                 return;
-            const bufferKey = feishuBufferPlaceKey(normalized.conversation);
             const isHumanGroup = event.sender?.sender_type === "user" && m.chat_type === "group";
             // Listening is not speaking: every message the channel can see refines who takes part in its thread, whether or
             // not it is answered.
@@ -312,50 +339,26 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 r = {};
             }
             if (!r) {
-                if (route === undefined && isHumanGroup) {
-                    const bodyText = feishuBufferText(normalized.content.text);
-                    if (bodyText) {
-                        const resources = normalized.content.resources;
-                        const images = resources
-                            .filter((resource) => resource.kind === "image")
-                            .map((resource) => ({ messageId: resource.messageId, key: resource.key }));
-                        const files = resources
-                            .filter((resource) => resource.kind === "file" || resource.kind === "audio" || resource.kind === "video")
-                            .map((resource) => ({
-                            messageId: resource.messageId,
-                            key: resource.key,
-                            name: resource.name,
-                        }));
-                        // A write failure escapes this boundary.
-                        buffer.push(bufferKey, {
-                            sender: senderLabel(event.sender) ?? "someone",
-                            body: bodyText,
-                            messageId: m.message_id,
-                            replyTo: m.parent_id,
-                            files: files.length ? files : undefined,
-                            images: images.length ? images : undefined,
-                        });
-                        seen.add(m.message_id);
-                        log.debug(`${label} buffered unsummoned group message ${m.message_id} (place ${bufferKey})`);
-                    }
-                    else {
-                        log.debug(`${label} not summoned — ignoring empty message ${m.message_id} (chat ${m.chat_id})`);
-                    }
-                }
-                else {
-                    log.debug(`${label} not summoned — ignoring message ${m.message_id} (chat ${m.chat_id}, ${m.chat_type})`);
-                }
+                // Not lost: the turn that is summoned here reads it from the place's history.
+                log.debug(`${label} not summoned — message ${m.message_id} (chat ${m.chat_id}, ${m.chat_type})`);
                 return;
             }
-            // Memory follows the place (participant model §5): one session per chat, and one per thread.
-            const routed = r.session;
-            const session = routed ?? placeKey(kind, m);
-            // Lineage is recorded ONLY for the default place-derived session.
-            const parentSession = routed === undefined && m.thread_id !== undefined ? placeKey(kind, { chat_id: m.chat_id }) : undefined;
+            // Memory follows the place (participant model §5): one conversation per chat, and one per thread.
+            const routed = r.conversation;
+            const conversation = routed ?? placeKey(kind, m);
+            // Lineage is recorded ONLY for the default place-derived conversation.
+            const parentConversation = routed === undefined && m.thread_id !== undefined ? placeKey(kind, { chat_id: m.chat_id }) : undefined;
             // Read BEFORE this turn records its own participation below, or it is always true.
-            const roomBufferKey = parentSession !== undefined && !threadParticipants.agentSpokeIn(session)
-                ? feishuBufferPlaceKey({ chatId: m.chat_id })
+            const roomKey = parentConversation !== undefined && !threadParticipants.agentSpokeIn(conversation)
+                ? feishuHistoryKey({ chatId: m.chat_id })
                 : undefined;
+            // Every place's discussion under the default routing, a DM's too (what a send tool posted there is in no session);
+            // a routed session's place is the router's to decide.
+            const historyKey = route === undefined ? feishuHistoryKey(normalized.conversation) : undefined;
+            // The platform stamps every message; acceptance time stands in only if a payload lacks it, and is still a bound
+            // the ask was created before.
+            const created = Number(m.create_time);
+            const askAt = Number.isFinite(created) && created > 0 ? created : Date.now();
             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
@@ -367,8 +370,10 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             // Explicit user stop: a control action, never a turn — it must not queue behind the run it stops.
             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))
+                sideTasks.track(dispatchStop(agent, recordedSession(conversation), label)
+                    .then((feedback) => placeApi(historyKey)
+                    .sendText({ chatId, replyTo, replyInThread }, feedback)
+                    .then(() => undefined))
                     .catch((error) => log.warn(`${label} stop feedback failed: ${String(error)}`)));
                 return;
             }
@@ -385,9 +390,11 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             runner.submit({
                 id: m.message_id,
                 seq: ++seqCounter, // arrival order; the turn store replays by it
-                session,
+                conversation,
                 baseText,
-                bufferKey,
+                ...(historyKey !== undefined ? { historyKey } : {}),
+                group: m.chat_type === "group",
+                askAt,
                 chatId,
                 replyTo,
                 queueReplyTo,
@@ -395,14 +402,14 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 // A quote is the user explicitly pointing at something that may predate this session (§8 rung 2), so it is
                 // always loaded.
                 parentId: m.parent_id,
-                ...(parentSession !== undefined ? { parentSession } : {}),
-                ...(roomBufferKey !== undefined ? { roomBufferKey } : {}),
+                ...(parentConversation !== undefined ? { parentConversation } : {}),
+                ...(roomKey !== undefined && historyKey !== undefined ? { roomKey } : {}),
                 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).
-            if (heard && replyInThread === true && sameTarget && r.session === undefined) {
+            if (heard && replyInThread === true && sameTarget && r.conversation === 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".
                 threadParticipants.merge(heard.key, { agentSpoke: true, humans: [heard.speaker] });
@@ -508,7 +515,11 @@ export function buildFeishuChannel(profile, 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)`);
+            // The scaffolded file reaches this under `start` with nothing set, so the error names both ways out.
+            throw new Error(`${factoryName} receives by webhook and needs a non-empty verificationToken: \`fastagent deploy <host> --run\` ` +
+                `or \`fastagent add ${profile.kind} --ingress webhook\` captures ${profile.envPrefix}_VERIFICATION_TOKEN ` +
+                `(console → Events & Callbacks has it too), or set ${profile.envPrefix}_INGRESS=websocket to receive by ` +
+                `WebSocket instead`);
         }
         return createFeishuWebhookRoutes(profile, opts, createRuntime(ctx));
     };

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

@@ -0,0 +1,55 @@
+import { type PlaceDiscussion, type PlaceHistory, type PlaceMessage, type PlaceRead } from "../kit/place-history.ts";
+import type { FeishuApi } from "./feishu-api.ts";
+/** A message's position: `create_time` alone is not unique, so the id breaks ties. */
+interface FeishuCursor {
+    at: number;
+    id: string;
+}
+export type FeishuPlaceRead = PlaceRead<FeishuCursor>;
+export type FeishuDiscussion = PlaceDiscussion<FeishuCursor>;
+export interface FeishuPlaceHistory extends PlaceHistory<FeishuCursor> {
+    /** The chat's threads among its newest messages, for a tool (`kit/room-threads.ts`). */
+    threads(chatId: string): Promise<string>;
+}
+/** A background resource carried into a turn, with attribution for its prompt manifest. */
+export interface FeishuBufferedRef {
+    messageId: string;
+    key: string;
+    name?: string;
+    from: string;
+}
+/** A place: the chat, or a thread within it. The turn record carries it as this key. */
+export declare function feishuHistoryKey(place: {
+    chatId: string;
+    threadId?: string;
+}): string;
+/** The inverse of {@link feishuHistoryKey}. */
+export declare function feishuPlaceOf(key: string): {
+    chatId: string;
+    threadId?: string;
+};
+/** Select the most recent background resources of the folded messages, excluding the turn's own primary ones. */
+export declare function collectFoldedAttachments(folded: readonly PlaceMessage[], primary: {
+    files: {
+        messageId: string;
+        key: string;
+    }[];
+    images: {
+        messageId: string;
+        key: string;
+    }[];
+}): {
+    files: FeishuBufferedRef[];
+    images: FeishuBufferedRef[];
+    skipped: number;
+};
+export declare function createFeishuPlaceHistory(deps: {
+    api: Pick<FeishuApi, "listMessages" | "chatMemberNames">;
+    /** THIS app's id: a message whose sender is this app is the agent's own. */
+    appId: string;
+    label: string;
+    /** Where each place's cursor and outputs persist. */
+    path: string;
+    isTurnInput(messageId: string): boolean;
+}): FeishuPlaceHistory;
+export {};