@fastagent-sh/fastagent 0.17.1 → 0.18.0

package/dist/agent.d.ts

@@ -19,6 +19,17 @@ export interface Prompt {
 export interface Scope {
     /** Opaque session anchor: turns of the same logical conversation MUST reuse the same value. */
     session: string;
+    /** EXTENSION (SPEC §8): the session this one branched from — a channel sets it when the place it
+     *  is invoking for was born out of another place (a thread opened in a room). Read ONLY when
+     *  `session` does not exist yet: an engine that understands it seeds the NEW session from the
+     *  parent once, at creation; after that the field is ignored, and an engine that does not
+     *  understand it ignores it entirely (the session starts empty, yesterday's behavior). */
+    parentSession?: string;
+    /** EXTENSION (SPEC §8): opaque markers that MAY locate the branch point inside `parentSession` —
+     *  e.g. platform message ids its transcript embeds. Best-effort by design: the first marker found
+     *  in the parent's transcript wins, and no match falls back to the parent's present. Meaningless
+     *  without `parentSession`. */
+    branchHints?: string[];
 }
 export type AgentEvent = {
     type: "text";

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

@@ -69,11 +69,13 @@ export interface FeishuApi {
      *
      *  `sender` is typed rather than `unknown` because the referent path READS it: an app-sent message
      *  whose id is THIS app's is the agent's own, which the prompt must say instead of attributing it to
-     *  "user cli_…". The message object carries more (`parent_id`, `root_id`, `thread_id`); they stay
-     *  unnamed until something reads them — this type is the surface in use, not a mirror of the wire. */
+     *  "user cli_…". `parent_id` is read by the reply-chain walk (invoke-turn): the message this one
+     *  itself replied to. The message object carries more (`root_id`, `thread_id`); they stay unnamed
+     *  until something reads them — this type is the surface in use, not a mirror of the wire. */
     getMessage(messageId: string): Promise<{
         message_id?: string;
         msg_type?: string;
+        parent_id?: string;
         body?: {
             content?: string;
         };

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, loadStateFile, removeRetiredStateFile, saveStateFile } from "../state.js";
+import { ensureStateHome, loadStateFile, saveStateFile } from "../state.js";
 import { dispatchStop, isStopText } from "../stop-command.js";
 import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "../turn-store.js";
@@ -58,6 +58,8 @@ function isStoredFeishuTurn(t) {
         (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") &&
         refs(r.images) &&
         refs(r.files) &&
         typeof r.attempts === "number");
@@ -160,10 +162,6 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         }
         const stateHome = join(stateRoot, "channels", kind);
         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);
         // The cached bot identity (rationale at the botInfo block above): seed synchronously — the
         // factory runs to completion before any promise resolves, so botOpenId is still unset here and
         // the seed is what the first envelope's dispatch sees. Refresh keeps the file current.
@@ -309,13 +307,31 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 // 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, {
+                // PEEK and never commit: the room still owes this discussion to its OWN memory (§8).
+                const room = rec.roomBufferKey !== undefined ? buffer.peek(rec.roomBufferKey) : undefined;
+                const roomBlock = room?.text
+                    ? `[recent discussion in the room this thread branched from — not yet answered there:\n${room.text}\n]\n\n`
+                    : "";
+                const threadBlock = recent ? `[recent group discussion:\n${recent}\n]\n\n` : "";
+                const prompt = `${roomBlock}${threadBlock}${rec.baseText}`;
+                // Room entries FIRST: the collector keeps the TAIL under its cap, so the thread's own
+                // attachments win the slots.
+                const buffered = collectFeishuBufferedAttachments([...(room?.consumed ?? []), ...consumed], {
                     images: rec.images.map((ref) => ({ messageId: ref.msg, key: ref.key })),
                     files: rec.files.map((ref) => ({ messageId: ref.msg, key: ref.key, name: ref.name })),
                 });
+                // Recorded at ingress (see submit) — never re-derived from the session key, which may be a
+                // routed OPAQUE id that only looks like a place key.
+                const parentSession = rec.parentSession;
                 try {
-                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label, appId }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
+                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, {
+                        api,
+                        chatId: rec.chatId,
+                        filesDir: join(stateHome, "files"),
+                        label,
+                        appId,
+                        ...(parentSession !== undefined ? { parentSession } : {}),
+                    }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
                         // 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);
@@ -465,7 +481,19 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             // 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 routed = r.session;
+            const session = routed ?? placeKey(kind, m);
+            // Lineage is recorded ONLY for the default place-derived session. A routed session id is
+            // OPAQUE (the route contract), and re-parsing it as a place key would let a three-segment id
+            // like "tenant:user:alice" masquerade as a thread and inherit from "tenant:user" — a
+            // cross-session injection. Derived from the MESSAGE (the fact this channel owns), at record
+            // time, where routed-ness is still known; the dequeue path only reads it back.
+            const parentSession = 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. Keyed by the
+            // SOURCE chat, never the answer target a route may name (§8).
+            const roomBufferKey = parentSession !== undefined && !threadParticipants.agentSpokeIn(session)
+                ? feishuBufferPlaceKey({ chatId: m.chat_id })
+                : undefined;
             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,
@@ -517,6 +545,8 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 // already have; it also pins WHICH message is being answered, which a long thread benefits
                 // from anyway.
                 parentId: m.parent_id,
+                ...(parentSession !== undefined ? { parentSession } : {}),
+                ...(roomBufferKey !== undefined ? { roomBufferKey } : {}),
                 images,
                 files,
             }, true);

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

