@theoremjs/react 0.0.0-stage → 0.3.0

package/hooks/use-theorem-chat-state.js

@@ -0,0 +1,118 @@
+import { useCallback, useRef, useState } from 'react';
+import { emptyInterfaceTurnSession, } from '@theoremjs/agents/interface';
+/** Coalesces streamed partial blocks to one state update per animation frame. */
+function useStreamFrames(setStreamBlocks) {
+    const streamRafRef = useRef(null);
+    const pendingStreamRef = useRef(null);
+    const cancelPendingStreamFrame = useCallback(() => {
+        if (streamRafRef.current != null) {
+            cancelAnimationFrame(streamRafRef.current);
+            streamRafRef.current = null;
+        }
+        pendingStreamRef.current = null;
+    }, []);
+    const scheduleStreamBlocks = useCallback((partial) => {
+        pendingStreamRef.current = partial;
+        if (streamRafRef.current != null)
+            return;
+        streamRafRef.current = requestAnimationFrame(() => {
+            streamRafRef.current = null;
+            const next = pendingStreamRef.current;
+            pendingStreamRef.current = null;
+            if (next)
+                setStreamBlocks(next);
+        });
+    }, []);
+    return { cancelPendingStreamFrame, scheduleStreamBlocks };
+}
+/** Composer / transcript / session state behind {@link useTheoremChat}. */
+export function useTheoremChatState(initial) {
+    const [blocks, setBlocksState] = useState(initial?.blocks ?? []);
+    const [streamBlocks, setStreamBlocks] = useState([]);
+    const [draftText, setDraftText] = useState('');
+    const [pendingFiles, setPendingFiles] = useState([]);
+    const [pendingVoice, setPendingVoice] = useState([]);
+    const [pendingMessages, setPendingMessages] = useState([]);
+    const [issues, setIssues] = useState([]);
+    const [failure, setFailure] = useState(null);
+    const [answering, setAnswering] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const [chatStarted, setChatStarted] = useState((initial?.blocks.length ?? 0) > 0);
+    const [streaming, setStreaming] = useState(false);
+    const [session, setSession] = useState(initial?.session ?? emptyInterfaceTurnSession());
+    // One object per posted message, so a run can tell whether it posted one.
+    const [delivery, setDeliveryState] = useState(null);
+    const blocksRef = useRef(blocks);
+    // Set as it is written, so a caller awaiting a turn reads the transcript the turn left.
+    const setBlocks = useCallback((value) => {
+        blocksRef.current = typeof value === 'function' ? value(blocksRef.current) : value;
+        setBlocksState(blocksRef.current);
+    }, []);
+    const streamBlocksRef = useRef(streamBlocks);
+    streamBlocksRef.current = streamBlocks;
+    const busyRef = useRef(false);
+    const abortRef = useRef(null);
+    const turnIdRef = useRef(null);
+    const pendingRef = useRef(pendingMessages);
+    pendingRef.current = pendingMessages;
+    const sessionRef = useRef(session);
+    sessionRef.current = session;
+    const drainLockRef = useRef(false);
+    const allowQueueDrainRef = useRef(false);
+    const runPromiseRef = useRef(null);
+    const deliveryRef = useRef(delivery);
+    const setDelivery = useCallback((next) => {
+        deliveryRef.current = next;
+        setDeliveryState(next);
+    }, []);
+    const { cancelPendingStreamFrame, scheduleStreamBlocks } = useStreamFrames(setStreamBlocks);
+    const clearComposer = useCallback(() => {
+        setDraftText('');
+        setPendingFiles([]);
+        setPendingVoice([]);
+    }, []);
+    return {
+        blocks,
+        setBlocks,
+        streamBlocks,
+        setStreamBlocks,
+        streamBlocksRef,
+        draftText,
+        setDraftText,
+        pendingFiles,
+        setPendingFiles,
+        pendingVoice,
+        setPendingVoice,
+        pendingMessages,
+        setPendingMessages,
+        issues,
+        setIssues,
+        failure,
+        setFailure,
+        answering,
+        setAnswering,
+        busy,
+        setBusy,
+        chatStarted,
+        setChatStarted,
+        streaming,
+        setStreaming,
+        session,
+        setSession,
+        delivery,
+        setDelivery,
+        deliveryRef,
+        blocksRef,
+        busyRef,
+        abortRef,
+        turnIdRef,
+        pendingRef,
+        sessionRef,
+        drainLockRef,
+        allowQueueDrainRef,
+        runPromiseRef,
+        cancelPendingStreamFrame,
+        scheduleStreamBlocks,
+        clearComposer,
+    };
+}

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

