@fastagent-sh/fastagent 0.13.0 → 0.14.0

package/README.md

@@ -39,7 +39,7 @@ FastAgent is the missing bridge from local agent directory to live service.
 - **Channels.** Serve the same agent as a GitHub PR reviewer, a Telegram bot, an HTTP/SSE endpoint, or your own adapter — verified webhooks, streaming replies, group-aware.
 - **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key; typed tools discovered from `tools/` (the filename is the name, Zod-validated); Agent Skills loaded on demand. Built on the open-source [pi](https://github.com/earendil-works/pi) harness.
 - **App embedding — your stack, we plug in.** Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler, or call `invoke` like any function from your own code — your auth, your database, your infra. FastAgent composes with your app, never owns it.
-- **Deploy anywhere.** No build step — the directory is the deployable unit. `fastagent deploy fly|railway` generates the deploy config + a runbook (`--run` drives it to completion); idle agents scale to zero and resume in hundreds of milliseconds on the next webhook. The generated container runs on any Docker host.
+- **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; optional `--tunnel` adds an ephemeral Quick Tunnel service for webhook channels. Durable ingress remains yours.
 
 ## Design philosophy
 
@@ -198,7 +198,7 @@ The neutral contract leaves room for capabilities that are not complete product
 - **Sandboxed execution** — `ExecutionEnv` is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter is future work.
 - **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
 - **More harness bindings and channels** — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.
-- **More deploy targets** — Fly and Railway ship today; the generated container is the portable path for other hosts.
+- **More deploy targets** — local Docker, Fly, and Railway ship today; the generated container is the portable path for other hosts.
 
 See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md) if one of these is the problem you want to work on.
 

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

@@ -0,0 +1,46 @@
+import type { NormalizedFeishuMessage } from "./model.ts";
+export interface FeishuBufferedResource {
+    messageId: string;
+    key: string;
+    name?: string;
+}
+export interface FeishuBufferEntry {
+    sender: string;
+    body: string;
+    messageId: string;
+    replyTo?: string;
+    files?: FeishuBufferedResource[];
+    images?: FeishuBufferedResource[];
+}
+/** A background resource carried into a later turn, with attribution for its prompt manifest. */
+export interface FeishuBufferedRef extends FeishuBufferedResource {
+    from: string;
+}
+/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
+export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "rootId" | "threadId">): string;
+/** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
+export declare function feishuBufferText(text: string): string;
+/**
+ * Select the most recent background resources, excluding resources already primary on this turn. A
+ * resource is message-scoped in Feishu/Lark, so identity is `message_id + key`, never the bare key.
+ */
+export declare function collectFeishuBufferedAttachments(consumed: FeishuBufferEntry[], primary: {
+    files: FeishuBufferedResource[];
+    images: FeishuBufferedResource[];
+}): {
+    files: FeishuBufferedRef[];
+    images: FeishuBufferedRef[];
+    skipped: number;
+};
+export interface FeishuContextBuffer {
+    /** Persist before webhook ACK. A failed write throws and rolls memory back for safe redelivery. */
+    push(placeKey: string, entry: FeishuBufferEntry): void;
+    /** Render and snapshot without clearing. */
+    peek(placeKey: string): {
+        text: string;
+        consumed: FeishuBufferEntry[];
+    };
+    /** Remove only the consumed snapshot after `completed`; a post-ACK write failure is logged. */
+    commit(placeKey: string, consumed: FeishuBufferEntry[]): void;
+}
+export declare function createFeishuContextBuffer(path: string, label: string): FeishuContextBuffer;

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

