@theoremjs/react 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,287 @@
+import { TheoremError } from '@theoremjs/agents';
+import { convertSteersToFrontQueued, createComposerPendingMessage, orderComposerPendingMessages, removeComposerPendingMessage, userDraftHasPayload, userDraftToSteerInject, } from '@theoremjs/agents/interface';
+import { useCallback } from 'react';
+import { clientFailure } from "../client/failure.js";
+import { composerFieldsFromDraft, encodeComposerDraft, resumeInterfaceTool, streamInterfaceDraftTurn, streamInterfaceTurn, } from "../client/index.js";
+import { issuedOperationId } from "../client/turn-client.js";
+function composerFieldsPayload(text, pendingFiles, pendingVoice) {
+    const meta = (files) => files.map((f) => ({
+        name: f.name,
+        mimeType: f.type || 'application/octet-stream',
+        sizeBytes: f.size,
+    }));
+    return {
+        ...(text.trim() ? { text } : {}),
+        ...(pendingFiles.length ? { attachments: meta(pendingFiles) } : {}),
+        ...(pendingVoice.length ? { voice: meta(pendingVoice) } : {}),
+    };
+}
+function newTurnId() {
+    return typeof crypto !== 'undefined' && 'randomUUID' in crypto
+        ? crypto.randomUUID()
+        : `turn-${Date.now()}`;
+}
+function beginAbortableTurn(args) {
+    if (!args.iface)
+        return null;
+    const controller = new AbortController();
+    args.abortRef.current = controller;
+    const turnId = newTurnId();
+    args.turnIdRef.current = turnId;
+    return {
+        composer: args.iface,
+        turnId,
+        signal: controller.signal,
+    };
+}
+/** The run's scope: the conversation the chat continues, and the run's own turn. */
+function scopeOf(args, turnId) {
+    return { conversation: args.conversationRef.current, turnId };
+}
+/**
+ * Puts a message back in the composer. What the composer holds now is
+ * stashed first, so nothing the user typed is lost.
+ */
+function useRestoreToComposer(args) {
+    return useCallback(async (fields) => {
+        const { draftText, pendingFiles, pendingVoice } = args.composerRef.current;
+        if (userDraftHasPayload(composerFieldsPayload(draftText, pendingFiles, pendingVoice))) {
+            const draft = await encodeComposerDraft({ text: draftText, pendingFiles, pendingVoice });
+            const stash = createComposerPendingMessage({ kind: 'stash', draft });
+            args.setPendingMessages((prev) => orderComposerPendingMessages([...prev, stash]));
+        }
+        args.setDraftText(fields.text);
+        args.setPendingFiles(fields.files);
+        args.setPendingVoice(fields.voice);
+        args.setIssues([]);
+    }, [args]);
+}
+/** Starts a turn from the composer's fields, or from an encoded draft (queued or send-now). */
+function useTurnStarters(args, restoreToComposer) {
+    const startTurnFromFields = useCallback(async (fields) => {
+        const started = beginAbortableTurn(args);
+        if (!started)
+            return;
+        await args.runTurnStream((view) => streamInterfaceTurn({
+            iface: started.composer,
+            transport: args.transport,
+            session: args.sessionRef.current,
+            text: fields.text,
+            pendingFiles: fields.files,
+            pendingVoice: fields.voice,
+            signal: started.signal,
+            scope: scopeOf(args, started.turnId),
+            view,
+            transcript: args.blocksRef.current,
+            onUserBlocks: (userBlocks) => {
+                args.setBlocks((prev) => [...prev, ...userBlocks]);
+                args.setDelivery({ status: 'sending' });
+                args.setChatStarted(true);
+                args.setStreaming(true);
+                args.clearComposer();
+            },
+        }), { message: { restore: () => restoreToComposer(fields) } });
+    }, [args, restoreToComposer]);
+    const startTurnFromDraft = useCallback(async (draft, options = {}) => {
+        const started = beginAbortableTurn(args);
+        if (!started)
+            return;
+        await args.runTurnStream((view) => streamInterfaceDraftTurn({
+            iface: started.composer,
+            transport: args.transport,
+            session: args.sessionRef.current,
+            draft,
+            signal: started.signal,
+            scope: scopeOf(args, started.turnId),
+            view,
+            transcript: args.blocksRef.current,
+            walkAway: options.walkAway === true,
+            onUserBlocks: (posted) => {
+                args.setBlocks((prev) => [...prev, ...posted]);
+                args.setStreamBlocks([]);
+                args.setDelivery({ status: 'sending' });
+                args.setChatStarted(true);
+                args.setStreaming(true);
+                options.onPosted?.();
+            },
+        }), { message: { restore: () => restoreToComposer(composerFieldsFromDraft(draft)) } });
+    }, [args, restoreToComposer]);
+    return { startTurnFromFields, startTurnFromDraft };
+}
+/** A steer with no running turn: the user reads `session.turn_ended`; queued steers move to the front. */
+function steerAfterTurnEnded(args, messageId) {
+    args.setFailure(clientFailure(
+    // labels-exempt: internal diagnostic; the user reads session.turn_ended
+    new TheoremError('request', 'steer: no active turn', { copy: { key: 'session.turn_ended' } }), args.iface?.labels));
+    args.setPendingMessages((prev) => orderComposerPendingMessages(convertSteersToFrontQueued(removeComposerPendingMessage(prev, messageId))));
+}
+/** Queue / steer / stash the composer draft, and restore a pending message into the composer. */
+function usePendingActions(args, restoreToComposer) {
+    const enqueuePending = useCallback(async (kind) => {
+        if (!userDraftHasPayload(composerFieldsPayload(args.draftText, args.pendingFiles, args.pendingVoice))) {
+            return;
+        }
+        args.setIssues([]);
+        try {
+            const draft = await encodeComposerDraft({
+                text: args.draftText,
+                pendingFiles: args.pendingFiles,
+                pendingVoice: args.pendingVoice,
+            });
+            const message = createComposerPendingMessage({ kind, draft });
+            args.setPendingMessages((prev) => orderComposerPendingMessages([...prev, message]));
+            args.clearComposer();
+            if (kind !== 'steer')
+                return;
+            const turnId = args.turnIdRef.current;
+            if (!turnId) {
+                steerAfterTurnEnded(args, message.id);
+                return;
+            }
+            const inject = userDraftToSteerInject(draft);
+            if (inject.length === 0)
+                return;
+            await args.transport.steer({ turnId, id: message.id, inject });
+        }
+        catch (err) {
+            args.setFailure(clientFailure(err, args.iface?.labels));
+        }
+    }, [args]);
+    const handlePendingRestore = useCallback(async (id) => {
+        const message = args.pendingRef.current.find((m) => m.id === id);
+        if (!message)
+            return;
+        try {
+            await restoreToComposer(composerFieldsFromDraft(message.draft));
+            args.setPendingMessages((prev) => removeComposerPendingMessage(prev, id));
+        }
+        catch (err) {
+            args.setFailure(clientFailure(err, args.iface?.labels));
+        }
+    }, [args, restoreToComposer]);
+    return { enqueuePending, handlePendingRestore };
+}
+/** Answer the gate the session waits on: a decision, or a sign-in. */
+function useGateActions(args) {
+    const resumeGatedTool = useCallback(async (resolution) => {
+        const composer = args.iface;
+        if (!composer)
+            return;
+        // why: Set once the run starts (not while another runs), and cleared once it has ended.
+        let started = false;
+        try {
+            await args.runTurnStream((view) => {
+                started = true;
+                const session = args.sessionRef.current;
+                // 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')
+                    args.setAnswering({
+                        callId: session.gatedTool.callId,
+                        operationId: issuedOperationId(session.gatedTool),
+                        action: resolution.action,
+                    });
+                return resumeInterfaceTool({
+                    iface: composer,
+                    transport: args.transport,
+                    session,
+                    scope: scopeOf(args),
+                    resolution,
+                    view,
+                });
+            });
+        }
+        finally {
+            if (started)
+                args.setAnswering(null);
+        }
+    }, [args]);
+    const handleToolDecision = useCallback(async (_index, action) => {
+        await resumeGatedTool({ action });
+    }, [resumeGatedTool]);
+    const handleAuthenticated = useCallback(async (_index, secret) => {
+        await resumeGatedTool({ action: 'auth', ...(secret === undefined ? {} : { secret }) });
+    }, [resumeGatedTool]);
+    return { handleToolDecision, handleAuthenticated, resumeGatedTool };
+}
+export function useTheoremChatActions(args) {
+    const restoreToComposer = useRestoreToComposer(args);
+    const { startTurnFromFields, startTurnFromDraft } = useTurnStarters(args, restoreToComposer);
+    const { enqueuePending, handlePendingRestore } = usePendingActions(args, restoreToComposer);
+    const { handleToolDecision, handleAuthenticated, resumeGatedTool } = useGateActions(args);
+    const handleStop = useCallback(() => {
+        args.abortRef.current?.abort();
+    }, [args]);
+    const handleSubmit = useCallback(async () => {
+        if (args.phase === 'streaming' || args.phase === 'gated') {
+            await enqueuePending('queue');
+            return;
+        }
+        if (args.gated)
+            return;
+        args.setIssues([]);
+        await startTurnFromFields({
+            text: args.draftText,
+            files: [...args.pendingFiles],
+            voice: [...args.pendingVoice],
+        });
+    }, [args, enqueuePending, startTurnFromFields]);
+    /** The queued message's draft, or the composer's when it holds something to send. */
+    const draftToSend = useCallback(async (draftSource) => {
+        if (draftSource)
+            return draftSource.draft;
+        const draft = await encodeComposerDraft({
+            text: args.draftText,
+            pendingFiles: args.pendingFiles,
+            pendingVoice: args.pendingVoice,
+        });
+        return userDraftHasPayload(draft) ? draft : undefined;
+    }, [args]);
+    /** The sent message leaves the queue, or the composer it came from. */
+    const releaseDraft = useCallback((draftSource) => {
+        if (!draftSource) {
+            args.clearComposer();
+            return;
+        }
+        const pendingId = draftSource.id;
+        args.setPendingMessages((prev) => removeComposerPendingMessage(prev, pendingId));
+    }, [args]);
+    const handleSendNow = useCallback(async (draftSource) => {
+        if (!args.iface)
+            return;
+        const draft = await draftToSend(draftSource);
+        if (!draft)
+            return;
+        if (args.busyRef.current) {
+            args.abortRef.current?.abort();
+            await args.runPromiseRef.current;
+        }
+        args.setPendingMessages((prev) => convertSteersToFrontQueued(prev));
+        args.allowQueueDrainRef.current = false;
+        // why: Sent while the reply waits on gates, the message walks away from them in its own request.
+        await startTurnFromDraft(draft, {
+            walkAway: args.sessionRef.current.gatedTool !== null,
+            onPosted: () => releaseDraft(draftSource),
+        });
+    }, [args, draftToSend, releaseDraft, startTurnFromDraft]);
+    const handleMenuAction = useCallback((action) => {
+        if (action === 'queue' || action === 'steer' || action === 'stash') {
+            void enqueuePending(action);
+            return;
+        }
+        if (action === 'send_now')
+            void handleSendNow();
+    }, [enqueuePending, handleSendNow]);
+    return {
+        startTurnFromFields,
+        startTurnFromDraft,
+        handleStop,
+        handleSubmit,
+        handleSendNow,
+        handleMenuAction,
+        handleToolDecision,
+        handleAuthenticated,
+        resumeGatedTool,
+        handlePendingRestore,
+        enqueuePending,
+    };
+}

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

