@theoremjs/react 0.3.0 → 0.3.1

package/hooks/use-theorem-chat.js

@@ -1,10 +1,62 @@
-import { useCallback, useEffect, useMemo, useRef } from 'react';
-import { branchInterfaceTurnSession, consumeNextComposerQueue, convertSteersToFrontQueued, defaultInterfaceEffort, orderComposerPendingMessages, promoteComposerPendingKind, removeLandedSteers, } from '@theoremjs/agents/interface';
-import { clientFailure } from "../client/failure.js";
+import { branchInterfaceTurnSession, consumeNextComposerQueue, convertSteersToFrontQueued, defaultInterfaceEffort, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, } from '@theoremjs/agents/interface';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { clientFailure, turnFailure } from "../client/failure.js";
 import { followGenerationDefaults } from "../client/generation-selection.js";
-import { applyTurnResultToTranscript } from "../client/index.js";
+import { withPageToolDispatch } from "../client/page-dispatch.js";
+import { sessionAfter, stampWorked } from "../client/run-commit.js";
+import { keepsConversation } from "../client/run-session.js";
+import { foldAssistantTurn } from "../client/turn-client.js";
+import { usePageToolWarnings } from "./use-page-tool-warnings.js";
 import { useTheoremChatActions } from "./use-theorem-chat-actions.js";
 import { useTheoremChatState, } from "./use-theorem-chat-state.js";