@@ -0,0 +1,133 @@
+/**
+ * Durable context buffer for human group messages that do NOT currently summon the Feishu/Lark Agent.
+ * Entries are bucketed by conversation place (main chat, or one concrete thread root) and folded into
+ * the next answered turn in that place. The consume protocol mirrors Telegram: peek without clearing,
+ * then commit exactly that snapshot only after the Agent emits `completed`.
+ */
+import { log } from "../../log.js";
+import { loadStateFile, saveStateFile } from "../state.js";
+const BUFFER_MAX_CHARS = 4000;
+const BUFFER_ATTACH_MAX = 3;
+function bufferLine(entry) {
+    const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
+        .filter(Boolean)
+        .join(", ");
+    return `${entry.sender} (${meta}): ${entry.body}`;
+}
+/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
+export function feishuBufferPlaceKey(conversation) {
+    const topic = conversation.rootId ?? conversation.threadId;
+    return topic ? `${conversation.chatId}:root:${topic}` : conversation.chatId;
+}
+/** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
+export function feishuBufferText(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, 280);
+}
+function resourceIdentity(resource) {
+    return `${resource.messageId}\u0000${resource.key}`;
+}
+/**
+ * Select the most recent background resources, excluding resources already primary on this turn. A
+ * resource is message-scoped in Feishu/Lark, so identity is `message_id + key`, never the bare key.
+ */
+export function collectFeishuBufferedAttachments(consumed, primary) {
+    const refs = (pick, primaryRefs) => {
+        const excluded = new Set(primaryRefs.map(resourceIdentity));
+        const seen = new Set();
+        const out = [];
+        for (const entry of consumed) {
+            for (const resource of pick(entry) ?? []) {
+                const identity = resourceIdentity(resource);
+                if (excluded.has(identity) || seen.has(identity))
+                    continue;
+                seen.add(identity);
+                out.push({ ...resource, from: entry.sender });
+            }
+        }
+        return out;
+    };
+    const files = refs((entry) => entry.files, primary.files);
+    const images = refs((entry) => entry.images, primary.images);
+    return {
+        files: files.slice(-BUFFER_ATTACH_MAX),
+        images: images.slice(-BUFFER_ATTACH_MAX),
+        skipped: Math.max(0, files.length - BUFFER_ATTACH_MAX) + Math.max(0, images.length - BUFFER_ATTACH_MAX),
+    };
+}
+function isResource(value) {
+    const resource = value;
+    return (typeof resource?.messageId === "string" &&
+        typeof resource.key === "string" &&
+        (resource.name === undefined || typeof resource.name === "string"));
+}
+function isEntry(value) {
+    const entry = value;
+    const resources = (candidate) => candidate === undefined || (Array.isArray(candidate) && candidate.every(isResource));
+    return (typeof entry?.sender === "string" &&
+        typeof entry.body === "string" &&
+        typeof entry.messageId === "string" &&
+        (entry.replyTo === undefined || typeof entry.replyTo === "string") &&
+        resources(entry.files) &&
+        resources(entry.images));
+}
+export function createFeishuContextBuffer(path, label) {
+    const load = () => {
+        const raw = loadStateFile(path);
+        if (raw === undefined)
+            return new Map();
+        if (typeof raw === "object" &&
+            raw !== null &&
+            !Array.isArray(raw) &&
+            Object.values(raw).every((entries) => Array.isArray(entries) && entries.every(isEntry))) {
+            return new Map(Object.entries(raw));
+        }
+        log.warn(`${label} unexpected shape in ${path} — starting with an empty context buffer`);
+        return new Map();
+    };
+    const buffers = load();
+    const persist = () => saveStateFile(path, Object.fromEntries(buffers));
+    return {
+        push(placeKey, entry) {
+            const previous = buffers.get(placeKey);
+            const entries = previous ? [...previous] : [];
+            entries.push(entry);
+            let total = entries.reduce((sum, candidate) => sum + bufferLine(candidate).length + 1, 0);
+            while (entries.length > 1 && total > BUFFER_MAX_CHARS) {
+                const dropped = entries.shift();
+                if (dropped)
+                    total -= bufferLine(dropped).length + 1;
+            }
+            buffers.set(placeKey, entries);
+            try {
+                persist();
+            }
+            catch (error) {
+                if (previous)
+                    buffers.set(placeKey, previous);
+                else
+                    buffers.delete(placeKey);
+                throw error;
+            }
+        },
+        peek(placeKey) {
+            const entries = buffers.get(placeKey) ?? [];
+            return { text: entries.map(bufferLine).join("\n"), consumed: [...entries] };
+        },
+        commit(placeKey, consumed) {
+            const entries = buffers.get(placeKey);
+            if (!entries)
+                return;
+            const remaining = entries.filter((entry) => !consumed.includes(entry));
+            if (remaining.length === 0)
+                buffers.delete(placeKey);
+            else
+                buffers.set(placeKey, remaining);
+            try {
+                persist();
+            }
+            catch (error) {
+                log.error(`${label} context-buffer write failed post-ACK (a restart may re-fold answered discussion): ${String(error)}`);
+            }
+        },
+    };
+}

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