@@ -0,0 +1,66 @@
+import { type AttachmentValidationIssue, type ComposerPendingMessage, type InterfaceTurnSession, type TranscriptBlock } from '@theoremjs/agents/interface';
+import type { ClientFailure } from '../client/failure.ts';
+import type { AnsweringGate } from '../client/tool-resume.ts';
+type SetSession = (value: InterfaceTurnSession | ((prev: InterfaceTurnSession) => InterfaceTurnSession)) => void;
+export type { SetSession };
+/**
+ * How far the latest message has got: posted (`sending`), taken by the server
+ * (`sent`), reached the model (`delivered`), answered (`read`).
+ */
+export type MessageDelivery = 'sending' | 'sent' | 'delivered' | 'read';
+/** Composer / transcript / session state behind {@link useTheoremChat}. */
+export declare function useTheoremChatState(initialText?: string): {
+    blocks: TranscriptBlock[];
+    setBlocks: (value: TranscriptBlock[] | ((prev: TranscriptBlock[]) => TranscriptBlock[])) => void;
+    streamBlocks: TranscriptBlock[];
+    setStreamBlocks: import("react").Dispatch<import("react").SetStateAction<TranscriptBlock[]>>;
+    streamBlocksRef: import("react").RefObject<TranscriptBlock[]>;
+    draftText: string;
+    setDraftText: import("react").Dispatch<import("react").SetStateAction<string>>;
+    pendingFiles: File[];
+    setPendingFiles: import("react").Dispatch<import("react").SetStateAction<File[]>>;
+    pendingVoice: File[];
+    setPendingVoice: import("react").Dispatch<import("react").SetStateAction<File[]>>;
+    pendingMessages: ComposerPendingMessage[];
+    setPendingMessages: import("react").Dispatch<import("react").SetStateAction<ComposerPendingMessage[]>>;
+    issues: AttachmentValidationIssue[];
+    setIssues: import("react").Dispatch<import("react").SetStateAction<AttachmentValidationIssue[]>>;
+    failure: ClientFailure | null;
+    setFailure: import("react").Dispatch<import("react").SetStateAction<ClientFailure | null>>;
+    answering: AnsweringGate | null;
+    setAnswering: import("react").Dispatch<import("react").SetStateAction<AnsweringGate | null>>;
+    busy: boolean;
+    setBusy: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    chatStarted: boolean;
+    setChatStarted: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    streaming: boolean;
+    setStreaming: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    session: InterfaceTurnSession;
+    setSession: import("react").Dispatch<import("react").SetStateAction<InterfaceTurnSession>>;
+    delivery: {
+        status: MessageDelivery;
+    } | null;
+    setDelivery: (next: {
+        status: MessageDelivery;
+    } | null) => void;
+    deliveryRef: import("react").RefObject<{
+        status: MessageDelivery;
+    } | null>;
+    composerRef: import("react").RefObject<{
+        draftText: string;
+        pendingFiles: File[];
+        pendingVoice: File[];
+    }>;
+    blocksRef: import("react").RefObject<TranscriptBlock[]>;
+    busyRef: import("react").RefObject<boolean>;
+    abortRef: import("react").RefObject<AbortController | null>;
+    turnIdRef: import("react").RefObject<string | null>;
+    pendingRef: import("react").RefObject<ComposerPendingMessage[]>;
+    sessionRef: import("react").RefObject<InterfaceTurnSession>;
+    drainLockRef: import("react").RefObject<boolean>;
+    allowQueueDrainRef: import("react").RefObject<boolean>;
+    runPromiseRef: import("react").RefObject<Promise<void> | null>;
+    cancelPendingStreamFrame: () => void;
+    scheduleStreamBlocks: (partial: TranscriptBlock[]) => void;
+    clearComposer: () => void;
+};

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