@@ -8,8 +8,9 @@
  *
  * 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.
+ * BUFFERED resources come from earlier un-summoned thread/group discussion and from reply-chain
+ * ancestors, and degrade per attachment: one expired background file must not block the current ask
+ * or hide its still-readable siblings.
  */
 import type { Agent, AgentEvent } from "../../agent.ts";
 import { type BusyRetry } from "../invoke-turn-kit.ts";
@@ -25,6 +26,11 @@ export interface FeishuTurnTransport {
      *  sender is an app. Needed to tell the agent's OWN messages from any other bot's in the same chat:
      *  `sender_type` alone says "some app", which is not the question the referent path asks. */
     appId: string;
+    /** The place this thread branched from (the chat's main place), when the turn runs in a thread —
+     *  rides the Scope's lineage extension so a NEW thread session starts from what the room knew
+     *  (participant-model.md §5). The engine reads it once, at session creation; every later turn
+     *  carries it inertly. */
+    parentSession?: string;
 }
 /** An attachment reference: the resource key inside its CARRYING message (the resource API addresses
  *  bytes by message_id + key, so the pair travels together through the turn record). */

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

@@ -1,5 +1,6 @@
 import { log } from "../../log.js";
 import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
+import { BUFFER_ATTACH_MAX } from "../context-buffer.js";
 import { parseContent } from "./parse.js";
 import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../text.js";
 /** The per-turn REPLY CONTRACT, appended to the prompt (not the system prompt). Two halves, one
@@ -10,14 +11,126 @@ import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../text.js";
 const REPLY_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card. This reply is " +
     "delivered to the current chat by the channel itself: do not call a send tool to answer the " +
     "current chat.)";
+/** How far up a reply chain the walk reads, beyond the replied-to message itself. The chain's natural
+ *  end is its ROOT — the platform threads every reply back to one — so this is an IO guard, not a
+ *  semantic boundary: each ancestor costs one serial `getMessage`, and a pathological chain must not
+ *  stall the turn. Field chains are 1–3 long; a capped walk says so in the block. */
+const MAX_CHAIN_ANCESTORS = 8;
+/** Attribution for a FETCHED message. 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.
+ *
+ *  OWN means THIS app, not "an app". A group can hold several bots, and `sender_type === "app"` is
+ *  true for every one of them — matching on it alone would tell the model it wrote another bot's
+ *  message. The identity to compare is the app id, because an app sender carries `id_type: "app_id"`:
+ *  the cached bot open_id answers a different question (who was @mentioned) and would never match
+ *  here. A missing or unexpected id fails CLOSED — labelled by id, never claimed as the agent's own.
+ *  And an app is not a person: labelling another bot's message "user cli_…" is the same
+ *  misattribution in a quieter form, so the noun follows the sender type. */
+function fetchedSenderLabel(sender, appId) {
+    const appSender = sender?.sender_type === "app";
+    const senderId = sender?.id;
+    if (appSender && senderId === appId)
+        return "you, the agent";
+    return senderId ? `${appSender ? "app" : "user"} ${senderId}` : undefined;
+}
+/**
+ * Walk the reply chain ABOVE the replied-to message, to its root. Quoting a reply points at one link
+ * of an exchange; the pointer is only fully resolved when the model can read what that link was
+ * replying to — all the way up, because the platform defines where the chain ends (its root), which
+ * is what makes the walk bounded by STRUCTURE rather than by a level count someone picked.
+ *
+ * This is pointer resolution, not history. Session memory — what this place already knows — is a
+ * different track (design/participant-model.md §8): a one-hop version of this walk was removed once
+ * for trying to be that substitute; it returns doing only the pointer's job, which is also why it
+ * walks through ANY author's message — the chain is the platform's structure, not a conversation the
+ * agent took part in. The repetition this implies (an established session re-reads chain text it may
+ * already hold, each reply turn) is accepted deliberately and bounded: ancestors are CONTEXT, not
+ * the ask, so their text shares ONE further `REFERENT_MAX_CODE_POINTS` budget across the whole chain
+ * — the walk costs at most one more referent — while the pointed-at referent keeps its own full
+ * fidelity bound.
+ *
+ * Fail-open at every edge, but never silently at the model: any walk that ends short of the root —
+ * the ancestor cap, an exhausted text budget, an unreadable ancestor, a cycle — leaves the same
+ * neutral truncation line at the top of the block, because a chain rendered without it READS as
+ * complete and the model would take the oldest fetched node for the original ask. Unreadable
+ * ancestors and cycles also warn the operator; a cycle is corrupt platform data (reply chains are
+ * temporally acyclic by construction — a reply can only point at an EARLIER message — so one firing
+ * means the data, not the walk, is wrong).
+ */
+async function walkReplyChain(t, start, visited) {
+    const nodes = [];
+    const images = [];
+    const files = [];
+    // No parent above the referent = no chain — not a truncated one. The marker below is only for
+    // walks that END SHORT of a root that exists.
+    if (start === undefined)
+        return { block: "", images, files, ids: [] };
+    let reachedRoot = false;
+    let textBudget = REFERENT_MAX_CODE_POINTS;
+    let next = start;
+    while (next !== undefined) {
+        if (visited.has(next)) {
+            log.warn(`${t.label} reply chain points back to already-visited message ${next} — corrupt platform data; the walk ends here`);
+            break;
+        }
+        if (nodes.length >= MAX_CHAIN_ANCESTORS || textBudget <= 0)
+            break;
+        // The annotation breaks a control-flow-analysis cycle (id → msg → next → id) that trips TS7022.
+        const id = next;
+        visited.add(id);
+        let failure;
+        const msg = await t.api.getMessage(id).catch((error) => {
+            failure = String(error);
+            return undefined;
+        });
+        if (!msg) {
+            log.warn(`${t.label} could not read reply-chain message ${id} (${failure ?? "no such message"}) — the chain is rendered up to it`);
+            break;
+        }
+        const parsed = parseContent({
+            message_type: msg.msg_type ?? "unknown",
+            content: msg.body?.content ?? "",
+            mentions: msg.mentions,
+        });
+        const label = fetchedSenderLabel(msg.sender, t.appId);
+        const from = label ?? "reply chain";
+        for (const key of parsed.imageKeys)
+            images.push({ messageId: id, key, from });
+        for (const ref of parsed.fileRefs)
+            files.push({ messageId: id, key: ref.key, name: ref.name, from });
+        const text = truncateCodePointPrefix(parsed.text, textBudget) || "(empty)";
+        textBudget -= [...text].length;
+        nodes.push({ id, label, text });
+        if (msg.parent_id === undefined)
+            reachedRoot = true;
+        next = msg.parent_id;
+    }
+    nodes.reverse(); // fetched leaf→root; rendered oldest first, the way a transcript reads
+    const lines = nodes.map((node) => `(msg ${node.id}${node.label ? `, from ${node.label}` : ""}): ${node.text}`);
+    // One line for every way of ending short of the root — cap, budget, unreadable, cycle. It names no
+    // cause on purpose: the model needs the SHAPE (there is more above), the operator log has the why.
+    if (!reachedRoot)
+        lines.unshift("(…the chain continues above this point)");
+    return {
+        block: `\n[reply chain above it, oldest first:\n${lines.join("\n")}]`,
+        images,
+        files,
+        // Walked (fetched) order = nearest first — nodes were reversed for RENDERING above, so read the
+        // hint order off the rendered list backwards.
+        ids: nodes.map((node) => node.id).reverse(),
+    };
+}
 /**
- * Resolve a turn's inputs (module header): fetch the reply referent's content, then load every image
- * (vision) and file (disk). Primary failures throw; buffered resources degrade independently.
+ * Resolve a turn's inputs (module header): fetch the reply referent's content and resolve its reply
+ * chain, then load every image (vision) and file (disk). Primary failures throw; buffered resources
+ * degrade independently.
  */
 async function resolveTurnInputs(t, attachments) {
     const images = [...attachments.primary.images];
     const files = [...attachments.primary.files];
     let referentBlock = "";
+    let chain = { block: "", images: [], files: [], ids: [] };
     if (attachments.primary.parentId !== undefined) {
         const parentId = attachments.primary.parentId;
         // A referent is CONTEXT, not the ask. Losing it (deleted, restricted, unreadable) must not cost
@@ -49,32 +162,11 @@ async function resolveTurnInputs(t, attachments) {
                 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.
-            //
-            // OWN means THIS app, not "an app". A group can hold several bots, and `sender_type === "app"`
-            // is true for every one of them — matching on it alone would tell the model it wrote another
-            // bot's message. The identity to compare is the app id, because an app sender carries
-            // `id_type: "app_id"`: the cached bot open_id answers a different question (who was @mentioned)
-            // and would never match here. A missing or unexpected id fails CLOSED — labelled by id, never
-            // claimed as the agent's own.
-            const appSender = parent.sender?.sender_type === "app";
-            const senderId = parent.sender?.id;
-            const ownMessage = appSender && senderId === t.appId;
-            // An app is not a person: labelling another bot's message "user cli_…" is the same misattribution
-            // in a quieter form, so the noun follows the sender type.
-            const from = ownMessage ? "you, the agent" : senderId ? `${appSender ? "app" : "user"} ${senderId}` : undefined;
+            const from = fetchedSenderLabel(parent.sender, t.appId);
             referentBlock = `\n\n[replied-to message (msg ${parentId}${from ? `, from ${from}` : ""}): ${truncateCodePointPrefix(parsed.text, REFERENT_MAX_CODE_POINTS) || "(empty)"}]`;
-            // The chain STOPS here, at the one message the user pointed at. Walking further — to what that
-            // message was itself replying to — was built and removed: it reconstructs HISTORY out of reply
-            // pointers, and history is the session's job. That framing has no non-arbitrary answers (how
-            // many levels? what about the level above that? how is it deduplicated against what the session
-            // already holds? how does an IMAGE two levels up become prompt text at all?), and every one of
-            // those questions is a symptom of solving a session-layer problem in the prompt layer. The real
-            // gap it was papering over — a thread opened on a room answer starts with an EMPTY session while
-            // the room's session holds the exchange — belongs to memory inheritance (design/participant-
-            // model.md §8, rungs 3-4), where images and tool results come along for free because they are
-            // already in the history rather than being re-serialised into a prompt string.
+            // The referent's own parent starts the chain walk; the referent id seeds the cycle guard.
+            chain = await walkReplyChain(t, parent.parent_id, new Set([parentId]));
+            referentBlock += chain.block;
         }
     }
     // Primary first and fail-fast: these are resources the current user explicitly pointed at.
@@ -88,8 +180,28 @@ async function resolveTurnInputs(t, attachments) {
     // downloaded twice or rendered twice in the manifest.
     const primaryImages = new Set(images.map((ref) => `${ref.msg}\u0000${ref.key}`));
     const primaryFiles = new Set(files.map((ref) => `${ref.msg}\u0000${ref.key}`));
-    const bufferedImages = attachments.buffered.images.filter((ref) => !primaryImages.has(`${ref.messageId}\u0000${ref.key}`));
-    const bufferedFiles = attachments.buffered.files.filter((ref) => !primaryFiles.has(`${ref.messageId}\u0000${ref.key}`));
+    // Chain ancestors and the context buffer share ONE background budget: BUFFER_ATTACH_MAX per kind.
+    // The cap is part of the tier's meaning, not an accident of who collected the ref — a rich-text
+    // ancestor must not turn the walk into an unbounded fan-out of downloads. Chain refs take slots
+    // FIRST: they are the direct upstream of the message the user pointed at, buffer refs are ambient
+    // discussion. Duplicates (a chain that points back into still-buffered discussion) count once, and
+    // what the cap drops is counted into the missing-attachments note like every other unloaded ref.
+    const capMerge = (chainRefs, bufferRefs, primary) => {
+        const seen = new Set();
+        const merged = [];
+        for (const ref of [...chainRefs, ...bufferRefs]) {
+            const identity = `${ref.messageId}\u0000${ref.key}`;
+            if (primary.has(identity) || seen.has(identity))
+                continue;
+            seen.add(identity);
+            merged.push(ref);
+        }
+        return { kept: merged.slice(0, BUFFER_ATTACH_MAX), dropped: Math.max(0, merged.length - BUFFER_ATTACH_MAX) };
+    };
+    const mergedImages = capMerge(chain.images, attachments.buffered.images, primaryImages);
+    const mergedFiles = capMerge(chain.files, attachments.buffered.files, primaryFiles);
+    const bufferedImages = mergedImages.kept;
+    const bufferedFiles = mergedFiles.kept;
     const backgroundImages = [];
     const backgroundFiles = [];
     let lost = 0;
@@ -114,7 +226,7 @@ async function resolveTurnInputs(t, attachments) {
             log.warn(`${t.label} could not load an earlier (buffered) attachment: ${String(result.reason)}`);
         }
     }
-    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped);
+    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped + mergedImages.dropped + mergedFiles.dropped);
     const backgroundImageManifest = backgroundImagesManifest(imageRefs.length, backgroundImages.map(({ ref }) => ref));
     const allFiles = [
         ...downloaded,
@@ -127,6 +239,7 @@ async function resolveTurnInputs(t, attachments) {
     return {
         images: allImages.length ? allImages : undefined,
         promptSuffix: `${referentBlock}${missingNote}${backgroundImageManifest}${attachedFilesManifest(allFiles)}`,
+        referentIds: [...(attachments.primary.parentId !== undefined ? [attachments.primary.parentId] : []), ...chain.ids],
     };
 }
 /**
@@ -144,5 +257,11 @@ export async function* invokeFeishuTurn(agent, session, text, transport, attachm
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${REPLY_INSTRUCTION}`, images: resolved.images };
-    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
+    // A thread turn names its lineage: parent place + the message ids that can locate the branch point
+    // (the referent and its chain — nearest first). The engine reads them ONCE, when the thread's
+    // session does not exist yet; on every later turn they ride along inertly.
+    const scope = transport.parentSession === undefined
+        ? { session }
+        : { session, parentSession: transport.parentSession, branchHints: resolved.referentIds };
+    yield* streamTurnWithBusyRetry(agent, scope, prompt, { label: transport.label, onCompleted, busyRetry });
 }

package/dist/channels/feishu/parse.js

@@ -52,6 +52,12 @@ export function cloudEnvelope(event, tag) {
         `chat ${message.chat_id} (${message.chat_type})`,
         message.thread_id ? `topic ${message.thread_id}` : undefined,
         from ? `from ${from}` : undefined,
+        // The message's own id is LOAD-BEARING, not decoration: it is the only way this message's id
+        // enters the session transcript, and session inheritance locates a thread's branch point by
+        // searching the parent transcript for exactly these ids (scope.branchHints — sessions.ts).
+        // Remove it and every thread quietly inherits from the room's present instead of the branch
+        // point. It also lets the model name what it is answering in a busy chat.
+        `msg ${message.message_id}`,
     ]
         .filter(Boolean)
         .join(", ");

package/dist/channels/http.js

@@ -56,14 +56,27 @@ export function createInvokeHandler(agent) {
         catch {
             return text("invalid json\n", 400);
         }
-        const { session, text: promptText } = (payload ?? {});
+        const { session, text: promptText, parentSession, branchHints, } = (payload ?? {});
         if (typeof session !== "string" || typeof promptText !== "string") {
             return text('need { "session": string, "text": string }\n', 400);
         }
         // ^ the request shape INVOKE_EXAMPLE_BODY (below) must keep satisfying.
+        // The OPTIONAL lineage extension (Scope): malformed values are a 400, not a silent drop — a
+        // caller that sent them meant them.
+        if (parentSession !== undefined && typeof parentSession !== "string") {
+            return text('"parentSession" must be a string\n', 400);
+        }
+        if (branchHints !== undefined && !(Array.isArray(branchHints) && branchHints.every((h) => typeof h === "string"))) {
+            return text('"branchHints" must be an array of strings\n', 400);
+        }
         // Take the iterator explicitly so the stream's cancel() (consumer disconnect) can return() it and
         // run invoke's cancellation cleanup (SPEC MUST 3). pull = backpressure: the next event is produced on demand.
-        const iterator = agent.invoke({ session }, { text: promptText })[Symbol.asyncIterator]();
+        const iterator = agent
+            .invoke({
+            session,
+            ...(parentSession !== undefined ? { parentSession } : {}),
+            ...(branchHints !== undefined ? { branchHints } : {}),
+        }, { text: promptText })[Symbol.asyncIterator]();
         // Heartbeats: a QUIET stream (a long tool call, no events) is normal here — remote consumers
         // distinguish "quiet but alive" from a dead connection by byte arrival, so silence must not
         // look identical to a black hole (SSE comments are ignored by spec-conforming parsers).

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

@@ -10,7 +10,7 @@
  * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
  * message-scoped Feishu keys, Slack file objects) are real differences.
  */
-import { type Agent, type AgentEvent, type Prompt } from "../agent.ts";
+import { type Agent, type AgentEvent, type Prompt, type Scope } from "../agent.ts";
 /** 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
  *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
@@ -35,7 +35,10 @@ export declare const DEFAULT_BUSY_RETRY: BusyRetry;
  * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
  * is ever re-run.
  */
-export declare function streamTurnWithBusyRetry(agent: Agent, session: string, prompt: Prompt, options: {
+export declare function streamTurnWithBusyRetry(agent: Agent, 
+/** The full scope, not a session string — channels that set extension fields (lineage) pass them
+ *  through here; channels that don't pass `{ session }` and nothing changes. */
+scope: Scope, prompt: Prompt, options: {
     label: string;
     onCompleted?: () => void;
     busyRetry?: BusyRetry;

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

@@ -33,13 +33,17 @@ export const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
  * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
  * is ever re-run.
  */
-export async function* streamTurnWithBusyRetry(agent, session, prompt, options) {
+export async function* streamTurnWithBusyRetry(agent, 
+/** The full scope, not a session string — channels that set extension fields (lineage) pass them
+ *  through here; channels that don't pass `{ session }` and nothing changes. */
+scope, prompt, options) {
     const { label, onCompleted, busyRetry = DEFAULT_BUSY_RETRY } = options;
+    const session = scope.session;
     const deadline = Date.now() + busyRetry.maxWaitMs;
     for (;;) {
         let retryBusy = false;
         let first = true;
-        for await (const e of agent.invoke({ session }, prompt)) {
+        for await (const e of agent.invoke(scope, prompt)) {
             if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
                 retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
                 break;

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

@@ -59,5 +59,5 @@ export async function* invokeSlackTurn(agent, session, text, transport, attachme
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
-    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
+    yield* streamTurnWithBusyRetry(agent, { session }, prompt, { label: transport.label, onCompleted, busyRetry });
 }

package/dist/channels/slack/slack.js

@@ -7,7 +7,7 @@ import { text } from "../respond.js";
 import { createSeenRing } from "../seen.js";
 import { createThreadParticipants } from "../thread-participants.js";
 import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome, removeRetiredStateFile } from "../state.js";
+import { ensureStateHome } from "../state.js";
 import { dispatchStop, isStopText } from "../stop-command.js";
 import { codePointPrefix } from "../text.js";
 import { createTurnQueue } from "../turn-queue.js";
@@ -141,10 +141,6 @@ export function slackChannel(options) {
          *  under a custom route is the `routed.session === undefined` condition on the write, not the
          *  absence of a route: a route that supplies its own session records nothing here. */
         const threadKey = (teamId, channelId, threadTs) => `slack:${teamId}:${channelId}:${threadTs}`;
-        // 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 welcomed = createWelcomedUsers(join(stateHome, "welcomed.json"), label);
         const buffer = createSlackContextBuffer(join(stateHome, "buffers.json"), label);
         const store = createTurnStore(join(stateHome, "turns.json"), {

package/dist/channels/state.d.ts

@@ -4,13 +4,3 @@ export declare function ensureStateHome(dir: string): void;
  *  caller owns shape validation (a `<T>` here would be an unchecked cast wearing a type). */
 export declare function loadStateFile(path: string): unknown;
 export declare function saveStateFile(path: string, value: unknown): void;
-/**
- * Drop a state file a redesign retired. Best-effort by design: a leftover file is untidy, not fatal,
- * so a failure is debug-level and never blocks a boot. Only for files that are pure CACHE — anything
- * whose loss changes behaviour needs a migration, not a delete.
- *
- * Shared because a retired file is usually retired in every channel at once: one best-effort
- * semantic, one log shape, one place to check what "retired" means here. (The removal DEADLINE is not
- * here — it lives in test/migration-deadline.test.ts, which names every call site to delete.)
- */
-export declare function removeRetiredStateFile(stateHome: string, name: string, label: string): void;

package/dist/channels/state.js

@@ -12,8 +12,8 @@
  * is an ENVIRONMENT error the operator must fix: it throws, and construction fails loudly — booting
  * with silently-empty state would hide real data behind a config mistake.
  */
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { log } from "../log.js";
 /** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
 export function ensureStateHome(dir) {
@@ -48,20 +48,3 @@ export function saveStateFile(path, value) {
     writeFileSync(tmp, JSON.stringify(value));
     renameSync(tmp, path);
 }
-/**
- * Drop a state file a redesign retired. Best-effort by design: a leftover file is untidy, not fatal,
- * so a failure is debug-level and never blocks a boot. Only for files that are pure CACHE — anything
- * whose loss changes behaviour needs a migration, not a delete.
- *
- * Shared because a retired file is usually retired in every channel at once: one best-effort
- * semantic, one log shape, one place to check what "retired" means here. (The removal DEADLINE is not
- * here — it lives in test/migration-deadline.test.ts, which names every call site to delete.)
- */
-export function removeRetiredStateFile(stateHome, name, label) {
-    try {
-        rmSync(join(stateHome, name), { force: true });
-    }
-    catch (error) {
-        log.debug(`${label} could not remove the obsolete ${name}: ${String(error)}`);
-    }
-}

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

@@ -76,5 +76,5 @@ export async function* invokeTurn(agent, session, text, transport, attachments,
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${HTML_INSTRUCTION}`, images: resolved.images };
-    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: "[telegram]", onCompleted, busyRetry });
+    yield* streamTurnWithBusyRetry(agent, { session }, prompt, { label: "[telegram]", onCompleted, busyRetry });
 }

package/dist/channels/thread-participants.d.ts

@@ -6,6 +6,13 @@ export interface ThreadParticipants {
      * get wrong twice, and "a second human restores the mention requirement" must have one place to change.
      */
     admitsBareMessage(key: string): boolean;
+    /**
+     * Has the agent answered into this thread before — the "first answered turn" fact
+     * (participant-model.md §8), unlike {@link ThreadParticipants.admitsBareMessage} which also weighs
+     * the second-human rule. An evicted record answers false (this store is a cache — see the header),
+     * so gate a repeatable read on it, never a durable claim.
+     */
+    agentSpokeIn(key: string): boolean;
     /**
      * Merge in what was just heard. Idempotent; a failed write is a warning, never a failed delivery.
      *

package/dist/channels/thread-participants.js

@@ -68,6 +68,9 @@ export function createThreadParticipants(path, label) {
             const heard = records.get(key);
             return heard?.agentSpoke === true && heard.humans.length <= 1;
         },
+        agentSpokeIn(key) {
+            return records.get(key)?.agentSpoke === true;
+        },
         merge(key, heard) {
             const previous = records.get(key);
             const humans = new Set(previous?.humans ?? []);