@@ -0,0 +1,63 @@
+import { type ComposerPendingMessage, type ComposerProfileInterface, type ComposerRunPhase, type InterfaceTurnSession, type TranscriptBlock } from '@theoremjs/agents/interface';
+import type { TheoremTransport } from '../client/transport.ts';
+import { type ChatSnapshot, type MessageDelivery } from './use-theorem-chat-state.ts';
+export type { ChatSnapshot };
+export type UseTheoremChatOptions = {
+    transport: TheoremTransport;
+    /** Composer interface for the host profile — see `useTheoremInterface`. `null` while loading. */
+    iface: ComposerProfileInterface | null;
+    /** A conversation to resume: its transcript, and the session the next turn continues from. */
+    initial?: ChatSnapshot;
+    /**
+     * The conversation each time it comes to rest: a turn finished, or a message was added or
+     * removed. Never while a reply streams or waits on a gate.
+     */
+    onChange?: (snapshot: ChatSnapshot) => void;
+};
+/** What `sendText` hands back: the blocks the turn added, its user message and the reply. */
+export type SentTurn = {
+    blocks: TranscriptBlock[];
+};
+/**
+ * Headless chat model: transcript, streaming, composer drafts, pending
+ * queue / steer / stash, tool gates. Render it with `@theoremjs/react/ui` or
+ * your own components.
+ */
+export declare function useTheoremChat({ transport, iface, initial, onChange }: UseTheoremChatOptions): {
+    iface: ComposerProfileInterface | null;
+    blocks: TranscriptBlock[];
+    chatStarted: boolean;
+    draftText: string;
+    failure: import("../index.ts").ClientFailure | null;
+    /** The answer on its way to a gate, shown on it until the answer settles or fails. */
+    answering: import("../index.ts").AnsweringGate | null;
+    issues: import("@theoremjs/agents/interface").AttachmentValidationIssue[];
+    pendingFiles: File[];
+    pendingMessages: ComposerPendingMessage[];
+    pendingVoice: File[];
+    phase: ComposerRunPhase;
+    session: InterfaceTurnSession;
+    /** The latest message's delivery; `null` before the first and once its turn failed. */
+    delivery: MessageDelivery | null;
+    streamBlocks: TranscriptBlock[];
+    streaming: boolean;
+    setDraftText: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setPendingFiles: import("react").Dispatch<import("react").SetStateAction<File[]>>;
+    setPendingVoice: import("react").Dispatch<import("react").SetStateAction<File[]>>;
+    setPendingMessages: import("react").Dispatch<import("react").SetStateAction<ComposerPendingMessage[]>>;
+    setIssues: import("react").Dispatch<import("react").SetStateAction<import("@theoremjs/agents/interface").AttachmentValidationIssue[]>>;
+    handleAuthenticated: (_index: number, secret?: string) => Promise<void>;
+    handleBranch: (index: number) => void;
+    handleSubmit: () => Promise<void>;
+    handleStop: () => void;
+    handleMenuAction: (action: import("@theoremjs/agents/interface").ComposerMenuAction) => void;
+    handlePendingQueue: (id: string) => void;
+    handlePendingRestore: (id: string) => Promise<void>;
+    handleSendNow: (draftSource?: ComposerPendingMessage) => Promise<void>;
+    handleToolDecision: (_index: number, action: import("../index.ts").ToolDecisionAction) => Promise<void>;
+    handleGenerationChange: (next: {
+        modelId: string;
+        effort?: string;
+    }) => void;
+    sendText: (text: string) => Promise<SentTurn | null>;
+};

