@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/channels/kit/event-stream.js

@@ -12,7 +12,8 @@ export function eventStream(open, label) {
             const close = iterator.return?.bind(iterator);
             if (!close || exhausted)
                 return Effect.void;
-            return Effect.promise(close).pipe(Effect.onError((cause) => Effect.sync(() => log.warn(`${label} source cleanup failed: ${String(Cause.squash(cause))}`))));
+            // Logged, not raised: a failing release would make the consumer's typed failure a defect.
+            return Effect.promise(close).pipe(Effect.catchCause((cause) => Effect.sync(() => log.warn(`${label} source cleanup failed: ${String(Cause.squash(cause))}`))));
         });
         return Effect.gen(function* () {
             const result = yield* Effect.tryPromise({

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

@@ -1,58 +1,57 @@
 import * as Stream from "effect/Stream";
-import { type Agent, type AgentEvent, type Prompt, type Scope } from "../../agent.ts";
+import { type Agent, type AgentErrorData, type MessageStreamEvent, type SendRequest } from "../../agent-api.ts";
 import { type PortFailure } from "../../effect-port.ts";
 /**
- * One turn, end to end: resolve the platform inputs, then stream `agent.invoke` with the shared
- * busy-wait. All three chat channels wrote this out, and the copies had already disagreed about the
- * one thing that is actually a per-platform judgement (whether a load failure is worth a redelivery)
- * while agreeing on everything that is not.
+ * What a turn reads, in order: the message as it was recorded, or why there is none (`rejected`), then the events of
+ * its session that belong to it through its `done` (SPEC.md §6.2).
+ */
+export type TurnEvent = {
+    type: "rejected";
+    error: AgentErrorData;
+} | MessageStreamEvent;
+/** An image a channel read from its platform, as a message carries it. */
+export interface ImageAttachment {
+    mimeType: string;
+    /** base64 */
+    data: string;
+}
+type MessageContent = Exclude<SendRequest["content"], string>;
+/** A turn's text and images as the content of one message. */
+export declare function promptContent(text: string, images: readonly ImageAttachment[] | undefined): MessageContent;
+/**
+ * One turn, end to end: the platform inputs prepared, the session the turn's conversation talks in (created and
+ * recorded before anything is sent, conversation-sessions.ts), then the message sent and its answer read as it is written
+ * (`stream`).
  *
- * A resolution failure becomes a `failed` EVENT. It must never throw out of the stream: the SPEC
- * forbids it (MUST 2), and the turn's own settlement path is what tells the user — an exception here
- * would take the reply with it.
+ * The message queues behind whatever runs in the session (a wake-up, a schedule): the channel's own turns never
+ * collide, its queue serializes them per conversation. Its key is the turn's, so a turn run again after a restart is the
+ * message it already sent: one that ended is read back, answer included.
+ *
+ * A failure to prepare is the turn's `rejected` event: nothing was sent. It must never throw out of the stream, since
+ * the turn's own settlement path is what tells the user; an exception here would take the reply with it.
  */
 export declare function turnStream<R>(opts: {
     agent: Agent;
     label: string;
-    /** Resolve this turn's platform inputs (download attachments, walk a reply chain). */
+    /**
+     * The session the turn's conversation talks in: the one it has, or one created and recorded before anything is
+     * sent. It gets the prepared inputs, since where a new thread forks from is what its reply chain names.
+     */
+    session: (resolved: R) => Promise<string>;
+    /** While the turn runs, what its session reaches by its id (a thread-reading tool's room); released when it ends. */
+    enter?: (sessionId: string) => () => void;
+    /** Prepare this turn's inputs (download attachments, walk a reply chain). */
     resolve: () => Promise<R>;
-    /** What the resolved inputs make of the turn: where it runs, and what it asks. */
+    /** What the prepared inputs make of the turn: what it asks, and the key it is known by. */
     turn: (resolved: R) => {
-        scope: Scope;
-        prompt: Prompt;
+        content: MessageContent;
+        idempotencyKey: string;
     };
-    /** Whether a failed resolution is worth a platform redelivery. Stated per channel because it IS a
+    /** Whether a failed preparation is worth a platform redelivery. Stated per channel because it IS a
      *  platform question — Slack reads its API error's status, and a transport that cannot tell says
      *  yes, since a retried download is cheap next to an unanswered ask. */
     retryableLoadFailure: (cause: unknown) => boolean;
-    busyRetry?: BusyRetry;
-}): Stream.Stream<AgentEvent, PortFailure>;
-/** 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
- *  always an outside holder — wait for it like a queued turn, instead of erroring at the user. */
-export interface BusyRetry {
-    delayMs: number;
-    maxWaitMs: number;
-}
-export declare const DEFAULT_BUSY_RETRY: BusyRetry;
-/**
- * Stream one Agent turn with the shared busy-wait. The durable-commit point is NOT here: an answer becomes durable
- * where its text is known and about to be written to the chat (the renderer's `onAnswered`), because "the model
- * finished" and "the user has it" are different events. Source pulls remain demand-driven, including while final
- * platform delivery runs.
- *
- * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn holds this session's
- * lease and OUR turn never started — replay-safe. Retry (bounded) instead of yielding it: the user
- * sees the channel's "Thinking…" placeholder while waiting (the mirror of the scheduler deferring a
- * wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a FIRST-event
- * 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 busyRetryStream(agent: Agent, scope: Scope, prompt: Prompt, { label, busyRetry }: {
-    label: string;
-    busyRetry?: BusyRetry;
-}): Stream.Stream<AgentEvent, PortFailure>;
+}): Stream.Stream<TurnEvent, PortFailure>;
 /**
  * Load the turn's BACKGROUND refs — what was folded in from earlier un-summoned discussion, not the
  * ask itself. Per-ref degradation is the whole meaning of that tier: one expired file costs a warn
@@ -104,3 +103,4 @@ export declare function backgroundImagesManifest(primaryCount: number, refs: rea
  *  cap-skipped) — without it, the model holds fold references it silently cannot open and may
  *  pretend it read them. Neutral wording (platforms differ on WHY: expired file_ids, deleted files). */
 export declare function missingAttachmentsNote(missing: number): string;
+export {};

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

@@ -1,10 +1,9 @@
 /**
  * Shared pieces of the channels' invoke-turn modules (telegram/feishu/slack `invoke-turn.ts`) — the
- * halves that are channel-independent, so a retry-policy or prompt-wording change lands ONCE:
+ * halves that are channel-independent, so a policy or prompt-wording change lands ONCE:
  *
- *   - {@link turnStream}: resolve inputs → ask the agent, with a load failure arriving as a `failed`
- *     EVENT rather than a thrown iteration (SPEC MUST 2);
- *   - {@link busyRetryStream}: the busy-retry loop around `agent.invoke`;
+ *   - {@link turnStream}: prepare the turn's inputs → ask the agent, with a preparation failure arriving as the
+ *     invoke's `rejected` EVENT rather than a thrown iteration;
  *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
  *     {@link missingAttachmentsNote}, {@link attributedFileName}.
  *
@@ -16,83 +15,75 @@
  * message-scoped Feishu keys, Slack file objects) are real differences. The two TIERS' failure
  * policies are not: see {@link loadBackground}.
  */
-import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
 import * as Stream from "effect/Stream";
-import { SESSION_BUSY_CODE } from "../../agent.js";
-import { eventStream } from "./event-stream.js";
-import { portJoin } from "../../effect-port.js";
+import { AgentError, } from "../../agent-api.js";
 import { log } from "../../log.js";
+import { eventStream } from "./event-stream.js";
+import { portError, portJoin } from "../../effect-port.js";
+/** A turn's text and images as the content of one message. */
+export function promptContent(text, images) {
+    return [{ type: "text", text }, ...(images ?? []).map((image) => ({ type: "image", ...image }))];
+}
 /**
- * One turn, end to end: resolve the platform inputs, then stream `agent.invoke` with the shared
- * busy-wait. All three chat channels wrote this out, and the copies had already disagreed about the
- * one thing that is actually a per-platform judgement (whether a load failure is worth a redelivery)
- * while agreeing on everything that is not.
+ * One turn, end to end: the platform inputs prepared, the session the turn's conversation talks in (created and
+ * recorded before anything is sent, conversation-sessions.ts), then the message sent and its answer read as it is written
+ * (`stream`).
  *
- * A resolution failure becomes a `failed` EVENT. It must never throw out of the stream: the SPEC
- * forbids it (MUST 2), and the turn's own settlement path is what tells the user — an exception here
- * would take the reply with it.
+ * The message queues behind whatever runs in the session (a wake-up, a schedule): the channel's own turns never
+ * collide, its queue serializes them per conversation. Its key is the turn's, so a turn run again after a restart is the
+ * message it already sent: one that ended is read back, answer included.
+ *
+ * A failure to prepare is the turn's `rejected` event: nothing was sent. It must never throw out of the stream, since
+ * the turn's own settlement path is what tells the user; an exception here would take the reply with it.
  */
 export function turnStream(opts) {
-    return Stream.unwrap(portJoin(opts.resolve).pipe(Effect.map((resolved) => {
-        const { scope, prompt } = opts.turn(resolved);
-        return busyRetryStream(opts.agent, scope, prompt, {
-            label: opts.label,
-            ...(opts.busyRetry ? { busyRetry: opts.busyRetry } : {}),
-        });
-    }), Effect.catchTag("PortFailure", ({ cause }) => Effect.succeed(Stream.succeed({
-        type: "failed",
-        details: `could not load attachment: ${String(cause)}`,
-        retryable: opts.retryableLoadFailure(cause),
-    })))));
+    const rejected = (error) => Stream.succeed({ type: "rejected", error });
+    return Stream.unwrap(Effect.gen(function* () {
+        const prepared = yield* Effect.result(portJoin(opts.resolve));
+        if (Result.isFailure(prepared)) {
+            const { cause } = prepared.failure;
+            return rejected({
+                code: "unavailable",
+                message: `could not prepare the turn: ${String(cause)}`,
+                retryable: opts.retryableLoadFailure(cause),
+            });
+        }
+        const resolved = prepared.success;
+        // The Agent's own question from here on, so its own answer says whether a retry is worth it.
+        const session = yield* Effect.result(portJoin(() => opts.session(resolved)));
+        if (Result.isFailure(session))
+            return rejected(agentFailure("its session", session.failure.cause));
+        const sessionId = session.success;
+        const enter = opts.enter;
+        if (enter !== undefined)
+            yield* Effect.acquireRelease(Effect.sync(() => enter(sessionId)), (leave) => Effect.sync(leave));
+        const { content, idempotencyKey } = opts.turn(resolved);
+        const request = { sessionId, content, idempotencyKey, whenBusy: "queue" };
+        // A send the agent refused rejects the stream's first read: the turn's `rejected`, not a failure of its stream.
+        return eventStream(() => opts.agent.messages.stream(request), `${opts.label} (session=${sessionId})`).pipe(Stream.scoped, Stream.catchCause((cause) => {
+            const error = portError(cause);
+            return error instanceof AgentError ? rejected(agentFailure("its message", error)) : Stream.failCause(cause);
+        }));
+    }));
 }
-// Each retry is a lease-check-level reject (tryAcquire runs before the session is bound) — waiting is nearly
-// free, and the loop exits within one delay of the holder finishing. So the cap is sized to outlast a
-// real tool-using wake turn (minutes), not to be short: 10 min. CEILING: a holder that runs longer than
-// this still surfaces the busy error to the user — the bound exists so a stuck lease can't hang a chat
-// turn forever.
-export const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
 /**
- * Stream one Agent turn with the shared busy-wait. The durable-commit point is NOT here: an answer becomes durable
- * where its text is known and about to be written to the chat (the renderer's `onAnswered`), because "the model
- * finished" and "the user has it" are different events. Source pulls remain demand-driven, including while final
- * platform delivery runs.
- *
- * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn holds this session's
- * lease and OUR turn never started — replay-safe. Retry (bounded) instead of yielding it: the user
- * sees the channel's "Thinking…" placeholder while waiting (the mirror of the scheduler deferring a
- * wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a FIRST-event
- * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
- * is ever re-run.
+ * A step of the Agent's that failed: its refusal as it gave it (an `AgentError`, with its own `retryable`), or a
+ * failure nothing was sent past, so worth a retry. A send that may have been recorded (`unconfirmed`) is worth one too:
+ * the turn's send carries its key, so sending it again finds the message rather than recording a second.
  */
-export function busyRetryStream(agent, scope, prompt, { label, busyRetry = DEFAULT_BUSY_RETRY }) {
-    return Stream.unwrap(Effect.map(Clock.currentTimeMillis, (started) => {
-        const deadline = started + busyRetry.maxWaitMs;
-        const attempt = () => Stream.suspend(() => {
-            let retryBusy = false;
-            let first = true;
-            return eventStream(() => agent.invoke(scope, prompt), `${label} (session=${scope.session})`).pipe(Stream.takeWhileEffect((event) => Effect.gen(function* () {
-                if (first &&
-                    event.type === "failed" &&
-                    event.code === SESSION_BUSY_CODE &&
-                    (yield* Clock.currentTimeMillis) + busyRetry.delayMs < deadline) {
-                    retryBusy = true;
-                    return false;
-                }
-                first = false;
-                return true;
-            })), Stream.scoped, 
-            // concat closes the attempt's scope (and its iterator) before the wait or next invoke.
-            Stream.concat(Stream.suspend(() => retryBusy
-                ? Stream.unwrap(Effect.gen(function* () {
-                    log.info(`${label} session ${scope.session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
-                    yield* Effect.sleep(busyRetry.delayMs);
-                    return attempt();
-                }))
-                : Stream.empty)));
-        });
-        return attempt();
-    }));
+function agentFailure(what, cause) {
+    if (cause instanceof AgentError) {
+        const { code, message, retryable, details } = cause;
+        return {
+            code,
+            message: `could not start ${what}: ${message}`,
+            retryable: retryable || code === "unconfirmed",
+            ...(details === undefined ? {} : { details }),
+        };
+    }
+    return { code: "unavailable", message: `could not start ${what}: ${String(cause)}`, retryable: true };
 }
 /**
  * Load the turn's BACKGROUND refs — what was folded in from earlier un-summoned discussion, not the

package/dist/channels/kit/place-history.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Where a turn's discussion comes from. `peek` snapshots what this turn folds; `commit` runs when the turn's answer
+ * is recorded, so a failure or crash before then leaves the discussion to be folded again. `P` names what is read: a
+ * buffer bucket's key, or a place plus where this turn's read ends.
+ */
+export interface DiscussionSource<E, P = string> {
+    /** Never rejects: a source that cannot read says so in `text`, and the turn proceeds without it. */
+    peek(place: P): {
+        text: string;
+        consumed: E[];
+    } | Promise<{
+        text: string;
+        consumed: E[];
+    }>;
+    commit(place: P, consumed: E[]): void;
+}
+/** One message of a place, as the fold renders it. */
+export interface PlaceMessage {
+    id: string;
+    /** Milliseconds since the epoch. */
+    at: number;
+    /** "self": this agent, outside its own turn answers (a schedule's digest, a post from another chat). */
+    from: {
+        kind: "human" | "self" | "bot";
+        label: string;
+    };
+    text: string;
+    replyTo?: string;
+    images: {
+        key: string;
+    }[];
+    files: {
+        key: string;
+        name?: string;
+    }[];
+}
+/**
+ * What a turn reads: its place, up to and including its own ask. The bound is what keeps every later message out —
+ * an ask queued behind this one is its own turn, and folding it here would answer it twice — and it needs no record
+ * of which messages were asks, so a lost or cold state cannot break it. `C` is the platform's position: the newest
+ * message a read reached.
+ */
+export interface PlaceRead<C> {
+    key: string;
+    until: C;
+}
+/** One turn's read: where it reached, what it folded (whose attachments ride along), and which outputs it passed. */
+export interface PlaceDiscussion<C> {
+    /** Absent when the read failed: the cursor then stays, and the next turn reads the same messages again. */
+    cursor?: C;
+    folded: PlaceMessage[];
+    outputsPassed: string[];
+}
+/** What a platform read of one place returns. */
+export interface PlaceListing<C> {
+    /** Every message id the read covered, kept or dropped: what tells which recorded outputs it passed. */
+    covered: string[];
+    /** What to fold, oldest first: system messages and what `drop` named already left out. */
+    messages: PlaceMessage[];
+    /** The newest message listed. A bounded read's cursor is its bound instead, the ask it read up to. */
+    newest?: C;
+    /** Older messages exist that the read never reached. */
+    earlier: boolean;
+}
+export interface PlaceHistory<C> extends DiscussionSource<PlaceDiscussion<C>, PlaceRead<C>> {
+    /** A message a turn posted into this place: in the session already, so the place's next read leaves it out. */
+    recordOutput(key: string, messageId: string): void;
+    /**
+     * A thread's room, read-only, for the thread's first turn (participant-model §8): the room's own next answered turn
+     * still reads it, so each place takes the discussion into its own memory.
+     */
+    room(key: string): Promise<{
+        text: string;
+        folded: PlaceMessage[];
+    }>;
+    /**
+     * A place as it reads now, for a tool: its newest messages, with no cursor and nothing left out (another session's
+     * asks and answers are what that place said). Rejects when the read fails: a tool's failure is the model's to see.
+     */
+    snapshot(key: string): Promise<{
+        text: string;
+        folded: PlaceMessage[];
+    }>;
+}
+/**
+ * A place's history read from its platform (docs/design/place-history.md): what was said in a chat or a thread since
+ * this agent last answered there, up to the turn's own ask. The platform owns the read; this owns what a place
+ * remembers between turns — its cursor, and the messages turns posted there — and what a turn leaves out of its read:
+ * the messages a turn posted into the place (`recordOutput`: answers, queue notices, stop feedback), kept beside the
+ * cursor until a read has passed them, so a busy deployment cannot push a quiet place's last answer out of a shared
+ * ring; and, as prompt shaping only, what the channel took as input (`isTurnInput`). What the agent sent itself from a
+ * send tool stays — that is what a later "what did point 3 mean?" is about.
+ */
+export declare function createPlaceHistory<C>(deps: {
+    label: string;
+    /** Where each place's cursor and outputs persist. */
+    path: string;
+    isCursor(value: unknown): value is C;
+    /** Negative, zero or positive as `a` is before, at or after `b`. */
+    compare(a: C, b: C): number;
+    isTurnInput(key: string, messageId: string): boolean;
+    /** The place's messages after `cursor` (or its newest few, with none) and before `until`, oldest first. */
+    read(key: string, from: {
+        cursor?: C;
+        drop(messageId: string): boolean;
+    }, until?: C): Promise<PlaceListing<C>>;
+}): PlaceHistory<C>;

package/dist/channels/kit/place-history.js

@@ -0,0 +1,182 @@
+/**
+ * What a turn learns about its place (a chat, or a thread in one) beyond its own ask — and the fold that renders it,
+ * shared by every channel whose platform can be read (docs/design/place-history.md).
+ *
+ * Two sources fill a turn's discussion: the context buffer (`context-buffer.ts`), for a platform with no history read,
+ * and the place's own history, read from the platform when the turn runs ({@link createPlaceHistory}). The turn
+ * runner sees only {@link DiscussionSource}.
+ */
+import { log } from "../../log.js";
+import { BUFFER_LINE_MAX_CHARS, BUFFER_MAX_CHARS } from "./context-buffer.js";
+import { loadStateFile, saveStateFile } from "../../state-file.js";
+import { truncateCodePointPrefix } from "./text.js";
+/**
+ * Per-message bound for the agent's own post. A digest runs to thousands of characters; the line bound would keep its
+ * title only. It stays inside the budget, so later discussion still pushes it out.
+ */
+const PLACE_OWN_MAX_CHARS = 2000;
+function line(message) {
+    const own = message.from.kind === "self";
+    const body = truncateCodePointPrefix(message.text.replace(/\s+/g, " ").trim(), own ? PLACE_OWN_MAX_CHARS : BUFFER_LINE_MAX_CHARS, own ? " … (truncated)" : "…");
+    const meta = [`msg ${message.id}`, message.replyTo ? `reply to msg ${message.replyTo}` : undefined]
+        .filter(Boolean)
+        .join(", ");
+    return `${message.from.label} (${meta}): ${body}`;
+}
+/**
+ * Render `messages` (oldest first) newest-first into the buffer's budget (the same bound, whichever the source). What the budget leaves out, and what the read never
+ * reached (`earlier`), is said in a line, never dropped silently.
+ */
+function foldPlace(messages, earlier) {
+    const lines = [];
+    const folded = [];
+    let used = 0;
+    let cut = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        const rendered = line(message);
+        if (cut > 0 || used + rendered.length + 1 > BUFFER_MAX_CHARS) {
+            cut++;
+            continue;
+        }
+        used += rendered.length + 1;
+        lines.unshift(rendered);
+        folded.unshift(message);
+    }
+    if (cut > 0 || earlier) {
+        lines.unshift(cut > 0
+            ? `(${cut}${earlier ? "+" : ""} earlier message${cut === 1 && !earlier ? "" : "s"} here not shown)`
+            : "(earlier messages here not shown)");
+    }
+    return { text: folded.length > 0 || cut > 0 ? lines.join("\n") : "", folded };
+}
+/**
+ * Places kept, least recently used dropped. A dropped place costs one re-read of its newest messages, its earlier
+ * answers among them.
+ */
+const MAX_PLACES = 2000;
+/**
+ * Of those, places no read has reached yet (only outputs, no cursor), least recently used dropped. Slack records an
+ * answer to a top-level ask in the thread it opens, and most such threads are never asked in again: their own bound
+ * keeps them from pushing out a quiet place's cursor, while a thread answered a moment ago is still among the newest
+ * when its follow-up comes.
+ */
+const MAX_UNREAD_PLACES = 500;
+/**
+ * A place's outputs not yet passed by a read. One turn posts a handful (an answer, its chunks, a queue notice); the
+ * bound only stops a place whose reads keep failing from growing without end.
+ */
+const MAX_OUTPUTS = 200;
+/**
+ * A place's history read from its platform (docs/design/place-history.md): what was said in a chat or a thread since
+ * this agent last answered there, up to the turn's own ask. The platform owns the read; this owns what a place
+ * remembers between turns — its cursor, and the messages turns posted there — and what a turn leaves out of its read:
+ * the messages a turn posted into the place (`recordOutput`: answers, queue notices, stop feedback), kept beside the
+ * cursor until a read has passed them, so a busy deployment cannot push a quiet place's last answer out of a shared
+ * ring; and, as prompt shaping only, what the channel took as input (`isTurnInput`). What the agent sent itself from a
+ * send tool stays — that is what a later "what did point 3 mean?" is about.
+ */
+export function createPlaceHistory(deps) {
+    const { label, path } = deps;
+    const places = loadPlaces(path, label, deps.isCursor);
+    /**
+     * Mark `key` most recently used (the map's order is the eviction order), apply both bounds, and persist every place.
+     */
+    const save = (key, state, lost) => {
+        places.delete(key);
+        places.set(key, state);
+        const unread = [...places.keys()].filter((other) => places.get(other)?.cursor === undefined);
+        for (const victim of unread.slice(0, Math.max(0, unread.length - MAX_UNREAD_PLACES)))
+            places.delete(victim);
+        for (const victim of [...places.keys()].slice(0, Math.max(0, places.size - MAX_PLACES)))
+            places.delete(victim);
+        try {
+            saveStateFile(path, Object.fromEntries(places));
+        }
+        catch (error) {
+            // Both callers are past a platform write (a sent message, a recorded answer): throwing would report a send that
+            // happened as failed. The state holds in memory; only a restart loses it.
+            log.warn(`${label} could not write ${path} (${lost}): ${String(error)}`);
+        }
+    };
+    const read = async (key, until) => {
+        const state = places.get(key);
+        const outputs = new Set(state?.outputs);
+        const listing = await deps.read(key, {
+            ...(state?.cursor !== undefined ? { cursor: state.cursor } : {}),
+            drop: (id) => outputs.has(id) || deps.isTurnInput(key, id),
+        }, until);
+        return {
+            ...listing,
+            // A bounded read has accounted for everything up to its bound, the ask included: the next read starts after it.
+            newest: until ?? listing.newest,
+            outputsPassed: listing.covered.filter((id) => outputs.has(id)),
+        };
+    };
+    const unreadable = (key, error) => {
+        log.warn(`${label} could not read the history of place ${key}; the turn runs without it: ${String(error)}`);
+        return { text: `(could not read the recent discussion here: ${String(error)})`, folded: [] };
+    };
+    return {
+        async peek({ key, until }) {
+            try {
+                const { messages, newest, earlier, outputsPassed } = await read(key, until);
+                const { text, folded } = foldPlace(messages, earlier);
+                return { text, consumed: [{ ...(newest !== undefined ? { cursor: newest } : {}), folded, outputsPassed }] };
+            }
+            catch (error) {
+                const { text } = unreadable(key, error);
+                return { text, consumed: [{ folded: [], outputsPassed: [] }] };
+            }
+        },
+        commit({ key }, consumed) {
+            const done = consumed[0];
+            if (done?.cursor === undefined)
+                return;
+            // Only the outputs this read passed: the turn's own answer came after it and waits for the next read.
+            const passed = new Set(done.outputsPassed);
+            const state = places.get(key);
+            const outputs = (state?.outputs ?? []).filter((id) => !passed.has(id));
+            // Forward only. Turns in a place can finish out of ask order (a redelivered ask, a deferred turn); an earlier
+            // ask committing after a later one must not pull the cursor back over what that later turn already folded.
+            const cursor = state?.cursor !== undefined && deps.compare(state.cursor, done.cursor) >= 0 ? state.cursor : done.cursor;
+            save(key, { cursor, outputs }, "a restart may re-fold answered discussion");
+        },
+        recordOutput(key, messageId) {
+            const state = places.get(key);
+            const outputs = [...(state?.outputs ?? []), messageId].slice(-MAX_OUTPUTS);
+            save(key, { ...(state?.cursor !== undefined ? { cursor: state.cursor } : {}), outputs }, "after a restart this place's next read may fold the agent's own answer");
+        },
+        async room(key) {
+            try {
+                const { messages, earlier } = await read(key);
+                return foldPlace(messages, earlier);
+            }
+            catch (error) {
+                return unreadable(key, error);
+            }
+        },
+        async snapshot(key) {
+            const { messages, earlier } = await deps.read(key, { drop: () => false });
+            return foldPlace(messages, earlier);
+        },
+    };
+}
+function loadPlaces(path, label, isCursor) {
+    const raw = loadStateFile(path);
+    if (raw === undefined)
+        return new Map();
+    const valid = (value) => {
+        const state = value;
+        return (typeof state === "object" &&
+            state !== null &&
+            (state.cursor === undefined || isCursor(state.cursor)) &&
+            Array.isArray(state.outputs) &&
+            state.outputs.every((id) => typeof id === "string"));
+    };
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && Object.values(raw).every(valid)) {
+        return new Map(Object.entries(raw));
+    }
+    log.warn(`${label} unexpected shape in ${path} — every place reads its recent history afresh`);
+    return new Map();
+}

package/dist/channels/kit/preview-kit.d.ts

@@ -2,18 +2,19 @@
  * Channel-neutral live-preview pieces shared by every messaging channel's preview renderer (telegram/preview.ts,
  * feishu/preview.ts, slack/preview.ts).
  */
-import type { AgentEvent, Json } from "../../agent.ts";
+import type { Json, SessionEvent } from "../../agent-api.ts";
+import type { TurnEvent } from "./invoke-turn-kit.ts";
 /** A terminal failure, as a channel hands it to its `onError`. */
 export interface ChannelFailure {
     details: string;
     retryable: boolean;
-    /** The engine's failure code, when it set one. */
+    /** The harness's failure code, when it set one. */
     code?: string;
 }
 /** The customer-facing default: neutral, no leaked internals. */
 export declare function defaultErrorMessage(failed: ChannelFailure): string;
 /**
- * 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 declare const RETRY_NOTICE = "\u23F3 Temporary problem \u2014 retrying\u2026";
@@ -30,16 +31,19 @@ interface ToolLine {
 export interface TurnView {
     thinking: string;
     tools: ToolLine[];
-    /** tool-call id → its line, for `tool_ended` status flips (bookkeeping; renderers read `tools`). */
+    /** tool-call id → its line, for the `tool_result` status flips (bookkeeping; renderers read `tools`). */
     toolById: Map<string, ToolLine>;
     answer: string;
+    /** What each event adds to the answer: its delta, or the settled text no delta carried. */
+    textOf: (event: SessionEvent) => string;
     /** Arrival time of the first non-empty answer delta; age-based reveal policies read it. */
     answerSince?: number;
     /** An advisory retry backoff is in progress (closed again by any subsequent progress event). */
     retrying: boolean;
 }
 export declare function createTurnView(): TurnView;
-export declare function applyTurnEvent(view: TurnView, e: AgentEvent, now?: number): boolean;
+/** Fold one event of a turn's invoke into its view; true when what a renderer shows changed. */
+export declare function applyTurnEvent(view: TurnView, e: TurnEvent, now?: number): boolean;
 /**
  * The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. A running call shows its latest
  * progress after the mark (`🔧 Bash npm test … › 42 passed`); a finished one drops it.