+/**
+ * The slots the profile declares and the value of each: the page's where it names one, else what
+ * the visitor chose, else the first allowed value.
+ */
+function useSlotChoices(iface, fixed, onSlotsChange) {
+    const [picked, setPicked] = useState({});
+    const declared = iface?.inputs.slots;
+    const values = useMemo(() => {
+        const out = { ...fixed };
+        for (const [name, allowed] of Object.entries(declared ?? {})) {
+            const value = fixed?.[name] ?? picked[name] ?? allowed[0];
+            if (value !== undefined)
+                out[name] = value;
+        }
+        return out;
+    }, [declared, fixed, picked]);
+    const choose = useCallback((name, value) => {
+        setPicked((prev) => ({ ...prev, [name]: value }));
+        onSlotsChange?.({ ...values, [name]: value });
+    }, [values, onSlotsChange]);
+    const isChosen = declared !== undefined && Object.keys(declared).length > 0;
+    return {
+        values: isChosen || fixed ? values : undefined,
+        choices: isChosen ? { declared, values, onChange: choose } : undefined,
+    };
+}
+/**
+ * Settles legacy page gates as unanswered. Browser callbacks require an active dispatch grant.
+ */
+function usePageAnswers(gated, pageTools, answer) {
+    const answered = useRef(null);
+    const latest = useRef({ pageTools, answer });
+    latest.current = { pageTools, answer };
+    const waiting = gated?.gateKind === 'page' ? gated : null;
+    useEffect(() => {
+        if (!waiting?.operationId || answered.current === waiting.operationId)
+            return;
+        const operationId = waiting.operationId;
+        answered.current = operationId;
+        // invariant: A restored page gate cannot authorize callback execution. Only active dispatch grants do.
+        void latest.current.answer({ action: 'page', page: { unanswered: true } });
+    }, [waiting]);
+}
+/** The page's side of a chat: answers the calls that wait on it, and warns of a tool it cannot answer. */
+function usePageTools(iface, waitingOn, pageTools, answer) {
+    usePageAnswers(waitingOn, pageTools, answer);
+    usePageToolWarnings(iface && 'tools' in iface ? iface.tools.page : undefined, pageTools);
+}
 /**
  * Seed the session with the profile's default model / effort once the interface loads, and keep
  * it valid as the interface changes: a pick still on the old defaults follows the new ones, and a
@@ -22,43 +74,52 @@ function useDefaultGeneration(iface, session, setSession) {
         setSession((prev) => ({ ...prev, selectedModel: next.model, selectedEffort: next.effort }));
     }, [session.selectedEffort, session.selectedModel, setSession, iface]);
 }
+function useConversationRef(initial, onChange) {
+    const ref = useRef(initial);
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const adopt = useCallback((next) => {
+        if (ref.current === next)
+            return;
+        ref.current = next;
+        onChangeRef.current?.(next);
+    }, []);
+    return useMemo(() => ({ ref, adopt }), [adopt]);
+}
+/** Draws the conversation as the host shows it: its transcript, and the reply that waits on gates. */
+function drawConversation(state, view, session, events) {
+    state.setBlocks(view.transcript);
+    state.setStreamBlocks(view.paused?.blocks ?? []);
+    // why: A reply at rest leaves the run's own events (tokens, an ask); a paused one, the host's.
+    state.setSession(sessionAfter(session, view.paused?.events ?? events));
+    state.setChatStarted(view.transcript.length > 0 || view.paused !== undefined);
+}
 /** 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 }];
 }
-/**
- * Shows a failed turn's error. Once the message is in the transcript, the
- * failure is too, closing the turn (the message, or the reply as far as it
- * got, shows it failed); a message that never went out (refused attachments)
- * is still in the composer, and a reply that still waits on a gate stays open,
- * so the failure shows in the composer.
- */
-function showTurnFailure(state, result, streamed, open) {
-    const { error, errorKind, errorInternal } = result;
-    if (open) {
-        state.setFailure({ error, errorKind, ...(errorInternal ? { errorInternal } : {}) });
-    }
-    else {
-        const failed = withTurnError(streamed, error);
-        state.setBlocks((prev) => [...prev, ...failed]);
-        state.setDelivery(null);
-    }
-    if (result.issues)
-        state.setIssues(result.issues);
+/** A failure the composer shows: none when the person stopped the run. */
+function showComposerFailure(state, failure) {
+    if (!failure || failure.aborted)
+        return;
+    const { error, errorKind, errorInternal } = failure;
+    state.setFailure({ error, errorKind, ...(errorInternal ? { errorInternal } : {}) });
+    if (failure.issues)
+        state.setIssues(failure.issues);
 }
 /**
  * The run begins: busy, and streaming unless its message goes live when it
  * posts (onUserBlocks), so the previous reply never renders as streaming in
  * between. Returns the delivery before it, which a new message replaces.
  */
-function beginRun(state, userBlocksAlreadyApplied) {
+function beginRun(state, message) {
     state.setFailure(null);
     const priorDelivery = state.deliveryRef.current;
     state.busyRef.current = true;
     state.setBusy(true);
-    if (!userBlocksAlreadyApplied)
+    if (!message)
         state.setStreaming(true);
     state.allowQueueDrainRef.current = false;
     return priorDelivery;
@@ -72,108 +133,181 @@ function endRun(state) {
     state.abortRef.current = null;
     state.turnIdRef.current = null;
 }
+/** A message that never reached the conversation leaves the transcript and goes back in the composer. */
+async function takeBackMessage(state, start, restore) {
+    state.setBlocks(start.blocks);
+    state.setStreamBlocks(start.streamBlocks);
+    state.setChatStarted(start.blocks.length > 0 || start.streamBlocks.length > 0);
+    state.setDelivery(null);
+    await restore();
+}
 /**
- * A failed run: its session (when it has one) and its error. A message that
- * never posted, or an answer that left its reply paused (as it was, or on its
- * next gate), keeps the transcript as it was, the paused reply waiting in it.
+ * 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.
  */
-function failRun(state, result, stream, unposted) {
-    const waits = (result.session ?? state.sessionRef.current).gatedTool !== null;
-    const open = unposted || waits;
-    if (result.session)
-        state.setSession(result.session);
-    if (!result.aborted)
-        showTurnFailure(state, result, stream.streamed, open);
-    if (!open)
-        state.setStreamBlocks([]);
-    else
-        state.setStreamBlocks(result.session ? stream.streamed : stream.before);
+async function settleHosted(state, transport, conversation, outcome, start) {
+    const { failure } = outcome;
+    if (failure)
+        state.setDelivery(null);
+    if (conversation === undefined) {
+        state.setStreamBlocks(start.streamBlocks);
+        showComposerFailure(state, failure);
+        return state.sessionRef.current.gatedTool !== null;
+    }
+    const view = await transport.conversation({ conversation });
+    drawConversation(state, view, outcome.session, outcome.events);
+    if (!view.transcript.slice(start.blocks.length).some((b) => b.kind === 'error')) {
+        showComposerFailure(state, 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 person's stop), or beside it
+ * while it waits on a gate. Returns whether it waits.
+ */
+function settleLocal(state, iface, outcome, worked) {
+    const session = sessionAfter(outcome.session, outcome.events);
+    const { failure } = outcome;
+    const reply = stampWorked(foldAssistantTurn(iface, outcome.events), worked);
+    state.setSession(session);
+    if (session.gatedTool !== null) {
+        state.setStreamBlocks(reply);
+        showComposerFailure(state, failure);
+        return true;
+    }
+    state.setStreamBlocks([]);
+    if (!failure) {
+        state.setBlocks((prev) => [...prev, ...reply]);
+        return false;
+    }
+    state.setDelivery(null);
+    const closing = failure.aborted
+        ? [{ id: crypto.randomUUID(), kind: 'turn-done', stop: { kind: 'cancelled' } }]
+        : withTurnError(reply, failure.error);
+    state.setBlocks((prev) => [...prev, ...closing]);
+    if (failure.issues)
+        state.setIssues(failure.issues);
+    return false;
+}
+/**
+ * Draws the conversation the chat resumes, once the interface says the host
+ * keeps one. A run that starts first draws it itself.
+ */
+function useResumedConversation(iface, transport, state, conversation, shown) {
+    const loaded = useRef(false);
+    const shownRef = useRef(shown);
+    useEffect(() => {
+        if (!iface || loaded.current)
+            return;
+        loaded.current = true;
+        const ref = conversation.ref.current;
+        if (ref === undefined || !keepsConversation(iface))
+            return;
+        if (shownRef.current) {
+            drawConversation(state, shownRef.current, state.sessionRef.current, []);
+            return;
+        }
+        void (async () => {
+            const before = state.blocksRef.current;
+            try {
+                const view = await transport.conversation({ conversation: ref });
+                // why: A message sent while it loaded posted onto the host's conversation; its run draws it.
+                if (state.blocksRef.current !== before || state.busyRef.current)
+                    return;
+                drawConversation(state, view, state.sessionRef.current, []);
+            }
+            catch (err) {
+                showComposerFailure(state, turnFailure(err, iface.labels));
+            }
+        })();
+    }, [conversation, iface, state, transport]);
 }
 /**
  * Runs one turn's stream into the transcript: live partials while it streams,
- * then the committed result (or the error) and the pending queue's next step.
+ * then what the run left (or its failure) and the pending queue's next step.
  */
-function useRunTurnStream(iface, state) {
-    // The current reply's work across its runs: a gate splits a reply into runs, and the wait between doesn't count.
+function useRunTurnStream(iface, transport, state, conversation) {
+    // why: A stateless reply's work across its runs: a gate splits a reply into runs, and the wait between doesn't count.
     const replyWorkedMs = useRef(0);
-    const onRunEnded = useCallback((nextPending, drain) => {
-        const converted = convertSteersToFrontQueued(nextPending);
-        state.setPendingMessages(orderComposerPendingMessages(converted));
+    // why: Steers the reply never took wait at the front of the queue.
+    const onRunEnded = useCallback((drain) => {
+        state.setPendingMessages((prev) => orderComposerPendingMessages(convertSteersToFrontQueued(prev)));
         state.allowQueueDrainRef.current = drain;
-        return converted;
     }, [state]);
     return useCallback(async (run, options = {}) => {
         if (!iface || state.busyRef.current)
             return;
-        const applied = options.userBlocksAlreadyApplied === true;
-        const priorDelivery = beginRun(state, applied);
-        const streamBefore = state.streamBlocksRef.current;
-        const paused = { workedMs: state.sessionRef.current.gatedTool ? replyWorkedMs.current : 0 };
-        // A run that answers a gate (a decision, sign-in) continues its reply; any other, walking away included, starts one.
-        if (!state.sessionRef.current.gatedTool || options.walksAway)
+        const { message } = options;
+        const priorDelivery = beginRun(state, message !== undefined);
+        const start = {
+            blocks: state.blocksRef.current,
+            streamBlocks: state.streamBlocksRef.current,
+        };
+        // why: A run that answers a gate continues its reply; any other starts one.
+        if (!state.sessionRef.current.gatedTool)
             replyWorkedMs.current = 0;
         const runStartedAt = Date.now();
         const work = (async () => {
-            let latestStream = [];
             const view = {
-                blocks: (partial) => {
-                    latestStream = partial;
-                    state.scheduleStreamBlocks(partial);
-                },
-                // The reply goes on; the composer names what it left out.
-                skipped: (error) => state.setFailure(clientFailure(error, iface.lexicon)),
+                blocks: (partial) => state.scheduleStreamBlocks(partial),
+                // why: The reply goes on; the composer names what it left out.
+                skipped: (error) => state.setFailure(clientFailure(error, iface.labels)),
             };
-            const result = await run(view, paused);
+            const outcome = await run(view);
             const endedAt = Date.now();
             replyWorkedMs.current += endedAt - runStartedAt;
             endRun(state);
-            if (!result.ok) {
-                // A new message posts itself (onUserBlocks) with a fresh delivery.
-                const unposted = applied && state.deliveryRef.current === priorDelivery;
-                failRun(state, result, { streamed: latestStream, before: streamBefore }, unposted);
-                onRunEnded(state.pendingRef.current, false);
-                return;
+            const unposted = message !== undefined && !outcome.posted;
+            // why: A message that posts itself (onUserBlocks) gets a fresh delivery.
+            if (unposted && state.deliveryRef.current !== priorDelivery) {
+                await takeBackMessage(state, start, message.restore);
             }
-            const merged = applyTurnResultToTranscript({
-                blocks: state.blocksRef.current,
-                streamBlocks: latestStream,
-                session: result.session,
-                userBlocks: applied ? undefined : result.userBlocks,
-                assistantBlocks: result.assistantBlocks,
-                worked: { workedMs: replyWorkedMs.current, endedAt },
-            });
-            state.setBlocks(merged.blocks);
-            state.setStreamBlocks(merged.streamBlocks);
-            state.setSession(merged.session);
-            if (merged.session.gatedTool !== null)
-                return;
-            onRunEnded(state.pendingRef.current, true);
+            let waits;
+            if (keepsConversation(iface)) {
+                waits = await settleHosted(state, transport, conversation.ref.current, outcome, start);
+            }
+            else if (unposted) {
+                showComposerFailure(state, outcome.failure);
+                waits = state.sessionRef.current.gatedTool !== null;
+            }
+            else {
+                waits = settleLocal(state, iface, outcome, { workedMs: replyWorkedMs.current, endedAt });
+            }
+            onRunEnded(!outcome.failure && !waits);
         })();
         state.runPromiseRef.current = work;
         try {
             await work;
         }
+        catch (err) {
+            // why: The run left no view to draw; the composer says so, and the chat stays as it stood.
+            showComposerFailure(state, turnFailure(err, iface.labels));
+            onRunEnded(false);
+        }
         finally {
             if (state.runPromiseRef.current === work)
                 state.runPromiseRef.current = null;
         }
-    }, [iface, onRunEnded, state]);
+    }, [conversation, iface, onRunEnded, state, transport]);
 }
 /** Start the next queued message once the run goes idle, when the run that ended allows it. */
 function useQueueDrain(phase, state, startTurnFromDraft) {
     const drainQueue = useCallback(async () => {
-        if (state.drainLockRef.current ||
-            state.busyRef.current ||
-            state.sessionRef.current.gatedTool) {
+        if (state.drainLockRef.current || state.busyRef.current || state.sessionRef.current.gatedTool) {
             return;
         }
-        const { message, remaining } = consumeNextComposerQueue(state.pendingRef.current);
+        const { message } = consumeNextComposerQueue(state.pendingRef.current);
         if (!message)
             return;
         state.drainLockRef.current = true;
-        state.setPendingMessages(remaining);
         try {
-            await startTurnFromDraft(message.draft);
+            // why: The message leaves the queue once it posts; one that never starts stays queued.
+            await startTurnFromDraft(message.draft, {
+                onPosted: () => state.setPendingMessages((prev) => removeComposerPendingMessage(prev, message.id)),
+            });
         }
         finally {
             state.drainLockRef.current = false;
@@ -196,48 +330,91 @@ 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 an event shows the message got: 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.
+ * 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(event) {
-    if (REPLY_EVENTS.has(event.type))
+function deliveryOf(line) {
+    if (line.type === 'conversation')
+        return line.posted ? 'sent' : undefined;
+    if (REPLY_EVENTS.has(line.type))
         return 'read';
-    return SERVER_EVENTS.has(event.type) ? 'sent' : 'delivered';
+    return SERVER_EVENTS.has(line.type) ? 'sent' : 'delivered';
+}
+/** Moves the message's delivery on to what `line` shows it reached, never back. */
+function advanceDelivery(deliveryRef, setDelivery, line) {
+    const delivery = deliveryRef.current;
+    const reached = deliveryOf(line);
+    if (!delivery || !reached)
+        return;
+    if (DELIVERY_ORDER.indexOf(reached) > DELIVERY_ORDER.indexOf(delivery.status)) {
+        setDelivery({ status: reached });
+    }
 }
 /**
  * The transport, with each turn's events also clearing the steers they report
  * as landed (so the run's end requeues only the steers the agent never saw),
- * and moving the posted message's delivery forward.
+ * and moving the posted message's delivery forward. The chat adopts each
+ * conversation ref as it arrives, so a page that reloads mid-reply keeps the
+ * posted message. Each turn carries the page's slots and context as they are
+ * when it is sent.
  */
-function useTappedTransport(transport, state) {
+function useTappedTransport(transport, state, conversation, values, onTurnEvent) {
+    const valuesRef = useRef(values);
+    valuesRef.current = values;
+    const onTurnEventRef = useRef(onTurnEvent);
+    onTurnEventRef.current = onTurnEvent;
     return useMemo(() => {
-        const tap = (onEvent) => (event) => {
-            if (event.type === 'stage' && event.injected?.length) {
-                state.pendingRef.current = removeLandedSteers(state.pendingRef.current, event);
-                state.setPendingMessages((prev) => removeLandedSteers(prev, event));
-            }
-            const delivery = state.deliveryRef.current;
-            const reached = deliveryOf(event);
-            if (delivery && DELIVERY_ORDER.indexOf(reached) > DELIVERY_ORDER.indexOf(delivery.status)) {
-                state.setDelivery({ status: reached });
+        const withValues = (request) => {
+            const { slots, context } = valuesRef.current;
+            if (slots === undefined && context === undefined)
+                return request;
+            return {
+                ...request,
+                input: {
+                    ...request.input,
+                    ...(slots === undefined ? {} : { slots }),
+                    ...(context === undefined ? {} : { context }),
+                },
+            };
+        };
+        const tap = (onLine) => (line) => {
+            if (line.type === 'stage' && line.injected?.length) {
+                state.pendingRef.current = removeLandedSteers(state.pendingRef.current, line);
+                state.setPendingMessages((prev) => removeLandedSteers(prev, line));
             }
-            onEvent(event);
+            advanceDelivery(state.deliveryRef, state.setDelivery, line);
+            if (line.type === 'conversation')
+                conversation.adopt(line.ref);
+            else
+                onTurnEventRef.current?.(line);
+            onLine(line);
         };
         return {
             ...transport,
-            turn: (request, onEvent, signal) => transport.turn(request, tap(onEvent), signal),
-            invoke: (request, onEvent, signal) => transport.invoke(request, tap(onEvent), signal),
+            turn: (request, onLine, signal) => transport.turn(withValues(request), tap(onLine), signal),
+            invoke: (request, onLine, signal) => transport.invoke(request, tap(onLine), signal),
         };
-    }, [transport, state.pendingRef, state.setPendingMessages, state.deliveryRef, state.setDelivery]);
+    }, [
+        transport,
+        conversation,
+        state.pendingRef,
+        state.setPendingMessages,
+        state.deliveryRef,
+        state.setDelivery,
+    ]);
 }
 /**
  * Headless chat model: transcript, streaming, composer drafts, pending
  * queue / steer / stash, tool gates. Render it with `@theoremjs/react/ui` or
  * your own components.
  */
-export function useTheoremChat({ transport, iface, initial, onChange }) {
-    const state = useTheoremChatState(initial);
+export function useTheoremChat({ transport, iface, conversation: initialConversation, conversationView, initialText, onConversationChange, slots, onSlotsChange, context, pageTools, onTurnEvent, }) {
+    const slotState = useSlotChoices(iface, slots, onSlotsChange);
+    const state = useTheoremChatState(initialText);
+    const conversation = useConversationRef(initialConversation, onConversationChange);
+    useResumedConversation(iface, transport, state, conversation, conversationView);
     useDefaultGeneration(iface, state.session, state.setSession);
     const gated = state.session.gatedTool !== null;
     const phase = state.busy ? 'streaming' : gated ? 'gated' : 'idle';
@@ -249,53 +426,63 @@ export function useTheoremChat({ transport, iface, initial, onChange }) {
             ...(effort ? { selectedEffort: effort } : { selectedEffort: undefined }),
         }));
     }, [iface, state]);
-    const runTurnStream = useRunTurnStream(iface, state);
-    const steerTransport = useTappedTransport(transport, state);
+    const runTurnStream = useRunTurnStream(iface, transport, state, conversation);
+    const pageTransport = useMemo(() => withPageToolDispatch(transport, pageTools), [transport, pageTools]);
+    const steerTransport = useTappedTransport(pageTransport, state, conversation, { slots: slotState.values, context }, onTurnEvent);
     const actions = useTheoremChatActions({
         ...state,
         iface,
         transport: steerTransport,
+        conversationRef: conversation.ref,
         phase,
         gated,
         runTurnStream,
     });
     useQueueDrain(phase, state, actions.startTurnFromDraft);
-    const onChangeRef = useRef(onChange);
-    onChangeRef.current = onChange;
-    const restedOn = useRef(initial);
-    useEffect(() => {
-        if (state.busy || gated)
-            return;
-        const last = restedOn.current;
-        if (last && last.blocks === state.blocks && last.session === state.session)
-            return;
-        const snapshot = { blocks: state.blocks, session: state.session };
-        restedOn.current = snapshot;
-        onChangeRef.current?.(snapshot);
-    }, [state.busy, gated, state.blocks, state.session]);
-    /** Sends `text` as the composer would, and resolves once the reply is done; `null` when it can't go now. */
-    const sendText = useCallback(async (text) => {
+    usePageTools(iface, phase === 'gated' ? state.session.gatedTool : null, pageTools, actions.resumeGatedTool);
+    /** Sends `text` and optional files as the composer would, and resolves once the reply is done; `null` when it can't go now. */
+    const sendText = useCallback(async (text, files = []) => {
         if (!iface || state.busyRef.current || state.sessionRef.current.gatedTool !== null)
             return null;
         const before = state.blocksRef.current.length;
-        await actions.startTurnFromFields({ text, files: [], voice: [] });
+        await actions.startTurnFromFields({ text, files: [...files], voice: [] });
         return { blocks: state.blocksRef.current.slice(before) };
     }, [actions, iface, state]);
-    const handleBranch = useCallback((index) => {
-        const kept = [...state.blocks, ...state.streamBlocks].slice(0, index + 1);
-        state.setBlocks(kept);
-        state.setStreamBlocks([]);
-        state.setStreaming(false);
-        state.busyRef.current = false;
-        state.setBusy(false);
-        state.setChatStarted(kept.length > 0);
-        // The kept transcript's last message isn't the one whose delivery was tracked.
-        state.setDelivery(null);
-        state.setSession((prevSession) => branchInterfaceTurnSession(prevSession, kept));
-    }, [iface, state]);
+    /**
+     * Cut the conversation after transcript block `index`. A host that keeps
+     * the conversation cuts it (walking away from a reply that waits on gates)
+     * and the chat draws what it returns; a stateless chat cuts its own.
+     */
+    const handleBranch = useCallback(async (index) => {
+        if (!iface || state.busyRef.current)
+            return;
+        const ref = conversation.ref.current;
+        if (!keepsConversation(iface) || ref === undefined) {
+            const kept = [...state.blocksRef.current, ...state.streamBlocksRef.current].slice(0, index + 1);
+            state.setBlocks(kept);
+            state.setStreamBlocks([]);
+            state.setChatStarted(kept.length > 0);
+            // why: The kept transcript's last message isn't the one whose delivery was tracked.
+            state.setDelivery(null);
+            state.setSession((prev) => branchInterfaceTurnSession(prev, kept));
+            return;
+        }
+        state.setFailure(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, state.blocksRef.current.length - 1);
+            const rewound = await transport.rewind({ conversation: ref, at });
+            conversation.adopt(rewound.conversation);
+            drawConversation(state, rewound.view, state.sessionRef.current, []);
+            state.setDelivery(null);
+        }
+        catch (err) {
+            showComposerFailure(state, turnFailure(err, iface.labels));
+        }
+    }, [conversation, iface, state, transport]);
     const handlePendingQueue = useCallback((id) => {
         const message = state.pendingRef.current.find((m) => m.id === id);
-        if (!message || message.kind !== 'stash')
+        if (message?.kind !== 'stash')
             return;
         if (phase === 'idle') {
             state.allowQueueDrainRef.current = true;
@@ -335,6 +522,7 @@ export function useTheoremChat({ transport, iface, initial, onChange }) {
         handleSendNow: actions.handleSendNow,
         handleToolDecision: actions.handleToolDecision,
         handleGenerationChange,
+        slotChoices: slotState.choices,
         sendText,
     };
 }

package/hooks/use-theorem-decision.d.ts

@@ -1,23 +1,18 @@
-import type { DecisionJson, DecisionResult } from '@theoremjs/agents';
+import type { DecisionAsset, DecisionJson, DecisionResult } from '@theoremjs/agents';
 import type { DecisionInterface, DecisionTransport } from '../client/decision-transport.ts';
-import { type ClientFailure } from '../client/failure.ts';
+import type { ClientFailure } from '../client/failure.ts';
+import { type OneCallState } from './use-one-call.ts';
 export type TheoremDecisionState = {
     /** The profile as the page sees it; null until the host describes it. */
     iface: DecisionInterface | null;
     /** Why the host could not describe the profile. */
     describeFailure: ClientFailure | null;
-    status: 'idle' | 'deciding' | 'done' | 'error';
-    /** The last answers; kept while the next decision runs and when it fails. */
-    result: DecisionResult | null;
-    /** How long the last decision took, round trip, in milliseconds. */
-    elapsedMs: number | null;
-    failure: ClientFailure | null;
-};
+} & OneCallState<'deciding', DecisionResult>;
 /**
  * One decision profile: describe it once, then `decide(state)` as often as
  * needed. A new decision aborts the one still running.
  */
 export declare function useTheoremDecision(transport: DecisionTransport): TheoremDecisionState & {
-    decide: (state: Exclude<DecisionJson, null>) => Promise<void>;
+    decide: (state: Exclude<DecisionJson, null>, assets?: Record<string, DecisionAsset>) => Promise<void>;
     cancel: () => void;
 };