@@ -1,7 +1,9 @@
 /** Constant-time string equality (padded to equal length first — timingSafeEqual demands it). */
 export declare function timingSafeEqualStr(a: string, b: string): boolean;
-/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed input
- *  or a wrong key (bad padding) — the caller turns that into a 4xx, never a silent drop. */
+/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed
+ * input or invalid padding. AES-CBC is not authenticated, so a wrong key is not mathematically
+ * guaranteed to fail padding; the caller verifies signed events before decrypting and JSON-parses every
+ * plaintext envelope, turning wrong-key garbage into a 4xx rather than a silent drop. */
 export declare function decryptEvent(encryptKey: string, encryptB64: string): string;
 /** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
 export declare function eventSignature(encryptKey: string, timestamp: string, nonce: string, rawBody: string): string;

package/dist/channels/feishu/crypto.js

@@ -21,8 +21,10 @@ export function timingSafeEqualStr(a, b) {
     const bb = Buffer.from(b);
     return ab.length === bb.length && timingSafeEqual(ab, bb);
 }
-/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed input
- *  or a wrong key (bad padding) — the caller turns that into a 4xx, never a silent drop. */
+/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed
+ * input or invalid padding. AES-CBC is not authenticated, so a wrong key is not mathematically
+ * guaranteed to fail padding; the caller verifies signed events before decrypting and JSON-parses every
+ * plaintext envelope, turning wrong-key garbage into a 4xx rather than a silent drop. */
 export function decryptEvent(encryptKey, encryptB64) {
     const key = createHash("sha256").update(encryptKey, "utf8").digest();
     const buf = Buffer.from(encryptB64, "base64");

package/dist/channels/feishu/feishu-api.d.ts

@@ -1,6 +1,6 @@
 import type { ImageRef } from "../../agent.ts";
 import type { FeishuCloudKind } from "./cloud.ts";
-/** Where a reply goes: a chat, optionally quote-replying a message (in-thread in topic groups). */
+/** Where a reply goes: a chat, optionally quote-replying a message inside a platform thread. */
 export interface FeishuTarget {
     chatId: string;
     /** Message to reply to (the summoning message). Set in groups so the answer threads under the asker. */
@@ -49,12 +49,12 @@ export interface FeishuApi {
     }>;
     /** Send a message to a chat; returns the new message_id (undefined if the body carried none). */
     sendMessage(chatId: string, msgType: string, content: string): Promise<string | undefined>;
-    /** Reply to a message (quote; `replyInThread` stays inside a topic group's thread). */
+    /** Reply to a message; `replyInThread` creates or continues its platform thread. */
     replyMessage(messageId: string, msgType: string, content: string, opts?: {
         replyInThread?: boolean;
     }): Promise<string | undefined>;
-    /** Send `text`, split at the platform's size cap: ordinary groups quote only the first chunk; topic
-     *  groups reply_in_thread on every chunk. Returns the FIRST message_id. */
+    /** Send `text`, split at the platform's size cap: ordinary groups quote only the first chunk;
+     *  threaded targets use reply_in_thread on every chunk. Returns the FIRST message_id. */
     sendText(target: FeishuTarget, text: string): Promise<string | undefined>;
     /** Edit a sent text message in place (PUT; the platform caps edits at 20 per message). */
     editTextMessage(messageId: string, text: string): Promise<void>;

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

@@ -212,8 +212,8 @@ export function createFeishuApi(opts) {
             let first = true;
             for (const chunk of chunks) {
                 const content = JSON.stringify({ text: chunk });
-                // A normal group quote-replies only the first chunk — N reply-quotes would be noise. A topic
-                // must reply_in_thread on EVERY chunk; a plain chat send would leak continuations to the main group.
+                // A normal group quote-replies only the first chunk — N reply-quotes would be noise. A thread
+                // must reply_in_thread on EVERY chunk; a plain chat send would leak continuations to main chat.
                 const reply = target.replyTo !== undefined && (first || target.replyInThread === true);
                 const id = reply
                     ? await api.replyMessage(target.replyTo, "text", content, {

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

@@ -17,6 +17,16 @@ export interface FeishuChannelOptions {
      *  handshake from event signature verification; that narrow path is authenticated after decryption
      *  by the Verification Token. Must match the console exactly. */
     encryptKey?: string;
+    /** Direct-message context + delivery policy. `threaded` (default) gives every top-level p2p message
+     * its own session, creates a platform thread for the answer, and routes later thread messages back
+     * by root message id. `continuous` keeps one session per p2p chat and sends ordinary unquoted replies. */
+    directMessageSession?: "continuous" | "threaded";
+    /** Group-message context + delivery policy. `threaded` (default) gives every top-level summoned
+     * message its own session and platform thread; later bare user messages in that managed thread answer
+     * in the same root session, while @other-only discussion buffers. `continuous` preserves the legacy
+     * chat/topic sessions (`chat_id` / `chat_id:thread_id`). Buffering and bare continuations require
+     * `im:message.group_msg`. */
+    groupMessageSession?: "continuous" | "threaded";
     /** Policy: whether/where to answer an event (return null to ignore). Defaults to {@link defaultFeishuRoute}. */
     route?: (event: FeishuMessageEvent) => FeishuRoute | null;
     /** Customer-facing failure text for the chat (the dev-facing full `details` always go to the operator
@@ -33,4 +43,4 @@ export interface FeishuChannelOptions {
 /** Build the canonical Feishu channel. Lark calls the internal profile-bound builder below. */
 export declare function feishuChannel(opts: FeishuChannelOptions): ChannelModule;
 /** Internal compatibility seam: protocol behavior comes from Feishu; the profile binds cloud edges. */
-export declare function buildFeishuChannel(profile: FeishuCloudProfile, { appId, appSecret, verificationToken, encryptKey, route, onError, baseUrl, queueNoticeDelayMs, }: FeishuChannelOptions, factoryName: string): ChannelModule;
+export declare function buildFeishuChannel(profile: FeishuCloudProfile, { appId, appSecret, verificationToken, encryptKey, directMessageSession, groupMessageSession, route, onError, baseUrl, queueNoticeDelayMs, }: FeishuChannelOptions, factoryName: string): ChannelModule;

package/dist/channels/feishu/feishu.js

@@ -1,5 +1,5 @@
 /**
- * Canonical Feishu bot-channel engine: verify webhook → answer url_verification → dedup → route → run
+ * 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
  * international binds this engine through an explicit compatibility profile because its control plane
  * trails Feishu; protocol reuse does not make Lark the design center.
@@ -16,10 +16,13 @@ import { ensureStateHome } from "../state.js";
 import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "../turn-store.js";
 import { FEISHU_CLOUD } from "./cloud.js";
+import { collectFeishuBufferedAttachments, createFeishuContextBuffer, feishuBufferPlaceKey, feishuBufferText, } from "./context-buffer.js";
 import { decryptEvent, timingSafeEqualStr, verifySignature } from "./crypto.js";
 import { invokeFeishuTurn } from "./invoke-turn.js";
 import { createFeishuApi } from "./feishu-api.js";
-import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, parseContent, placeKey, } from "./parse.js";
+import { normalizeFeishuMessage } from "./normalize.js";
+import { createOwnedFeishuThreads } from "./owned-threads.js";
+import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderLabel, } from "./parse.js";
 import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, streamFeishuReply, } from "./preview.js";
 import { createSeenRing } from "./seen.js";
 // Canonical public surface; the Lark subpath aliases these types/functions at its compatibility boundary.
@@ -45,6 +48,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.chatId === "string" &&
         (r.replyTo === undefined || typeof r.replyTo === "string") &&
         (r.queueReplyTo === undefined || typeof r.queueReplyTo === "string") &&
@@ -59,7 +63,7 @@ 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, route, onError, baseUrl = profile.apiBase, queueNoticeDelayMs = QUEUE_NOTICE_DELAY_MS, }, factoryName) {
+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
@@ -71,6 +75,12 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
     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"`);
+    }
     return ({ agent, stateRoot }) => {
         const formatError = onError ?? defaultErrorMessage;
         const api = createFeishuApi({ kind, baseUrl, appId, appSecret });
@@ -90,7 +100,9 @@ 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 — downloaded files may carry chat content
+        ensureStateHome(stateHome); // create + self-ignore — buffers/files may carry chat content
+        const ownedThreads = createOwnedFeishuThreads(join(stateHome, "owned-threads.json"), label);
+        const buffer = createFeishuContextBuffer(join(stateHome, "buffers.json"), label);
         const store = createTurnStore(join(stateHome, "turns.json"), {
             label,
             isRecord: isStoredFeishuTurn,
@@ -177,10 +189,24 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
                 }
                 const startedAt = Date.now();
                 log.info(`${label} turn start: turn=${rec.id} session=${rec.session} chat=${rec.chatId}`);
+                // Snapshot background discussion at dequeue. Commit only this snapshot on `completed`, so a
+                // message arriving while the turn runs remains buffered for the next answered turn.
+                // ponytail: independent threaded roots in one main chat dequeue concurrently and may both fold
+                // this snapshot before either commits it. That fan-out loses nothing; claiming by buffer key
+                // would instead couple otherwise-independent root sessions and require failure rollback.
+                const { text: recent, consumed } = buffer.peek(rec.bufferKey);
+                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${rec.baseText}` : rec.baseText;
+                const buffered = collectFeishuBufferedAttachments(consumed, {
+                    images: rec.images.map((ref) => ({ messageId: ref.msg, key: ref.key })),
+                    files: rec.files.map((ref) => ({ messageId: ref.msg, key: ref.key, name: ref.name })),
+                });
                 try {
-                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, rec.baseText, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label }, { images: rec.images, files: rec.files, parentId: rec.parentId }, 
-                    // On completed, drop the intent — the turn provably lives in the session from here on.
-                    () => store.remove(rec.id)), api, targetOf(rec), formatError, rec.preview, label);
+                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
+                        // Drop intent first: a crash between these writes may re-fold answered context later,
+                        // but can never replay this turn after its context was removed.
+                        store.remove(rec.id);
+                        buffer.commit(rec.bufferKey, consumed);
+                    }), api, targetOf(rec), formatError, rec.preview, label);
                     log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
                 }
                 catch (error) {
@@ -195,13 +221,13 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
                 }
             },
         });
-        // Accept a turn: persist its intent (pre-ACK; a failed write throws → webhook 500 → redeliver),
-        // record its id in the dedup ring (post-decision insurance, best-effort), enqueue it. Recovery
-        // re-enqueues a crash-surviving turn WITHOUT re-persisting.
+        // Accept a turn: persist its intent before the ACK, then record the platform delivery id and enqueue
+        // it. The ordering is deliberate: recording first could turn a failed intent write into silent loss
+        // when the platform redelivers. Recovery re-enqueues a crash survivor without re-persisting it.
         const submit = (rec, persist) => {
             if (persist) {
-                store.add(toStored(rec));
-                seen.add(rec.id);
+                store.add(toStored(rec)); // failed write → webhook 500 → platform redelivery
+                seen.add(rec.id); // post-persist, best-effort protection from documented duplicate pushes
             }
             queue.accept(rec);
         };
@@ -218,8 +244,12 @@ 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)
-            submit({ ...intent, preview: undefined }, false);
+        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);
@@ -311,40 +341,123 @@ export function buildFeishuChannel(profile, { appId, appSecret, verificationToke
             if (!m?.message_id || !m.chat_id)
                 return new Response(null, { status: 200 });
             if (seen.has(m.message_id)) {
-                log.debug(`${label} duplicate push for message ${m.message_id} — already accepted, skipping`);
+                log.debug(`${label} duplicate push for message ${m.message_id} — already persisted, skipping`);
                 return new Response(null, { status: 200 });
             }
-            const r = decide(event);
+            let r = decide(event);
+            const normalized = normalizeFeishuMessage(event);
+            if (!normalized)
+                return new Response(null, { status: 200 });
+            const bufferKey = feishuBufferPlaceKey(normalized.conversation);
+            const isHumanGroup = event.sender?.sender_type === "user" && m.chat_type === "group";
+            const managedThread = groupMessageSession === "threaded" &&
+                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)
+                r = {};
             if (!r) {
-                log.debug(`${label} not summoned — ignoring message ${m.message_id} (chat ${m.chat_id}, ${m.chat_type})`);
+                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,
+                        }));
+                        // Pre-ACK persistence: a write failure rejects the webhook so the platform can redeliver.
+                        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); // post-persist: a redelivery cannot duplicate buffered context
+                        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})`);
+                }
                 return new Response(null, { status: 200 });
             }
             {
-                const session = r.session ?? placeKey(m);
+                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;
-                // Reply to the summoning message in groups (threads the answer under the asker; stays inside a
-                // topic); a 1:1 p2p chat needs no reply-quote. Only when the RESOLVED target is the message's own
-                // chat: a route that redirects elsewhere must not quote a same-id message in the wrong place.
+                // 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 = m.chat_type !== "p2p" && sameTarget ? m.message_id : undefined;
-                // Queue feedback always identifies the exact ask, including p2p. Ordinary p2p answers remain
-                // unquoted unless the turn actually waited long enough for its queue preview to mount.
+                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 content = parseContent(m);
+                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() !== "" || content.imageKeys.length > 0 || content.fileRefs.length > 0) {
+                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: replyTo !== undefined && m.thread_id !== undefined ? true : undefined,
-                        parentId: m.parent_id,
-                        images: content.imageKeys.map((key) => ({ msg: m.message_id, key })),
-                        files: content.fileRefs.map((f) => ({ msg: m.message_id, key: f.key, name: f.name })),
+                        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);
                 }
             }

package/dist/channels/feishu/invoke-turn.d.ts

@@ -6,13 +6,13 @@
  * half touches the Open API + disk; split from feishu.ts so the factory keeps only wiring and the
  * per-turn lifecycle.
  *
- * Everything here is PRIMARY input — the summoning message's own attachments and the message the user
- * explicitly replied to — so any load failure THROWS and the caller sees a `failed` event: the agent
- * never runs on inputs the user pointed at but we failed to load. (The telegram channel's second,
- * degrade-per-attachment tier is its context BUFFER — background material; Feishu grows that tier only
- * with the buffer itself, which needs the sensitive all-group-messages scope.)
+ * Inputs have two tiers. PRIMARY is the summoning message plus the message it explicitly replied to;
+ * any load failure there aborts visibly so the Agent never runs without an input the user pointed at.
+ * BUFFERED resources come from earlier un-summoned thread/group discussion and degrade per attachment:
+ * one expired background file must not block the current ask or hide its still-readable siblings.
  */
 import { type Agent, type AgentEvent } from "../../agent.ts";
+import type { FeishuBufferedRef } from "./context-buffer.ts";
 import type { FeishuApi } from "./feishu-api.ts";
 /** Everything the transport needs to fetch a turn's attachments. */
 export interface FeishuTurnTransport {
@@ -28,13 +28,19 @@ export interface FeishuAttachmentInput {
     key: string;
     name?: string;
 }
-/** A turn's attachment inputs: the summoning message's own resources, plus the message it replied to
- *  (resolved here — content and resources both). */
+/** A turn's primary resources plus background resources folded from the context buffer. */
 export interface FeishuTurnAttachments {
-    images: FeishuAttachmentInput[];
-    files: FeishuAttachmentInput[];
-    /** The replied-to message's id, when the summon is a reply. */
-    parentId?: string;
+    primary: {
+        images: FeishuAttachmentInput[];
+        files: FeishuAttachmentInput[];
+        /** The replied-to message's id, when the summon is a reply. */
+        parentId?: string;
+    };
+    buffered: {
+        files: FeishuBufferedRef[];
+        images: FeishuBufferedRef[];
+        skipped: number;
+    };
 }
 /** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
  *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
@@ -45,8 +51,8 @@ export interface BusyRetry {
     maxWaitMs: number;
 }
 /**
- * Run one turn: resolve its inputs, then stream agent.invoke. An input failure surfaces as a `failed`
- * event (never a silent drop). `onCompleted` (if given) fires on the turn's `completed` event — the
+ * Run one turn: resolve its inputs, then stream agent.invoke. A primary-input failure surfaces as a
+ * `failed` event (never a silent drop). `onCompleted` (if given) fires on the `completed` event — the
  * durable-commit point; the caller uses it to remove the turn intent (turn-store L1) at the earliest
  * moment the turn provably lives in the session.
  *