@@ -0,0 +1,122 @@
+import { emptyInterfaceTurnSession, } from '@theoremjs/agents/interface';
+import { useCallback, useRef, useState } from 'react';
+/** 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);
+        });
+    }, [setStreamBlocks]);
+    return { cancelPendingStreamFrame, scheduleStreamBlocks };
+}
+/** Composer / transcript / session state behind {@link useTheoremChat}. */
+export function useTheoremChatState(initialText = '') {
+    const [blocks, setBlocksState] = useState([]);
+    const [streamBlocks, setStreamBlocks] = useState([]);
+    const [draftText, setDraftText] = useState(initialText);
+    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(false);
+    const [streaming, setStreaming] = useState(false);
+    const [session, setSession] = useState(emptyInterfaceTurnSession);
+    // why: One object per posted message, so a run can tell whether it posted one.
+    const [delivery, setDeliveryState] = useState(null);
+    const blocksRef = useRef(blocks);
+    // why: 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);
+    // why: A run's end reads the composer as it is then, not as it was when the run began.
+    const composerRef = useRef({ draftText, pendingFiles, pendingVoice });
+    composerRef.current = { draftText, pendingFiles, pendingVoice };
+    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,
+        composerRef,
+        blocksRef,
+        busyRef,
+        abortRef,
+        turnIdRef,
+        pendingRef,
+        sessionRef,
+        drainLockRef,
+        allowQueueDrainRef,
+        runPromiseRef,
+        cancelPendingStreamFrame,
+        scheduleStreamBlocks,
+        clearComposer,
+    };
+}

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

