@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/channels/kit/preview-kit.js

@@ -1,3 +1,4 @@
+import { answerText } from "../../answer-text.js";
 import { truncateCodePointPrefix, truncateCodePointSuffix } from "./text.js";
 /** The customer-facing default: neutral, no leaked internals. */
 export function defaultErrorMessage(failed) {
@@ -6,47 +7,67 @@ export function defaultErrorMessage(failed) {
         : "⚠️ Sorry, something went wrong. Try rephrasing, or check I have access to what you need.";
 }
 /**
- * Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying` event): neutral, no
+ * Customer-facing live-preview line for a harness-internal retry backoff (the advisory `retrying` event): neutral, no
  * leaked internals — the reason stays in operator logs.
  */
 export const RETRY_NOTICE = "⏳ Temporary problem — retrying…";
 /** The placeholder shown before any reasoning/tool/text arrives. */
 export const THINKING_PLACEHOLDER = "💭 Thinking…";
 export function createTurnView() {
-    return { thinking: "", tools: [], toolById: new Map(), answer: "", retrying: false };
+    const view = {
+        thinking: "",
+        tools: [],
+        toolById: new Map(),
+        answer: "",
+        textOf: answerText(),
+        retrying: false,
+    };
+    return view;
 }
+/** Fold one event of a turn's invoke into its view; true when what a renderer shows changed. */
 export function applyTurnEvent(view, e, now = Date.now()) {
     const closedRetry = view.retrying && e.type !== "retrying";
     if (closedRetry)
         view.retrying = false;
+    const appended = (text) => {
+        if (text === "")
+            return closedRetry;
+        view.answer += text;
+        if (view.answerSince === undefined && view.answer.trim() !== "")
+            view.answerSince = now;
+        return true;
+    };
     switch (e.type) {
-        case "text":
-            view.answer += e.delta;
-            if (view.answerSince === undefined && view.answer.trim() !== "")
-                view.answerSince = now;
-            return true;
-        case "thinking":
-            view.thinking += e.delta;
+        case "delta":
+            if (e.channel === "text")
+                return appended(view.textOf(e));
+            view.thinking += e.text;
             return true;
         case "tool_started": {
             const arg = summarizeToolArgs(e.args);
             const name = humanizeToolName(e.name);
             const line = { label: arg ? `${name} ${arg}` : name, status: "running" };
             view.tools.push(line);
-            view.toolById.set(e.id, line);
+            view.toolById.set(e.toolCallId, line);
             return true;
         }
         case "tool_progress": {
-            const line = view.toolById.get(e.id);
+            const line = view.toolById.get(e.toolCallId);
             if (line?.status !== "running")
                 return closedRetry;
             line.progress = e.text;
             return true;
         }
-        case "tool_ended": {
-            const line = view.toolById.get(e.id);
-            if (line)
-                line.status = e.isError ? "error" : "ok";
+        case "entry": {
+            if (e.entry.kind === "assistant")
+                return appended(view.textOf(e));
+            if (e.entry.kind !== "tool_result")
+                return closedRetry;
+            const data = e.entry.data;
+            const line = data.toolCallId === undefined ? undefined : view.toolById.get(data.toolCallId);
+            if (!line)
+                return closedRetry;
+            line.status = data.isError === true ? "error" : "ok";
             return true;
         }
         case "retrying":

package/dist/channels/kit/room-threads.d.ts

@@ -0,0 +1,46 @@
+/** A channel's reads of its rooms' threads. Each resolves to text for the model; a failed read rejects. */
+export interface ThreadReader {
+    /** The room's recent threads, newest first, each with its id. */
+    list(room: string): Promise<string>;
+    /** One thread of the room, as it reads now. Rejects for a thread that is not in this room. */
+    read(room: string, threadId: string): Promise<string>;
+}
+/** The rooms of a channel's running group turns, by session id, and how to read their threads. */
+export interface RoomThreads {
+    /** The turn of `sessionId` runs in `room` until the returned function is called. */
+    enter(sessionId: string, room: string): () => void;
+    readonly reader: ThreadReader;
+    roomOf(sessionId: string): string | undefined;
+}
+export declare function createRoomThreads(reader: ThreadReader): RoomThreads;
+export declare function registerRoomThreads(kind: string, stateDir: string, rooms: RoomThreads): void;
+/** The threads the turn running in `sessionId` may read, from the `kind` channel it was asked through. */
+export declare function roomThreads(kind: string, sessionId: string | undefined): {
+    list(): Promise<string>;
+    read(threadId: string): Promise<string>;
+};
+/** One thread of a room, as a list shows it. */
+export interface ThreadSummary {
+    id: string;
+    /**
+     * The one time a list can vouch for, in milliseconds since the epoch: its newest message, or only when it started
+     * where its replies are not visible (a Feishu ordinary group lists a thread's root only).
+     */
+    time: {
+        at: number;
+        is: "last active" | "started";
+    };
+    /** When the platform says (Slack); Feishu's listing does not. */
+    replies?: number;
+    /** Its first message the read saw: the thread's opener, wherever the platform lists it. */
+    first: {
+        label: string;
+        text: string;
+    };
+}
+/**
+ * The list a tool returns: newest first by the time each line shows, each with the id that reads it, and what was
+ * left out said. A thread shown by when it started may have gone on since, and the list says so, since whether a
+ * problem was resolved is what a reader most often wants to know.
+ */
+export declare function threadList(threads: readonly ThreadSummary[], scanned: string): string;

package/dist/channels/kit/room-threads.js

@@ -0,0 +1,81 @@
+/**
+ * What a thread-reading tool may reach: the threads of the room its turn was asked in, and nothing else
+ * (docs/design/place-history.md, #374).
+ *
+ * The room is never an argument. A model can be asked to read any chat ("what did they say in the other group?"), and
+ * the platform lets the bot read every chat it is in, so a room the tool were told would let one chat read another.
+ * The channel names the room instead: while a group turn runs, it registers that turn's room under the turn's session,
+ * and the tool, asking with its own session (`sessionIdOf`), gets that room or nothing. A place's turns run one at a
+ * time, so one session has one running turn and one room.
+ */
+import { truncateCodePointPrefix } from "./text.js";
+export function createRoomThreads(reader) {
+    const rooms = new Map();
+    return {
+        enter(session, room) {
+            rooms.set(session, room);
+            return () => {
+                if (rooms.get(session) === room)
+                    rooms.delete(session);
+            };
+        },
+        reader,
+        roomOf: (session) => rooms.get(session),
+    };
+}
+/**
+ * Per channel kind, per mounted channel (its `stateDir`): that channel's rooms. A remount of the channel replaces its
+ * entry, and two channel files of one kind keep one each. A session id names its storage, and a room is entered by the
+ * turn that runs in it, so a tool's session finds its own channel among every one of its kind in the process.
+ */
+const mounted = new Map();
+export function registerRoomThreads(kind, stateDir, rooms) {
+    const byChannel = mounted.get(kind) ?? new Map();
+    byChannel.set(stateDir, rooms);
+    mounted.set(kind, byChannel);
+}
+/** The threads the turn running in `sessionId` may read, from the `kind` channel it was asked through. */
+export function roomThreads(kind, sessionId) {
+    const serving = [...(mounted.get(kind)?.values() ?? [])];
+    if (serving.length === 0) {
+        throw new Error(`no ${kind} channel is serving in this process: threads are read only in a chat turn`);
+    }
+    const rooms = sessionId === undefined ? undefined : serving.find((each) => each.roomOf(sessionId) !== undefined);
+    const room = sessionId === undefined ? undefined : rooms?.roomOf(sessionId);
+    if (rooms === undefined || room === undefined) {
+        throw new Error(`this turn was not asked in a ${kind} group chat: threads are read only from the group a turn was asked in`);
+    }
+    return { list: () => rooms.reader.list(room), read: (threadId) => rooms.reader.read(room, threadId) };
+}
+/** Threads a list shows; a vague question reads every one listed, so the list is short. */
+const MAX_THREADS = 20;
+const PREVIEW_CHARS = 160;
+/**
+ * The list a tool returns: newest first by the time each line shows, each with the id that reads it, and what was
+ * left out said. A thread shown by when it started may have gone on since, and the list says so, since whether a
+ * problem was resolved is what a reader most often wants to know.
+ */
+export function threadList(threads, scanned) {
+    if (threads.length === 0)
+        return `No threads among ${scanned}.`;
+    const shown = [...threads].sort((a, b) => b.time.at - a.time.at).slice(0, MAX_THREADS);
+    const when = (ms) => `${new Date(ms).toISOString().slice(0, 16).replace("T", " ")} UTC`;
+    const lines = shown.map((thread) => {
+        const meta = [
+            thread.replies === undefined ? undefined : `${thread.replies} repl${thread.replies === 1 ? "y" : "ies"}`,
+            `${thread.time.is} ${when(thread.time.at)}`,
+        ]
+            .filter(Boolean)
+            .join(", ");
+        const text = truncateCodePointPrefix(thread.first.text.replace(/\s+/g, " ").trim(), PREVIEW_CHARS, "…");
+        return `- thread ${thread.id} (${meta}): ${thread.first.label}: ${text}`;
+    });
+    const more = threads.length - shown.length;
+    const startedOnly = shown.some((thread) => thread.time.is === "started");
+    return [
+        `Threads in this room, newest first by the time shown (among ${scanned}). Pass a thread's id to read it.`,
+        ...(startedOnly ? ["A thread shown by when it started may have later replies this list cannot see: read it."] : []),
+        ...lines,
+        ...(more > 0 ? [`(${more} more not listed)`] : []),
+    ].join("\n");
+}

package/dist/channels/kit/seen.js

@@ -1,6 +1,6 @@
 /** Best-effort bounded durable dedup ring, recorded only after the caller's pre-ACK side effect is durable. */
 import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "./state.js";
+import { loadStateFile, saveStateFile } from "../../state-file.js";
 export function createSeenRing(path, label, cap = 2000) {
     const raw = loadStateFile(path);
     const order = raw === undefined

package/dist/channels/kit/stop-command.d.ts

@@ -1,5 +1,8 @@
-import { type SessionControl } from "../../session.ts";
+import { type Agent } from "../../agent-api.ts";
 /** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
 export declare function isStopText(text: string): boolean;
-/** Dispatch `abort` for the session and map the outcome to the customer-facing line. */
-export declare function dispatchStop(control: SessionControl | undefined, session: string, label: string): Promise<string>;
+/**
+ * Dispatch `cancel` for the place's session (none: nothing was ever said there) and map its answer to the
+ * customer-facing line: the asker is told, and the failure goes to the log.
+ */
+export declare function dispatchStop(agent: Pick<Agent, "sessions">, sessionId: string | undefined, label: string): Promise<string>;

package/dist/channels/kit/stop-command.js

@@ -1,33 +1,35 @@
 /**
  * SHARED user-facing stop command: the chat channels (telegram, feishu/lark, slack) map an explicit "stop" ask onto
- * the session control plane's `abort`.
+ * the session's `cancel`.
  */
 import { log } from "../../log.js";
-import { NO_ACTIVE_RUN_CODE } from "../../session.js";
+import { AgentError } from "../../agent-api.js";
 /** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
 export function isStopText(text) {
     return /^(stop|cancel)[.!]?$/i.test(text.trim());
 }
 const STOPPED_NOTICE = "⏹ Stopped.";
 const NOTHING_RUNNING_NOTICE = "Nothing is running.";
-// A serve always builds the hub, so this is only reachable when an embedder mounted a service without one — never by
-// a configuration an author can change, which is why it no longer names a setting to turn on.
-const STOP_UNAVAILABLE_NOTICE = "⚠️ Stop isn't available on this deployment.";
-/** Dispatch `abort` for the session and map the outcome to the customer-facing line. */
-export async function dispatchStop(control, session, label) {
-    if (!control)
-        return STOP_UNAVAILABLE_NOTICE;
+const UNKNOWN_NOTICE = "⚠️ Could not tell whether it stopped — check again in a moment.";
+/**
+ * Dispatch `cancel` for the place's session (none: nothing was ever said there) and map its answer to the
+ * customer-facing line: the asker is told, and the failure goes to the log.
+ */
+export async function dispatchStop(agent, sessionId, label) {
+    if (sessionId === undefined)
+        return NOTHING_RUNNING_NOTICE;
     try {
-        const result = await control.sessions.get(session).abort();
-        if (result.ok)
-            return STOPPED_NOTICE;
-        if (result.error.code === NO_ACTIVE_RUN_CODE)
-            return NOTHING_RUNNING_NOTICE;
-        log.warn(`${label} stop rejected for ${session}: ${result.error.code} — ${result.error.message}`);
-        return `⚠️ Could not stop (${result.error.code}).`;
+        const { stopped } = await agent.sessions.cancel(sessionId);
+        return stopped.length > 0 ? STOPPED_NOTICE : NOTHING_RUNNING_NOTICE;
     }
     catch (error) {
-        log.warn(`${label} stop failed for ${session}: ${String(error)}`);
-        return "⚠️ Could not stop — see the server logs.";
+        if (error instanceof AgentError && error.code === "not_found")
+            return NOTHING_RUNNING_NOTICE;
+        const code = error instanceof AgentError ? error.code : undefined;
+        log.warn(`${label} stop failed for ${sessionId}: ${code ?? "error"} — ${error instanceof Error ? error.message : String(error)}`);
+        // The storage could not answer, or the call broke: the stop may have been recorded all the same (SPEC.md §4).
+        if (code === undefined || code === "unavailable")
+            return UNKNOWN_NOTICE;
+        return `⚠️ Could not stop (${code}).`;
     }
 }

package/dist/channels/kit/thread-fork.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where a NEW thread starts from (participant-model.md §5, architecture.md §2): a fork of the room's session at
+ * the message the thread's reply chain names, or at the room's present when nothing in it names one. A thread that
+ * already exists is left alone.
+ *
+ * A user's chat message names the message it became by its key: a channel sends with the platform's message id as
+ * the `idempotencyKey`, so `messages.get({ sessionId: room, idempotencyKey })` finds it. The thread forks at that
+ * message's answer; at its own entry when it has none (still running, or ended without one); at the room's present
+ * when it is still queued, or was never taken, since it is not in the history.
+ */
+import { type Agent } from "../../agent-api.ts";
+import type { ForkSource } from "../../channel.ts";
+/**
+ * Where a new thread's session forks from: its room's session at the message the thread's reply chain names, or at the
+ * room's present when nothing in it names one. What `sessionFor`'s `forkFrom` answers for a thread.
+ */
+export declare function threadForkSource(agent: Agent, room: string, chain: readonly string[]): Promise<ForkSource>;

package/dist/channels/kit/thread-fork.js

@@ -0,0 +1,43 @@
+/**
+ * Where a NEW thread starts from (participant-model.md §5, architecture.md §2): a fork of the room's session at
+ * the message the thread's reply chain names, or at the room's present when nothing in it names one. A thread that
+ * already exists is left alone.
+ *
+ * A user's chat message names the message it became by its key: a channel sends with the platform's message id as
+ * the `idempotencyKey`, so `messages.get({ sessionId: room, idempotencyKey })` finds it. The thread forks at that
+ * message's answer; at its own entry when it has none (still running, or ended without one); at the room's present
+ * when it is still queued, or was never taken, since it is not in the history.
+ */
+import { AgentError } from "../../agent-api.js";
+/** A reply chain is ids walked from the platform, each one a `messages.get`: bounded like ids, not payloads. */
+const MAX_CHAIN = 16;
+const MAX_ID_CHARS = 128;
+/** The entry a thread forks at for the message a chain names; undefined forks at the room's present. */
+function forkPoint(message) {
+    if (message.status === "queued")
+        return undefined;
+    return message.answer?.entryId ?? message.entryId;
+}
+/** Where the first message the chain names (nearest first) puts the fork; undefined, the room's present. */
+async function branchPoint(agent, room, chain) {
+    const usable = chain.filter((id) => id.length > 0 && id.length <= MAX_ID_CHARS).slice(0, MAX_CHAIN);
+    for (const idempotencyKey of usable) {
+        const message = await agent.messages.get({ sessionId: room, idempotencyKey }).catch((error) => {
+            // A platform message the agent was never sent (another bot's, or one before the agent joined) names nothing.
+            if (error instanceof AgentError && error.code === "not_found")
+                return undefined;
+            throw error;
+        });
+        if (message)
+            return forkPoint(message);
+    }
+    return undefined;
+}
+/**
+ * Where a new thread's session forks from: its room's session at the message the thread's reply chain names, or at the
+ * room's present when nothing in it names one. What `sessionFor`'s `forkFrom` answers for a thread.
+ */
+export async function threadForkSource(agent, room, chain) {
+    const at = await branchPoint(agent, room, chain);
+    return { sessionId: room, ...(at === undefined ? {} : { entryId: at }) };
+}

package/dist/channels/kit/thread-participants.js

@@ -4,7 +4,7 @@
  * that session's memory, so the two cannot be keyed independently.
  */
 import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "./state.js";
+import { loadStateFile, saveStateFile } from "../../state-file.js";
 const MAX_THREADS = 1000;
 /** Cap on remembered humans per thread. */
 const MAX_HUMANS = 2;

package/dist/channels/kit/transport.d.ts

@@ -24,3 +24,8 @@ export interface CallOptions {
 }
 /** A write the next one supersedes: never wait out a rate limit for it. */
 export declare const DROPPABLE_FRAME: CallOptions;
+/**
+ * A read that only adds context to a turn (a place's history, its speakers' names): the turn runs without it and says
+ * so, and the asker sees nothing until it ends, so it never waits out a rate limit either.
+ */
+export declare const CONTEXT_READ: CallOptions;

package/dist/channels/kit/transport.js

@@ -18,3 +18,8 @@
  */
 /** A write the next one supersedes: never wait out a rate limit for it. */
 export const DROPPABLE_FRAME = { retries: 0 };
+/**
+ * A read that only adds context to a turn (a place's history, its speakers' names): the turn runs without it and says
+ * so, and the asker sees nothing until it ends, so it never waits out a rate limit either.
+ */
+export const CONTEXT_READ = { retries: 0 };

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

@@ -2,17 +2,18 @@
 import * as Effect from "effect/Effect";
 import type * as Scope from "effect/Scope";
 import { type PortFailure } from "../../effect-port.ts";
-import type { ContextBuffer } from "./context-buffer.ts";
+import type { DiscussionSource } from "./place-history.ts";
 import { type TurnRecordBase, type TurnStore } from "./turn-store.ts";
 /**
  * A pending turn is the persisted intent minus its attempt count, plus live-only fields the channel adds (a notice's
  * message id).
  */
 export type PendingBase<S extends TurnRecordBase> = Omit<S, "attempts">;
-export interface TurnRunnerOptions<R extends PendingBase<S>, S extends TurnRecordBase, E> {
+export interface TurnRunnerOptions<R extends PendingBase<S>, S extends TurnRecordBase, E, P = string> {
     label: string;
     store: TurnStore<S>;
-    buffer: ContextBuffer<E>;
+    /** What a turn folds beyond its own ask: the context buffer, or the place's history read from the platform. */
+    discussion: DiscussionSource<E, P>;
     /** Delivery dedup by platform id, recorded post-persist (Slack, Feishu). */
     seen?: {
         add(id: string): void;
@@ -21,8 +22,8 @@ export interface TurnRunnerOptions<R extends PendingBase<S>, S extends TurnRecor
     toStored(rec: R): S;
     /** A recovered intent as a pending turn — live-only fields start absent. */
     fromStored(stored: S): R;
-    /** The context-buffer bucket this turn folds. */
-    bufferKey(rec: R): string;
+    /** The place this turn folds the discussion of (a buffer bucket, or a place to read); undefined folds nothing. */
+    discussionKey(rec: R): P | undefined;
     /** The place, for the lifecycle log line (`chat=… thread=…`). */
     where(rec: R): string;
     /** Queue feedback when a turn is scheduled BEHIND an active one. */
@@ -50,7 +51,7 @@ export interface TurnRunnerOptions<R extends PendingBase<S>, S extends TurnRecor
      * preview — the one the answer was written for died with its process.
      *
      * A notice THIS process put up is a different thing and must still be settled: a record recovered behind another
-     * turn in the same session goes through `onQueuedBehind` like any other, so it can hold a fresh "queued" message
+     * turn in the same conversation goes through `onQueuedBehind` like any other, so it can hold a fresh "queued" message
      * or status that only this call can take over or clear.
      */
     deliverAnswer(rec: R, answer: string): Effect.Effect<void, PortFailure, Scope.Scope>;
@@ -66,8 +67,8 @@ export interface TurnRunner<R, S> {
     /** Resolve once no turn is in flight — the test/observability seam. */
     idle(): Promise<void>;
 }
-export declare function runQueuedTurn<R extends PendingBase<S>, S extends TurnRecordBase, E>(options: TurnRunnerOptions<R, S, E>, rec: R): Effect.Effect<void, PortFailure>;
+export declare function runQueuedTurn<R extends PendingBase<S>, S extends TurnRecordBase, E, P = string>(options: TurnRunnerOptions<R, S, E, P>, rec: R): Effect.Effect<void, PortFailure>;
 export declare function createTurnRunner<R extends PendingBase<S> & {
     id: string;
-    session: string;
-}, S extends TurnRecordBase, E>(options: TurnRunnerOptions<R, S, E>): TurnRunner<R, S>;
+    conversation: string;
+}, S extends TurnRecordBase, E, P = string>(options: TurnRunnerOptions<R, S, E, P>): TurnRunner<R, S>;

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

@@ -3,11 +3,11 @@ import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import { log } from "../../log.js";
 import { portError, portJoin } from "../../effect-port.js";
-import { createTurnQueue } from "./turn-queue.js";
+import { createTurnQueue } from "../turn-queue.js";
 import { commitAnsweredTurn } from "./turn-store.js";
 export function runQueuedTurn(options, rec) {
     return Effect.gen(function* () {
-        const { label, store, buffer, beforeRun } = options;
+        const { label, store, discussion: source, beforeRun } = options;
         if (beforeRun && !(yield* portJoin(() => beforeRun(rec))))
             return;
         const decision = store.startAttempt(rec.id);
@@ -24,10 +24,10 @@ export function runQueuedTurn(options, rec) {
                 // The store has already said, at error level, that this turn will not be run again. Silence after that
                 // reads as "nothing happened"; this line is what distinguishes it from a delivered answer.
                 onSuccess: () => Effect.sync(() => log.info(`${label} turn ${rec.id} hit the execution ceiling, but the answer it had already recorded was ` +
-                    `delivered (session=${rec.session})`)),
+                    `delivered (conversation=${rec.conversation})`)),
                 onFailure: (error) => Effect.sync(() => {
                     log.error(`${label} turn ${rec.id} hit the execution ceiling and its recorded answer could not be delivered ` +
-                        `either (session=${rec.session}) — the answer is gone: ${String(error.cause)}`);
+                        `either (conversation=${rec.conversation}) — the answer is gone: ${String(error.cause)}`);
                     // The record is off disk, so nothing will retry this. The asker is owed an ending — without one, a
                     // queue notice this turn put up stays in the chat forever reading "Queued".
                     options.notifyDropped(rec);
@@ -45,30 +45,28 @@ export function runQueuedTurn(options, rec) {
         let answered = recovered !== undefined;
         // One stable prefix, so every `turn done:`/`turn failed:` has a `turn start:` to grep back to; what kind of work
         // it is rides along as a field.
-        log.info(`${label} turn start: turn=${rec.id} session=${rec.session} ${options.where(rec)}` +
+        log.info(`${label} turn start: turn=${rec.id} conversation=${rec.conversation} ${options.where(rec)}` +
             `${recovered === undefined ? "" : " mode=re-delivery (answer recovered from a prior run)"}`);
         const work = recovered !== undefined
             ? Effect.suspend(() => options.deliverAnswer(rec, recovered))
             : Effect.suspend(() => {
-                const bufferKey = options.bufferKey(rec);
-                const discussion = buffer.peek(bufferKey);
-                return options.execute(rec, discussion, (answer) => {
+                const key = options.discussionKey(rec);
+                // `peek` never rejects (DiscussionSource): a source that cannot read says so in the text.
+                return Effect.promise(async () => key === undefined ? { text: "", consumed: [] } : source.peek(key)).pipe(Effect.flatMap((discussion) => options.execute(rec, discussion, (answer) => {
                     // Only a recorded answer is recoverable — an untracked run has no record to keep it in.
-                    answered = commitAnsweredTurn(store, buffer, {
-                        id: rec.id,
-                        bufferKey,
-                        consumed: discussion.consumed,
-                        answer,
-                    });
-                });
+                    answered =
+                        key === undefined
+                            ? store.answered(rec.id, answer)
+                            : commitAnsweredTurn(store, source, { id: rec.id, key, consumed: discussion.consumed, answer });
+                })));
             });
         const delivered = yield* Effect.scoped(work).pipe(Effect.matchEffect({
             onSuccess: () => Effect.sync(() => {
-                log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
+                log.info(`${label} turn done: turn=${rec.id} conversation=${rec.conversation} (${Date.now() - startedAt}ms)`);
                 return true;
             }),
             onFailure: (error) => Effect.sync(() => {
-                log.error(`${label} turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error.cause)}`);
+                log.error(`${label} turn failed: turn=${rec.id} conversation=${rec.conversation} (${Date.now() - startedAt}ms): ${String(error.cause)}`);
                 return false;
             }),
         }));
@@ -79,7 +77,7 @@ export function runQueuedTurn(options, rec) {
             store.remove(rec.id);
             return;
         }
-        log.warn(`${label} turn ${rec.id} produced an answer that was not delivered (session=${rec.session}) — ` +
+        log.warn(`${label} turn ${rec.id} produced an answer that was not delivered (conversation=${rec.conversation}) — ` +
             `keeping it to re-deliver on the next start`);
     });
 }
@@ -92,7 +90,7 @@ export function createTurnRunner(options) {
             ((rec) => {
                 const notice = onQueuedBehind(rec);
                 // Observe rejection at acceptance, even if dequeue is minutes away.
-                const done = Effect.runFork(portJoin(() => notice.done).pipe(Effect.catchCause((cause) => Effect.sync(() => log.warn(`${label} queue notice failed: turn=${rec.id} session=${rec.session}: ${String(portError(cause))}`)))));
+                const done = Effect.runFork(portJoin(() => notice.done).pipe(Effect.catchCause((cause) => Effect.sync(() => log.warn(`${label} queue notice failed: turn=${rec.id} conversation=${rec.conversation}: ${String(portError(cause))}`)))));
                 notices.set(rec.id, { done, cancel: notice.cancel });
             }),
         run: (rec) => Effect.gen(function* () {

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

@@ -1,8 +1,9 @@
-import type { ContextBuffer } from "./context-buffer.ts";
+import type { DiscussionSource } from "./place-history.ts";
 /** What every persisted turn record carries regardless of channel. */
 export interface TurnRecordBase {
     id: string;
-    session: string;
+    /** The conversation the turn belongs to: what its queue and its session are kept by. */
+    conversation: string;
     attempts: number;
     /**
      * The completed reply, recorded BEFORE it is delivered. Its presence is the difference between the two things a
@@ -49,9 +50,9 @@ export interface TurnStoreOptions<T extends TurnRecordBase> {
  *
  * Returns whether the answer became recoverable, so a caller does not claim a recovery that has nothing on disk.
  */
-export declare function commitAnsweredTurn<T extends TurnRecordBase, E>(store: TurnStore<T>, buffer: ContextBuffer<E>, turn: {
+export declare function commitAnsweredTurn<T extends TurnRecordBase, E, P>(store: TurnStore<T>, discussion: Pick<DiscussionSource<E, P>, "commit">, turn: {
     id: string;
-    bufferKey: string;
+    key: P;
     consumed: E[];
     answer: string;
 }): boolean;

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

@@ -7,7 +7,7 @@
  * exactly-once story needs the different backend above.
  */
 import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "./state.js";
+import { loadStateFile, saveStateFile } from "../../state-file.js";
 /** How many times a turn may START without finishing before it is dropped rather than run again. */
 const MAX_TURN_ATTEMPTS = 3;
 /**
@@ -17,9 +17,9 @@ const MAX_TURN_ATTEMPTS = 3;
  *
  * Returns whether the answer became recoverable, so a caller does not claim a recovery that has nothing on disk.
  */
-export function commitAnsweredTurn(store, buffer, turn) {
+export function commitAnsweredTurn(store, discussion, turn) {
     const recorded = store.answered(turn.id, turn.answer);
-    buffer.commit(turn.bufferKey, turn.consumed);
+    discussion.commit(turn.key, turn.consumed);
     return recorded;
 }
 export function createTurnStore(path, opts) {
@@ -98,7 +98,7 @@ export function createTurnStore(path, opts) {
                 // State the fact, not a cause the counter can't prove: a turn killed mid-run every time bumps this whether IT
                 // poisoned the process or a deploy/OOM took it down each time.
                 log.error(`${label} dropping turn ${id} after starting ${rec.attempts} time(s) without finishing ` +
-                    `(session=${rec.session}) — it may be crashing the process, or was killed mid-run each time; it will not ` +
+                    `(conversation=${rec.conversation}) — it may be crashing the process, or was killed mid-run each time; it will not ` +
                     `be run again`);
                 turns.delete(id);
                 persistBestEffort("drop");
@@ -113,7 +113,7 @@ export function createTurnStore(path, opts) {
                 // RE-RUNS this turn.
                 turns.set(id, rec);
                 log.error(`${label} cannot persist turn ${id}'s attempt count — deferring it to the next start rather ` +
-                    `than run it untracked (session=${rec.session}): ${String(e)}`);
+                    `than run it untracked (conversation=${rec.conversation}): ${String(e)}`);
                 return "defer";
             }
             return "run";

package/dist/channels/lark/lark.d.ts

@@ -1,6 +1,7 @@
 /** Lark-international compatibility adapter. */
 import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
 import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, type FeishuWebSocketChannelOptions, defaultFeishuRoute } from "../feishu/feishu.ts";
+import { type FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
 export type LarkChannelOptions = FeishuChannelOptions;
 export type LarkWebSocketChannelOptions = FeishuWebSocketChannelOptions;
 export type LarkFailure = FeishuFailure;
@@ -10,4 +11,6 @@ export type LarkRoute = FeishuRoute;
 export declare const defaultLarkRoute: typeof defaultFeishuRoute;
 export declare function larkEnvelope(event: LarkMessageEvent): string;
 export declare function larkChannel(opts: LarkChannelOptions): ChannelModule;
+/** How this process receives the Lark channel: `LARK_INGRESS`, else WebSocket under `dev` and webhook otherwise. */
+export declare function larkIngress(): FeishuSubscriptionMode;
 export declare function larkWebSocketChannel(opts: LarkWebSocketChannelOptions): LongConnectionChannelModule;

package/dist/channels/lark/lark.js

@@ -1,6 +1,7 @@
 import { LARK_COMPAT_CLOUD } from "../feishu/cloud.js";
 import { buildFeishuChannel, buildFeishuWebSocketChannel, defaultFeishuRoute, } from "../feishu/feishu.js";
 import { cloudEnvelope } from "../feishu/parse.js";
+import { feishuIngressFor } from "../feishu/setup-mode.js";
 export const defaultLarkRoute = defaultFeishuRoute;
 export function larkEnvelope(event) {
     return cloudEnvelope(event, "lark");
@@ -8,6 +9,10 @@ export function larkEnvelope(event) {
 export function larkChannel(opts) {
     return buildFeishuChannel(LARK_COMPAT_CLOUD, opts, larkChannel.name);
 }
+/** How this process receives the Lark channel: `LARK_INGRESS`, else WebSocket under `dev` and webhook otherwise. */
+export function larkIngress() {
+    return feishuIngressFor("lark");
+}
 export function larkWebSocketChannel(opts) {
     return buildFeishuWebSocketChannel(LARK_COMPAT_CLOUD, opts, larkWebSocketChannel.name);
 }