@theoremjs/web 0.0.0-stage → 0.3.4-next.375.ga2d1878

package/client/chat.js

@@ -0,0 +1,760 @@
+import { TheoremError } from '@theoremjs/agents';
+import { branchInterfaceTurnSession, consumeNextComposerQueue, convertSteersToFrontQueued, createComposerPendingMessage, defaultInterfaceEffort, emptyInterfaceTurnSession, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, userDraftHasPayload, userDraftToSteerInject, } from '@theoremjs/agents/interface';
+import { composerHasPayload } from "./composer-primary.js";
+import { composerFieldsFromDraft } from "./decode-composer-draft.js";
+import { encodeComposerDraft } from "./encode-composer-draft.js";
+import { clientFailure, turnFailure } from "./failure.js";
+import { followGenerationDefaults } from "./generation-selection.js";
+import { warnPageToolMismatch } from "./live/live-page-tool.js";
+import { withPageToolDispatch } from "./page-dispatch.js";
+import { sessionAfter, stampWorked } from "./run-commit.js";
+import { keepsConversation, resumeInterfaceTool, streamInterfaceDraftTurn, streamInterfaceTurn, } from "./run-session.js";
+import { foldAssistantTurn, issuedOperationId } from "./turn-client.js";
+const DELIVERY_ORDER = ['sending', 'sent', 'delivered', 'read'];
+/** The server's own reports (bookkeeping, a failure, the end), which say nothing of the model having the message. */
+const SERVER_EVENTS = new Set(['stage', 'guardrail', 'session', 'error', 'done']);
+/** The reply itself (its thinking and tool calls come before it). */
+const REPLY_EVENTS = new Set(['text', 'structured', 'media']);
+/**
+ * How far a line shows the message got: the host saving it, or any event,
+ * means the server took it; one from the model (thinking, a tool call) means
+ * the model has it, and the reply means it was read. A save without the
+ * message (a walk settling calls) says nothing of it.
+ */
+function deliveryOf(line) {
+    if (line.type === 'conversation')
+        return line.posted ? 'sent' : undefined;
+    if (REPLY_EVENTS.has(line.type))
+        return 'read';
+    return SERVER_EVENTS.has(line.type) ? 'sent' : 'delivered';
+}
+/** The streamed blocks, ending on the turn's error unless the stream already carried it. */
+function withTurnError(blocks, error) {
+    if (blocks.some((block) => block.kind === 'error'))
+        return blocks;
+    return [...blocks, { id: crypto.randomUUID(), kind: 'error', message: error }];
+}
+function slotsOf(iface, fixed, picked) {
+    const declared = iface?.inputs.slots ?? {};
+    const values = { ...fixed };
+    for (const [name, allowed] of Object.entries(declared)) {
+        const value = fixed?.[name] ?? picked[name] ?? allowed[0];
+        if (value !== undefined)
+            values[name] = value;
+    }
+    const chosen = Object.keys(declared).length > 0;
+    return {
+        values: chosen || fixed ? values : undefined,
+        slots: chosen ? { declared, values } : undefined,
+    };
+}
+function sameSlots(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    const keys = Object.keys(a.values);
+    return (a.declared === b.declared &&
+        keys.length === Object.keys(b.values).length &&
+        keys.every((key) => a.values[key] === b.values[key]));
+}
+/** One frame later in a browser; a timer's tick elsewhere. Returns the cancel. */
+function nextFrame(run) {
+    // why: The client also runs where there are no frames (a server, a test), so it asks before it uses them.
+    const frames = globalThis;
+    if (frames.requestAnimationFrame && frames.cancelAnimationFrame) {
+        const id = frames.requestAnimationFrame(run);
+        return () => frames.cancelAnimationFrame?.(id);
+    }
+    const id = setTimeout(run, 16);
+    return () => clearTimeout(id);
+}
+function newTurnId() {
+    return crypto.randomUUID();
+}
+class Chat {
+    #options;
+    #state;
+    #notified;
+    #listeners = new Set();
+    #flushQueued = false;
+    #busy = false;
+    #abort = null;
+    #turnId = null;
+    /** The run in flight; it settles, never rejects. */
+    #run = null;
+    // why: A stateless reply's work across its runs: a gate splits a reply into runs, and the wait between doesn't count.
+    #replyWorkedMs = 0;
+    /** The run that ended let the queue send its next message. */
+    #drainArmed = false;
+    #draining = false;
+    #conversation;
+    // why: One object per posted message, so a run can tell whether it posted one.
+    #delivery = null;
+    #picked = {};
+    #resumed = false;
+    #defaultsFrom;
+    #answeredPage = null;
+    #pageToolsWarned;
+    #frame = null;
+    #frameBlocks = null;
+    constructor(options) {
+        this.#options = options;
+        this.#conversation = options.conversation;
+        this.#state = {
+            iface: options.iface,
+            blocks: [],
+            streamBlocks: [],
+            chatStarted: false,
+            draftText: options.initialText ?? '',
+            pendingFiles: [],
+            pendingVoice: [],
+            pendingMessages: [],
+            issues: [],
+            failure: null,
+            answering: null,
+            phase: 'idle',
+            session: emptyInterfaceTurnSession(),
+            delivery: null,
+            streaming: false,
+            slots: slotsOf(options.iface, options.slots, {}).slots,
+        };
+        this.#notified = this.#state;
+        this.#warnPageTools();
+        this.#settle();
+    }
+    getState = () => this.#state;
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    };
+    update = (options) => {
+        this.#options = options;
+        this.#warnPageTools();
+        const { slots } = slotsOf(options.iface, options.slots, this.#picked);
+        const patch = {};
+        if (options.iface !== this.#state.iface)
+            patch.iface = options.iface;
+        if (!sameSlots(slots, this.#state.slots))
+            patch.slots = slots;
+        if (Object.keys(patch).length > 0)
+            this.#set(patch);
+    };
+    setDraftText = (value) => this.#apply('draftText', value);
+    setPendingFiles = (value) => this.#apply('pendingFiles', value);
+    setPendingVoice = (value) => this.#apply('pendingVoice', value);
+    setPendingMessages = (value) => this.#apply('pendingMessages', value);
+    setIssues = (value) => this.#apply('issues', value);
+    submit = async () => {
+        const { phase, draftText, pendingFiles, pendingVoice } = this.#state;
+        if (phase !== 'idle') {
+            await this.enqueue('queue');
+            return;
+        }
+        this.#set({ issues: [] });
+        await this.#sendFields({ text: draftText, files: [...pendingFiles], voice: [...pendingVoice] });
+    };
+    stop = () => {
+        this.#abort?.abort();
+    };
+    enqueue = async (kind) => {
+        const { draftText, pendingFiles, pendingVoice } = this.#state;
+        if (!composerHasPayload(draftText, pendingFiles, pendingVoice))
+            return;
+        this.#set({ issues: [] });
+        try {
+            const draft = await encodeComposerDraft({ text: draftText, pendingFiles, pendingVoice });
+            const message = createComposerPendingMessage({ kind, draft });
+            this.#set({
+                pendingMessages: orderComposerPendingMessages([...this.#state.pendingMessages, message]),
+                ...this.#clearedComposer(),
+            });
+            if (kind !== 'steer')
+                return;
+            const turnId = this.#turnId;
+            if (!turnId) {
+                this.#steerAfterTurnEnded();
+                return;
+            }
+            const inject = userDraftToSteerInject(draft);
+            if (inject.length === 0)
+                return;
+            await this.#options.transport.steer({ turnId, id: message.id, inject });
+        }
+        catch (err) {
+            this.#set({ failure: clientFailure(err, this.#options.iface?.labels) });
+        }
+    };
+    sendNow = async (source) => {
+        if (!this.#options.iface)
+            return;
+        const draft = source ? source.draft : await this.#composerDraft();
+        if (!draft)
+            return;
+        if (this.#busy) {
+            this.#abort?.abort();
+            await this.#run;
+        }
+        this.#set({ pendingMessages: convertSteersToFrontQueued(this.#state.pendingMessages) });
+        this.#drainArmed = false;
+        // why: Sent while the reply waits on gates, the message walks away from them in its own request.
+        await this.#sendDraft(draft, {
+            walkAway: this.#state.session.gatedTool !== null,
+            // why: The sent message leaves the queue, or the composer it came from.
+            onPosted: () => this.#set(source
+                ? {
+                    pendingMessages: removeComposerPendingMessage(this.#state.pendingMessages, source.id),
+                }
+                : this.#clearedComposer()),
+        });
+    };
+    menuAction = (action) => {
+        if (action === 'queue' || action === 'steer' || action === 'stash') {
+            void this.enqueue(action);
+            return;
+        }
+        if (action === 'send_now')
+            void this.sendNow();
+    };
+    restorePending = async (id) => {
+        const message = this.#state.pendingMessages.find((m) => m.id === id);
+        if (!message)
+            return;
+        try {
+            await this.#restore(composerFieldsFromDraft(message.draft));
+            this.#set({
+                pendingMessages: removeComposerPendingMessage(this.#state.pendingMessages, id),
+            });
+        }
+        catch (err) {
+            this.#set({ failure: clientFailure(err, this.#options.iface?.labels) });
+        }
+    };
+    queuePending = (id) => {
+        const message = this.#state.pendingMessages.find((m) => m.id === id);
+        if (message?.kind !== 'stash')
+            return;
+        if (this.#state.phase === 'idle')
+            this.#drainArmed = true;
+        this.#set({
+            pendingMessages: promoteComposerPendingKind(this.#state.pendingMessages, id, 'queue'),
+        });
+    };
+    decide = (action) => this.#answerGate({ action });
+    authenticate = (secret) => this.#answerGate({ action: 'auth', ...(secret === undefined ? {} : { secret }) });
+    branch = async (index) => {
+        const { iface } = this.#options;
+        if (!iface || this.#busy)
+            return;
+        const ref = this.#conversation;
+        if (!keepsConversation(iface) || ref === undefined) {
+            const kept = [...this.#state.blocks, ...this.#state.streamBlocks].slice(0, index + 1);
+            // why: The kept transcript's last message isn't the one whose delivery was tracked.
+            this.#setDelivery(null);
+            this.#set({
+                blocks: kept,
+                streamBlocks: [],
+                chatStarted: kept.length > 0,
+                session: branchInterfaceTurnSession(this.#state.session, kept),
+            });
+            return;
+        }
+        this.#set({ failure: null });
+        try {
+            // why: The paused reply is not in the host's transcript; a cut inside it keeps the transcript whole.
+            const at = Math.min(index, this.#state.blocks.length - 1);
+            const rewound = await this.#options.transport.rewind({ conversation: ref, at });
+            this.#adopt(rewound.conversation);
+            this.#draw(rewound.view, this.#state.session, []);
+            this.#setDelivery(null);
+        }
+        catch (err) {
+            this.#showFailure(turnFailure(err, iface.labels));
+        }
+    };
+    setGeneration = (next) => {
+        const { iface } = this.#options;
+        const effort = next.effort ?? (iface ? defaultInterfaceEffort(iface, next.modelId) : undefined);
+        this.#set({
+            session: { ...this.#state.session, selectedModel: next.modelId, selectedEffort: effort },
+        });
+    };
+    pickSlot = (name, value) => {
+        const before = slotsOf(this.#options.iface, this.#options.slots, this.#picked).values;
+        this.#picked = { ...this.#picked, [name]: value };
+        this.#set({ slots: slotsOf(this.#options.iface, this.#options.slots, this.#picked).slots });
+        this.#options.onSlotsChange?.({ ...before, [name]: value });
+    };
+    sendText = async (text, files = []) => {
+        if (!this.#options.iface || this.#state.phase !== 'idle')
+            return null;
+        const before = this.#state.blocks.length;
+        await this.#sendFields({ text, files: [...files], voice: [] });
+        return { blocks: this.#state.blocks.slice(before) };
+    };
+    #set(patch) {
+        const next = { ...this.#state, ...patch };
+        next.phase = this.#busy ? 'streaming' : next.session.gatedTool ? 'gated' : 'idle';
+        this.#state = next;
+        if (this.#flushQueued)
+            return;
+        this.#flushQueued = true;
+        // why: Changes made together reach listeners once, after the code that made them has run.
+        queueMicrotask(() => this.#flush());
+    }
+    #apply(key, value) {
+        const next = typeof value === 'function'
+            ? value(this.#state[key])
+            : value;
+        this.#set({ [key]: next });
+    }
+    #flush() {
+        this.#flushQueued = false;
+        this.#settle();
+        if (this.#flushQueued || this.#notified === this.#state)
+            return;
+        this.#notified = this.#state;
+        for (const listener of [...this.#listeners])
+            listener();
+    }
+    /**
+     * What follows from the state as it now stands: the profile's default model, the conversation
+     * the chat resumes, a page gate that has no answer, and the queue's next message. Each is done
+     * once, so settling again changes nothing.
+     */
+    #settle() {
+        const { iface } = this.#options;
+        if (!iface)
+            return;
+        this.#followDefaults(iface);
+        this.#resume(iface);
+        this.#answerPageGate();
+        this.#drain();
+    }
+    #clearedComposer() {
+        return { draftText: '', pendingFiles: [], pendingVoice: [] };
+    }
+    #setDelivery(next) {
+        this.#delivery = next;
+        this.#set({ delivery: next?.status ?? null });
+    }
+    #adopt(ref) {
+        if (this.#conversation === ref)
+            return;
+        this.#conversation = ref;
+        this.#options.onConversationChange?.(ref);
+    }
+    #showFailure(failure) {
+        if (!failure || failure.aborted)
+            return;
+        const { error, errorKind, errorInternal } = failure;
+        this.#set({
+            failure: { error, errorKind, ...(errorInternal ? { errorInternal } : {}) },
+            ...(failure.issues ? { issues: failure.issues } : {}),
+        });
+    }
+    /** Draws the conversation as the host shows it: its transcript, and the reply that waits on gates. */
+    #draw(view, session, events) {
+        this.#set({
+            blocks: view.transcript,
+            streamBlocks: view.paused?.blocks ?? [],
+            // why: A reply at rest leaves the run's own events (tokens, an ask); a paused one, the host's.
+            session: sessionAfter(session, view.paused?.events ?? events),
+            chatStarted: view.transcript.length > 0 || view.paused !== undefined,
+        });
+    }
+    /**
+     * Keeps the model and effort valid as the interface changes: a pick still on the old defaults
+     * follows the new ones, and a pick the profile no longer has falls back to them.
+     */
+    #followDefaults(iface) {
+        const { session } = this.#state;
+        const next = followGenerationDefaults(iface, { model: session.selectedModel, effort: session.selectedEffort }, this.#defaultsFrom);
+        this.#defaultsFrom = iface;
+        if (next.model === session.selectedModel && next.effort === session.selectedEffort)
+            return;
+        this.#set({ session: { ...session, selectedModel: next.model, selectedEffort: next.effort } });
+    }
+    /** Draws the conversation the chat resumes, once. A run that starts first draws it itself. */
+    #resume(iface) {
+        if (this.#resumed)
+            return;
+        this.#resumed = true;
+        const ref = this.#conversation;
+        if (ref === undefined || !keepsConversation(iface))
+            return;
+        const shown = this.#options.conversationView;
+        if (shown) {
+            this.#draw(shown, this.#state.session, []);
+            return;
+        }
+        const before = this.#state.blocks;
+        void this.#options.transport.conversation({ conversation: ref }).then((view) => {
+            // why: A message sent while it loaded posted onto the host's conversation; its run draws it.
+            if (this.#state.blocks !== before || this.#busy)
+                return;
+            this.#draw(view, this.#state.session, []);
+        }, (err) => this.#showFailure(turnFailure(err, iface.labels)));
+    }
+    /**
+     * Settles a restored page gate as unanswered.
+     * invariant: A restored page gate cannot authorize callback execution. Only active dispatch grants do.
+     */
+    #answerPageGate() {
+        const gated = this.#state.phase === 'gated' ? this.#state.session.gatedTool : null;
+        if (gated?.gateKind !== 'page' || !gated.operationId)
+            return;
+        if (this.#answeredPage === gated.operationId)
+            return;
+        this.#answeredPage = gated.operationId;
+        void this.#answerGate({ action: 'page', page: { unanswered: true } });
+    }
+    /** Sends the next queued message once the chat is idle, when the run that ended allowed it. */
+    #drain() {
+        if (this.#state.phase !== 'idle' || !this.#drainArmed)
+            return;
+        this.#drainArmed = false;
+        if (this.#draining)
+            return;
+        const { message } = consumeNextComposerQueue(this.#state.pendingMessages);
+        if (!message)
+            return;
+        this.#draining = true;
+        // why: The message leaves the queue once it posts; one that never starts stays queued.
+        void this.#sendDraft(message.draft, {
+            onPosted: () => this.#set({
+                pendingMessages: removeComposerPendingMessage(this.#state.pendingMessages, message.id),
+            }),
+        }).finally(() => {
+            this.#draining = false;
+        });
+    }
+    /** Says in the console, once for each set of names, where the page's tools and the profile's disagree. */
+    #warnPageTools() {
+        const { iface, pageTools } = this.#options;
+        const declared = iface && 'tools' in iface ? iface.tools.page : undefined;
+        if (declared === undefined)
+            return;
+        const handled = Object.keys(pageTools ?? {}).sort();
+        const key = JSON.stringify([declared, handled]);
+        if (key === this.#pageToolsWarned)
+            return;
+        this.#pageToolsWarned = key;
+        warnPageToolMismatch(declared, handled);
+    }
+    /** The composer's draft, when it holds something to send. */
+    async #composerDraft() {
+        const { draftText, pendingFiles, pendingVoice } = this.#state;
+        const draft = await encodeComposerDraft({ text: draftText, pendingFiles, pendingVoice });
+        return userDraftHasPayload(draft) ? draft : undefined;
+    }
+    /** Puts a message back in the composer. What the composer holds now is stashed first, so nothing typed is lost. */
+    async #restore(fields) {
+        const { draftText, pendingFiles, pendingVoice } = this.#state;
+        if (composerHasPayload(draftText, pendingFiles, pendingVoice)) {
+            const draft = await encodeComposerDraft({ text: draftText, pendingFiles, pendingVoice });
+            const stash = createComposerPendingMessage({ kind: 'stash', draft });
+            this.#set({
+                pendingMessages: orderComposerPendingMessages([...this.#state.pendingMessages, stash]),
+            });
+        }
+        this.#set({
+            draftText: fields.text,
+            pendingFiles: fields.files,
+            pendingVoice: fields.voice,
+            issues: [],
+        });
+    }
+    /** A steer with no running turn: the visitor reads `session.turn_ended`; steers, this one too, move to the front of the queue. */
+    #steerAfterTurnEnded() {
+        this.#set({
+            failure: clientFailure(
+            // labels-exempt: internal diagnostic; the user reads session.turn_ended
+            new TheoremError('request', 'steer: no active turn', {
+                copy: { key: 'session.turn_ended' },
+            }), this.#options.iface?.labels),
+            // why: The composer already gave the message up, so it waits as the next to send, not lost.
+            pendingMessages: orderComposerPendingMessages(convertSteersToFrontQueued(this.#state.pendingMessages)),
+        });
+    }
+    /** The message posted: it joins the transcript, and the reply starts streaming. */
+    #posted(blocks, patch) {
+        this.#setDelivery({ status: 'sending' });
+        this.#set({
+            blocks: [...this.#state.blocks, ...blocks],
+            chatStarted: true,
+            streaming: true,
+            ...patch,
+        });
+    }
+    #sendFields(fields) {
+        return this.#runTurn(({ iface, view, transport, scope, signal }) => streamInterfaceTurn({
+            iface,
+            transport,
+            session: this.#state.session,
+            text: fields.text,
+            pendingFiles: fields.files,
+            pendingVoice: fields.voice,
+            signal,
+            scope,
+            view,
+            transcript: this.#state.blocks,
+            onUserBlocks: (blocks) => this.#posted(blocks, this.#clearedComposer()),
+        }), { turn: true, message: { restore: () => this.#restore(fields) } });
+    }
+    #sendDraft(draft, options) {
+        return this.#runTurn(({ iface, view, transport, scope, signal }) => streamInterfaceDraftTurn({
+            iface,
+            transport,
+            session: this.#state.session,
+            draft,
+            signal,
+            scope,
+            view,
+            transcript: this.#state.blocks,
+            walkAway: options.walkAway === true,
+            onUserBlocks: (blocks) => {
+                this.#posted(blocks, { streamBlocks: [] });
+                options.onPosted();
+            },
+        }), { turn: true, message: { restore: () => this.#restore(composerFieldsFromDraft(draft)) } });
+    }
+    async #answerGate(resolution) {
+        // why: Set once the run starts (not while another runs), and cleared once it has ended.
+        let started = false;
+        try {
+            await this.#runTurn(({ iface, view, transport, scope }) => {
+                started = true;
+                const { session } = this.#state;
+                // why: A person's answer shows on its gate while it settles; the page's has no gate to show on.
+                if (session.gatedTool && resolution.action !== 'page') {
+                    this.#set({
+                        answering: {
+                            callId: session.gatedTool.callId,
+                            operationId: issuedOperationId(session.gatedTool),
+                            action: resolution.action,
+                        },
+                    });
+                }
+                return resumeInterfaceTool({ iface, transport, session, scope, resolution, view });
+            });
+        }
+        finally {
+            if (started)
+                this.#set({ answering: null });
+        }
+    }
+    /**
+     * The transport each run uses: the page's tools answer their calls, each turn carries the
+     * page's slots and context as they are when it is sent, and each line lands the steers it
+     * reports, moves the message's delivery on, and hands the chat the conversation's new ref
+     * (so a page that reloads mid-reply keeps the posted message).
+     */
+    #runTransport() {
+        const { transport, pageTools } = this.#options;
+        const base = withPageToolDispatch(transport, pageTools);
+        const tap = (onLine) => (line) => {
+            this.#took(line);
+            onLine(line);
+        };
+        return {
+            ...base,
+            turn: (request, onLine, signal) => base.turn(this.#withValues(request), tap(onLine), signal),
+            invoke: (request, onLine, signal) => base.invoke(request, tap(onLine), signal),
+        };
+    }
+    #withValues(request) {
+        const { iface, slots: fixed, context } = this.#options;
+        const slots = slotsOf(iface, fixed, this.#picked).values;
+        if (slots === undefined && context === undefined)
+            return request;
+        return {
+            ...request,
+            input: {
+                ...request.input,
+                ...(slots === undefined ? {} : { slots }),
+                ...(context === undefined ? {} : { context }),
+            },
+        };
+    }
+    /** One line of a run's stream, before the run folds it. */
+    #took(line) {
+        if (line.type === 'stage' && line.injected?.length) {
+            this.#set({ pendingMessages: removeLandedSteers(this.#state.pendingMessages, line) });
+        }
+        const reached = deliveryOf(line);
+        const delivery = this.#delivery;
+        if (delivery &&
+            reached &&
+            DELIVERY_ORDER.indexOf(reached) > DELIVERY_ORDER.indexOf(delivery.status)) {
+            this.#setDelivery({ status: reached });
+        }
+        if (line.type === 'conversation')
+            this.#adopt(line.ref);
+        else
+            this.#options.onTurnEvent?.(line);
+    }
+    #streamFrame(partial) {
+        this.#frameBlocks = partial;
+        if (this.#frame)
+            return;
+        // why: A stream can carry many lines a frame; the chat draws the latest once per frame.
+        this.#frame = nextFrame(() => {
+            this.#frame = null;
+            const next = this.#frameBlocks;
+            this.#frameBlocks = null;
+            if (next)
+                this.#set({ streamBlocks: next });
+        });
+    }
+    /**
+     * Runs one stream into the transcript: live partials while it streams, then what the run left
+     * (or its failure) and the queue's next step. Does nothing while another run is in flight.
+     */
+    async #runTurn(run, options = {}) {
+        const { iface } = this.#options;
+        if (!iface || this.#busy)
+            return;
+        const { message } = options;
+        const priorDelivery = this.#delivery;
+        const abort = options.turn ? new AbortController() : null;
+        const turnId = options.turn ? newTurnId() : undefined;
+        this.#busy = true;
+        this.#abort = abort;
+        this.#turnId = turnId ?? null;
+        this.#drainArmed = false;
+        // why: A message streams once it posts, so the previous reply never shows as streaming before it.
+        this.#set({ failure: null, ...(message ? {} : { streaming: true }) });
+        const start = { blocks: this.#state.blocks, streamBlocks: this.#state.streamBlocks };
+        // why: A run that answers a gate continues its reply; any other starts one.
+        if (!this.#state.session.gatedTool)
+            this.#replyWorkedMs = 0;
+        const startedAt = Date.now();
+        const done = (async () => {
+            try {
+                const outcome = await run({
+                    iface,
+                    transport: this.#runTransport(),
+                    scope: { conversation: this.#conversation, turnId },
+                    signal: abort?.signal,
+                    view: {
+                        blocks: (partial) => this.#streamFrame(partial),
+                        // why: The reply goes on; the composer names what it left out.
+                        skipped: (error) => this.#set({ failure: clientFailure(error, iface.labels) }),
+                    },
+                });
+                const endedAt = Date.now();
+                this.#replyWorkedMs += endedAt - startedAt;
+                this.#endRun();
+                const unposted = message !== undefined && !outcome.posted;
+                // why: A message that posts itself (onUserBlocks) gets a fresh delivery.
+                if (unposted && this.#delivery !== priorDelivery)
+                    await this.#takeBack(start, message);
+                let waits;
+                if (keepsConversation(iface)) {
+                    waits = await this.#settleHosted(outcome, start);
+                }
+                else if (unposted) {
+                    this.#showFailure(outcome.failure);
+                    waits = this.#state.session.gatedTool !== null;
+                }
+                else {
+                    waits = this.#settleLocal(iface, outcome, { workedMs: this.#replyWorkedMs, endedAt });
+                }
+                this.#runEnded(!outcome.failure && !waits);
+            }
+            catch (err) {
+                // why: The run left no view to draw; the composer says so, and the chat stays as it stood.
+                this.#endRun();
+                this.#showFailure(turnFailure(err, iface.labels));
+                this.#runEnded(false);
+            }
+        })();
+        this.#run = done;
+        await done;
+        if (this.#run === done)
+            this.#run = null;
+    }
+    /** The run is over: nothing streams, and nothing can stop or steer it. */
+    #endRun() {
+        this.#frame?.();
+        this.#frame = null;
+        this.#frameBlocks = null;
+        this.#busy = false;
+        this.#abort = null;
+        this.#turnId = null;
+        this.#set({ streaming: false });
+    }
+    /** Steers the reply never took wait at the front of the queue; the queue sends on when `drain`. */
+    #runEnded(drain) {
+        this.#drainArmed = drain;
+        this.#set({
+            pendingMessages: orderComposerPendingMessages(convertSteersToFrontQueued(this.#state.pendingMessages)),
+        });
+    }
+    /** A message that never reached the conversation leaves the transcript and goes back in the composer. */
+    async #takeBack(start, message) {
+        this.#setDelivery(null);
+        this.#set({
+            blocks: start.blocks,
+            streamBlocks: start.streamBlocks,
+            chatStarted: start.blocks.length > 0 || start.streamBlocks.length > 0,
+        });
+        await message.restore();
+    }
+    /**
+     * A host that keeps the conversation is the truth: the chat draws it again from its ref, even
+     * after a message that never posted (a walk can settle calls before it fails). A failure shows
+     * in the composer unless the host's transcript closed on it. Returns whether the reply waits
+     * on gates.
+     */
+    async #settleHosted(outcome, start) {
+        const { failure } = outcome;
+        if (failure)
+            this.#setDelivery(null);
+        const ref = this.#conversation;
+        if (ref === undefined) {
+            this.#set({ streamBlocks: start.streamBlocks });
+            this.#showFailure(failure);
+            return this.#state.session.gatedTool !== null;
+        }
+        const view = await this.#options.transport.conversation({ conversation: ref });
+        this.#draw(view, outcome.session, outcome.events);
+        if (!view.transcript.slice(start.blocks.length).some((b) => b.kind === 'error')) {
+            this.#showFailure(failure);
+        }
+        return view.paused !== undefined;
+    }
+    /**
+     * A stateless chat keeps the reply as the run streamed it: in the transcript once it ends
+     * (closed by its failure, or by the visitor's stop), or beside it while it waits on a gate.
+     * Returns whether it waits.
+     */
+    #settleLocal(iface, outcome, worked) {
+        const session = sessionAfter(outcome.session, outcome.events);
+        const { failure } = outcome;
+        const reply = stampWorked(foldAssistantTurn(iface, outcome.events), worked);
+        if (session.gatedTool !== null) {
+            this.#set({ session, streamBlocks: reply });
+            this.#showFailure(failure);
+            return true;
+        }
+        if (!failure) {
+            this.#set({ session, streamBlocks: [], blocks: [...this.#state.blocks, ...reply] });
+            return false;
+        }
+        this.#setDelivery(null);
+        const closing = failure.aborted
+            ? [{ id: crypto.randomUUID(), kind: 'turn-done', stop: { kind: 'cancelled' } }]
+            : withTurnError(reply, failure.error);
+        this.#set({
+            session,
+            streamBlocks: [],
+            blocks: [...this.#state.blocks, ...closing],
+            ...(failure.issues ? { issues: failure.issues } : {}),
+        });
+        return false;
+    }
+}
+/** A chat for `options`. Framework-free: see `ChatController`. */
+export function createChatController(options) {
+    return new Chat(options);
+}