package/hooks/use-theorem-chat.js

@@ -0,0 +1,340 @@
+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 { followGenerationDefaults } from "../client/generation-selection.js";
+import { applyTurnResultToTranscript } from "../client/index.js";
+import { useTheoremChatActions } from "./use-theorem-chat-actions.js";
+import { useTheoremChatState, } from "./use-theorem-chat-state.js";
+/**
+ * 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
+ * pick the profile no longer has falls back to them (see `followGenerationDefaults`).
+ */
+function useDefaultGeneration(iface, session, setSession) {
+    const previous = useRef(undefined);
+    useEffect(() => {
+        if (!iface)
+            return;
+        const next = followGenerationDefaults(iface, { model: session.selectedModel, effort: session.selectedEffort }, previous.current);
+        previous.current = iface;
+        if (next.model === session.selectedModel && next.effort === session.selectedEffort)
+            return;
+        setSession((prev) => ({ ...prev, selectedModel: next.model, selectedEffort: next.effort }));
+    }, [session.selectedEffort, session.selectedModel, setSession, iface]);
+}
+/** 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);
+}
+/**
+ * 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) {
+    state.setFailure(null);
+    const priorDelivery = state.deliveryRef.current;
+    state.busyRef.current = true;
+    state.setBusy(true);
+    if (!userBlocksAlreadyApplied)
+        state.setStreaming(true);
+    state.allowQueueDrainRef.current = false;
+    return priorDelivery;
+}
+/** The run is over: nothing streams, and nothing can stop or steer it. */
+function endRun(state) {
+    state.cancelPendingStreamFrame();
+    state.busyRef.current = false;
+    state.setBusy(false);
+    state.setStreaming(false);
+    state.abortRef.current = null;
+    state.turnIdRef.current = null;
+}
+/**
+ * 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.
+ */
+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);
+}
+/**
+ * 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.
+ */
+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.
+    const replyWorkedMs = useRef(0);
+    const onRunEnded = useCallback((nextPending, drain) => {
+        const converted = convertSteersToFrontQueued(nextPending);
+        state.setPendingMessages(orderComposerPendingMessages(converted));
+        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)
+            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)),
+            };
+            const result = await run(view, paused);
+            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 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);
+        })();
+        state.runPromiseRef.current = work;
+        try {
+            await work;
+        }
+        finally {
+            if (state.runPromiseRef.current === work)
+                state.runPromiseRef.current = null;
+        }
+    }, [iface, onRunEnded, state]);
+}
+/** 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) {
+            return;
+        }
+        const { message, remaining } = consumeNextComposerQueue(state.pendingRef.current);
+        if (!message)
+            return;
+        state.drainLockRef.current = true;
+        state.setPendingMessages(remaining);
+        try {
+            await startTurnFromDraft(message.draft);
+        }
+        finally {
+            state.drainLockRef.current = false;
+        }
+    }, [startTurnFromDraft, state]);
+    useEffect(() => {
+        if (phase !== 'idle' || !state.allowQueueDrainRef.current)
+            return;
+        if (!state.pendingMessages.some((m) => m.kind === 'queue')) {
+            state.allowQueueDrainRef.current = false;
+            return;
+        }
+        state.allowQueueDrainRef.current = false;
+        void drainQueue();
+    }, [drainQueue, phase, state]);
+}
+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 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.
+ */
+function deliveryOf(event) {
+    if (REPLY_EVENTS.has(event.type))
+        return 'read';
+    return SERVER_EVENTS.has(event.type) ? 'sent' : 'delivered';
+}
+/**
+ * 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.
+ */
+function useTappedTransport(transport, state) {
+    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 });
+            }
+            onEvent(event);
+        };
+        return {
+            ...transport,
+            turn: (request, onEvent, signal) => transport.turn(request, tap(onEvent), signal),
+            invoke: (request, onEvent, signal) => transport.invoke(request, tap(onEvent), signal),
+        };
+    }, [transport, 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);
+    useDefaultGeneration(iface, state.session, state.setSession);
+    const gated = state.session.gatedTool !== null;
+    const phase = state.busy ? 'streaming' : gated ? 'gated' : 'idle';
+    const handleGenerationChange = useCallback((next) => {
+        const effort = next.effort ?? (iface ? defaultInterfaceEffort(iface, next.modelId) : undefined);
+        state.setSession((prev) => ({
+            ...prev,
+            selectedModel: next.modelId,
+            ...(effort ? { selectedEffort: effort } : { selectedEffort: undefined }),
+        }));
+    }, [iface, state]);
+    const runTurnStream = useRunTurnStream(iface, state);
+    const steerTransport = useTappedTransport(transport, state);
+    const actions = useTheoremChatActions({
+        ...state,
+        iface,
+        transport: steerTransport,
+        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) => {
+        if (!iface || state.busyRef.current || state.sessionRef.current.gatedTool !== null)
+            return null;
+        const before = state.blocksRef.current.length;
+        await actions.startTurnFromFields({ text, 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]);
+    const handlePendingQueue = useCallback((id) => {
+        const message = state.pendingRef.current.find((m) => m.id === id);
+        if (!message || message.kind !== 'stash')
+            return;
+        if (phase === 'idle') {
+            state.allowQueueDrainRef.current = true;
+        }
+        state.setPendingMessages((prev) => promoteComposerPendingKind(prev, id, 'queue'));
+    }, [phase, state]);
+    return {
+        iface,
+        blocks: state.blocks,
+        chatStarted: state.chatStarted,
+        draftText: state.draftText,
+        failure: state.failure,
+        /** The answer on its way to a gate, shown on it until the answer settles or fails. */
+        answering: state.answering,
+        issues: state.issues,
+        pendingFiles: state.pendingFiles,
+        pendingMessages: state.pendingMessages,
+        pendingVoice: state.pendingVoice,
+        phase,
+        session: state.session,
+        /** The latest message's delivery; `null` before the first and once its turn failed. */
+        delivery: state.delivery?.status ?? null,
+        streamBlocks: state.streamBlocks,
+        streaming: state.streaming,
+        setDraftText: state.setDraftText,
+        setPendingFiles: state.setPendingFiles,
+        setPendingVoice: state.setPendingVoice,
+        setPendingMessages: state.setPendingMessages,
+        setIssues: state.setIssues,
+        handleAuthenticated: actions.handleAuthenticated,
+        handleBranch,
+        handleSubmit: actions.handleSubmit,
+        handleStop: actions.handleStop,
+        handleMenuAction: actions.handleMenuAction,
+        handlePendingQueue,
+        handlePendingRestore: actions.handlePendingRestore,
+        handleSendNow: actions.handleSendNow,
+        handleToolDecision: actions.handleToolDecision,
+        handleGenerationChange,
+        sendText,
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { DecisionJson, DecisionResult } from '@theoremjs/agents';
+import type { DecisionInterface, DecisionTransport } from '../client/decision-transport.ts';
+import { type ClientFailure } from '../client/failure.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;
+};
+/**
+ * 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>;
+    cancel: () => void;
+};

package/hooks/use-theorem-decision.js

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { clientFailure } from "../client/failure.js";
+import { useDescribed } from "./use-described.js";
+/**
+ * One decision profile: describe it once, then `decide(state)` as often as
+ * needed. A new decision aborts the one still running.
+ */
+export function useTheoremDecision(transport) {
+    const { iface, describeFailure } = useDescribed(transport);
+    const [run, setRun] = useState({
+        transport,
+        status: 'idle',
+        result: null,
+        elapsedMs: null,
+        failure: null,
+    });
+    const running = useRef(null);
+    useEffect(() => () => running.current?.abort(), [transport]);
+    const cancel = useCallback(() => {
+        running.current?.abort();
+        running.current = null;
+        setRun((previous) => previous.status === 'deciding'
+            ? { ...previous, status: previous.result ? 'done' : 'idle' }
+            : previous);
+    }, []);
+    const decide = useCallback(async (state) => {
+        running.current?.abort();
+        const controller = new AbortController();
+        running.current = controller;
+        setRun((previous) => ({
+            transport,
+            status: 'deciding',
+            result: previous.transport === transport ? previous.result : null,
+            elapsedMs: previous.transport === transport ? previous.elapsedMs : null,
+            failure: null,
+        }));
+        const started = performance.now();
+        try {
+            const reply = await transport.decide(state, controller.signal);
+            if (controller.signal.aborted)
+                return;
+            for (const record of reply.traces ?? [])
+                transport.traces?.push(record);
+            setRun({
+                transport,
+                status: 'done',
+                result: reply.result,
+                elapsedMs: performance.now() - started,
+                failure: null,
+            });
+        }
+        catch (err) {
+            if (controller.signal.aborted)
+                return;
+            setRun((previous) => ({ ...previous, status: 'error', failure: clientFailure(err) }));
+        }
+        finally {
+            if (running.current === controller)
+                running.current = null;
+        }
+    }, [transport]);
+    const visible = run.transport === transport
+        ? run
+        : { status: 'idle', result: null, elapsedMs: null, failure: null };
+    return {
+        iface,
+        describeFailure,
+        status: visible.status,
+        result: visible.result,
+        elapsedMs: visible.elapsedMs,
+        failure: visible.failure,
+        decide,
+        cancel,
+    };
+}

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

@@ -0,0 +1,44 @@
+import type { TurnEvent } from '@theoremjs/agents';
+import { type ClientFailure } from '../client/failure.ts';
+import type { ToolCall } from '../client/host-call.ts';
+import type { HostInterface, HostTransport } from '../client/host-transport.ts';
+import { type ToolGateResolution } from '../client/tool-resume.ts';
+export type { ToolCall };
+/** One call of one of the host's tools, as it streams. */
+export type TheoremHostCall = {
+    /** The page's id for the call, before the host names it. */
+    id: string;
+    name: string;
+    input: unknown;
+    /** Everything the host streamed for the call, answers included. */
+    events: TurnEvent[];
+    /** The call as its events fold: its state is the phase it is in. */
+    call: ToolCall | null;
+    /** The tool's latest progress report while it runs. */
+    progress: unknown;
+    isRunning: boolean;
+    /** The call never reached its tool, or its stream broke. */
+    failure: ClientFailure | null;
+    /** The answer on its way to the gate the call paused on. */
+    answering: ToolGateResolution['action'] | null;
+    startedAt: number;
+    /** Round trip, once it settles or pauses. */
+    elapsedMs: number | null;
+};
+export type TheoremHostState = {
+    /** The host as the page sees it; null until it describes itself. */
+    iface: HostInterface | null;
+    describeFailure: ClientFailure | null;
+    /** This page's calls, newest first. */
+    calls: TheoremHostCall[];
+};
+/**
+ * One host profile: describe it once, then `run(name, input)` any of its tools
+ * as often as needed, and answer the gates a call pauses on. `run` returns the
+ * call's id at once; calls run side by side, and `cancel` stops one.
+ */
+export declare function useTheoremHost(transport: HostTransport): TheoremHostState & {
+    run: (name: string, input: unknown) => string;
+    answer: (id: string, resolution: ToolGateResolution) => Promise<void>;
+    cancel: (id: string) => void;
+};