@@ -0,0 +1,97 @@
+import { type ComposerPendingMessage, type ComposerProfileInterface, type ComposerRunPhase, type InterfaceTurnSession, type TranscriptBlock } from '@theoremjs/agents/interface';
+import type { PageTools } from '../client/live/live-page-tool.ts';
+import type { ConversationView, TheoremTransport, TurnEventSink } from '../client/transport.ts';
+import { type MessageDelivery } from './use-theorem-chat-state.ts';
+export type UseTheoremChatOptions = {
+    transport: TheoremTransport;
+    /** Composer interface for the host profile — see `useTheoremInterface`. `null` while loading. */
+    iface: ComposerProfileInterface | null;
+    /**
+     * The ref of a conversation to resume, as `onConversationChange` reported it. Read once, when
+     * the chat mounts: the chat draws the conversation as the host keeps it. A stateless profile
+     * keeps no conversation, so it has no ref.
+     */
+    conversation?: string;
+    /**
+     * The conversation under `conversation` as the host showed it with the ref, as
+     * `startConversation` returns it. Read once, when the chat mounts: the chat draws it at once,
+     * and does not read it from the host again.
+     */
+    conversationView?: ConversationView;
+    /** The text the composer starts with. Read once, when the chat mounts. */
+    initialText?: string;
+    /**
+     * Each new ref the host issues for the conversation: once the message posts, and again as the
+     * reply's runs are saved. Keep the latest to resume the chat later.
+     */
+    onConversationChange?: (ref: string) => void;
+    /**
+     * The value chosen for each of the profile's `inputs.slots`. Sent with every turn. A slot you
+     * name here is fixed to that value; one you leave out is chosen in the composer, starting at
+     * its first allowed value.
+     */
+    slots?: Record<string, string>;
+    /** Told each time the visitor chooses a slot in the composer, with every slot's value. */
+    onSlotsChange?: (slots: Record<string, string>) => void;
+    /** What the page wants the agent to know: any JSON. The latest value goes with every turn. */
+    context?: unknown;
+    /** The page's tools, by name: each answers a tool the profile declares with `answeredBy: 'page'`. */
+    pageTools?: PageTools;
+    /**
+     * Every event of every turn, as it arrives and before the transcript takes it: the ones the
+     * transcript shows, and the ones it does not (a stage, a session, a guardrail decision).
+     */
+    onTurnEvent?: TurnEventSink;
+};
+/** 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, conversation: initialConversation, conversationView, initialText, onConversationChange, slots, onSlotsChange, context, pageTools, onTurnEvent, }: 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").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").AttachmentValidationIssue[]>>;
+    handleAuthenticated: (_index: number, secret?: string) => Promise<void>;
+    handleBranch: (index: number) => Promise<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;
+    slotChoices: {
+        declared: Record<string, string[]>;
+        values: Record<string, string>;
+        onChange: (name: string, value: string) => void;
+    } | undefined;
+    sendText: (text: string, files?: readonly File[]) => Promise<SentTurn | null>;
+};