@theoremjs/react 0.3.0 → 0.3.1

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

@@ -1,8 +1,9 @@
-import { useCallback } from 'react';
 import { TheoremError } from '@theoremjs/agents';
 import { convertSteersToFrontQueued, createComposerPendingMessage, orderComposerPendingMessages, removeComposerPendingMessage, userDraftHasPayload, userDraftToSteerInject, } from '@theoremjs/agents/interface';
-import { composerFieldsFromDraft, encodeComposerDraft, resumeInterfaceTool, streamInterfaceDraftTurn, streamInterfaceTurn, } from "../client/index.js";
+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,
@@ -33,8 +34,30 @@ function beginAbortableTurn(args) {
         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) {
+function useTurnStarters(args, restoreToComposer) {
     const startTurnFromFields = useCallback(async (fields) => {
         const started = beginAbortableTurn(args);
         if (!started)
@@ -47,8 +70,9 @@ function useTurnStarters(args) {
             pendingFiles: fields.files,
             pendingVoice: fields.voice,
             signal: started.signal,
-            turnId: started.turnId,
+            scope: scopeOf(args, started.turnId),
             view,
+            transcript: args.blocksRef.current,
             onUserBlocks: (userBlocks) => {
                 args.setBlocks((prev) => [...prev, ...userBlocks]);
                 args.setDelivery({ status: 'sending' });
@@ -56,43 +80,43 @@ function useTurnStarters(args) {
                 args.setStreaming(true);
                 args.clearComposer();
             },
-        }), { userBlocksAlreadyApplied: true });
-    }, [args]);
+        }), { message: { restore: () => restoreToComposer(fields) } });
+    }, [args, restoreToComposer]);
     const startTurnFromDraft = useCallback(async (draft, options = {}) => {
         const started = beginAbortableTurn(args);
         if (!started)
             return;
-        await args.runTurnStream((view, paused) => streamInterfaceDraftTurn({
+        await args.runTurnStream((view) => streamInterfaceDraftTurn({
             iface: started.composer,
             transport: args.transport,
             session: args.sessionRef.current,
             draft,
             signal: started.signal,
-            turnId: started.turnId,
+            scope: scopeOf(args, started.turnId),
             view,
-            ...(options.walkAway ? { walkAway: paused } : {}),
+            transcript: args.blocksRef.current,
+            walkAway: options.walkAway === true,
             onUserBlocks: (posted) => {
                 args.setBlocks((prev) => [...prev, ...posted]);
-                // A walked-away reply's blocks were streaming; they are posted now.
                 args.setStreamBlocks([]);
                 args.setDelivery({ status: 'sending' });
                 args.setChatStarted(true);
                 args.setStreaming(true);
                 options.onPosted?.();
             },
-        }), { userBlocksAlreadyApplied: true, walksAway: options.walkAway === true });
-    }, [args]);
+        }), { 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(
-    // lexicon-exempt: internal diagnostic; the user reads session.turn_ended
-    new TheoremError('request', 'steer: no active turn', { copy: { key: 'session.turn_ended' } }), args.iface?.lexicon));
+    // 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) {
+function usePendingActions(args, restoreToComposer) {
     const enqueuePending = useCallback(async (kind) => {
         if (!userDraftHasPayload(composerFieldsPayload(args.draftText, args.pendingFiles, args.pendingVoice))) {
             return;
@@ -120,36 +144,21 @@ function usePendingActions(args) {
             await args.transport.steer({ turnId, id: message.id, inject });
         }
         catch (err) {
-            args.setFailure(clientFailure(err, args.iface?.lexicon));
+            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;
-        const currentDraft = composerFieldsPayload(args.draftText, args.pendingFiles, args.pendingVoice);
         try {
-            let nextPending = removeComposerPendingMessage(args.pendingRef.current, id);
-            if (userDraftHasPayload(currentDraft)) {
-                const stashDraft = await encodeComposerDraft({
-                    text: args.draftText,
-                    pendingFiles: args.pendingFiles,
-                    pendingVoice: args.pendingVoice,
-                });
-                const stash = createComposerPendingMessage({ kind: 'stash', draft: stashDraft });
-                nextPending = orderComposerPendingMessages([...nextPending, stash]);
-            }
-            const restored = composerFieldsFromDraft(message.draft);
-            args.setPendingMessages(nextPending);
-            args.setDraftText(restored.text);
-            args.setPendingFiles(restored.files);
-            args.setPendingVoice(restored.voice);
-            args.setIssues([]);
+            await restoreToComposer(composerFieldsFromDraft(message.draft));
+            args.setPendingMessages((prev) => removeComposerPendingMessage(prev, id));
         }
         catch (err) {
-            args.setFailure(clientFailure(err, args.iface?.lexicon));
+            args.setFailure(clientFailure(err, args.iface?.labels));
         }
-    }, [args]);
+    }, [args, restoreToComposer]);
     return { enqueuePending, handlePendingRestore };
 }
 /** Answer the gate the session waits on: a decision, or a sign-in. */
@@ -158,15 +167,27 @@ function useGateActions(args) {
         const composer = args.iface;
         if (!composer)
             return;
-        // Set once the run starts (not while another runs), and cleared once it has ended.
+        // 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;
-                if (session.gatedTool)
-                    args.setAnswering({ callId: session.gatedTool.callId, action: resolution.action });
-                return resumeInterfaceTool({ iface: composer, transport: args.transport, session, resolution, view });
+                // 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 {
@@ -180,12 +201,13 @@ function useGateActions(args) {
     const handleAuthenticated = useCallback(async (_index, secret) => {
         await resumeGatedTool({ action: 'auth', ...(secret === undefined ? {} : { secret }) });
     }, [resumeGatedTool]);
-    return { handleToolDecision, handleAuthenticated };
+    return { handleToolDecision, handleAuthenticated, resumeGatedTool };
 }
 export function useTheoremChatActions(args) {
-    const { startTurnFromFields, startTurnFromDraft } = useTurnStarters(args);
-    const { enqueuePending, handlePendingRestore } = usePendingActions(args);
-    const { handleToolDecision, handleAuthenticated } = useGateActions(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]);
@@ -235,10 +257,9 @@ export function useTheoremChatActions(args) {
         }
         args.setPendingMessages((prev) => convertSteersToFrontQueued(prev));
         args.allowQueueDrainRef.current = false;
-        // Sent while the reply waits on gates, the message walks away from them in its own request.
+        // 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,
-            // The message leaves the composer (or the queue) once it posts.
             onPosted: () => releaseDraft(draftSource),
         });
     }, [args, draftToSend, releaseDraft, startTurnFromDraft]);
@@ -259,6 +280,7 @@ export function useTheoremChatActions(args) {
         handleMenuAction,
         handleToolDecision,
         handleAuthenticated,
+        resumeGatedTool,
         handlePendingRestore,
         enqueuePending,
     };

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

@@ -8,13 +8,8 @@ export type { SetSession };
  * (`sent`), reached the model (`delivered`), answered (`read`).
  */
 export type MessageDelivery = 'sending' | 'sent' | 'delivered' | 'read';
-/** A conversation at rest: what the transcript shows and what the next turn is sent with. */
-export type ChatSnapshot = {
-    blocks: TranscriptBlock[];
-    session: InterfaceTurnSession;
-};
 /** Composer / transcript / session state behind {@link useTheoremChat}. */
-export declare function useTheoremChatState(initial?: ChatSnapshot): {
+export declare function useTheoremChatState(initialText?: string): {
     blocks: TranscriptBlock[];
     setBlocks: (value: TranscriptBlock[] | ((prev: TranscriptBlock[]) => TranscriptBlock[])) => void;
     streamBlocks: TranscriptBlock[];
@@ -51,6 +46,11 @@ export declare function useTheoremChatState(initial?: ChatSnapshot): {
     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>;

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

@@ -1,5 +1,5 @@
-import { useCallback, useRef, useState } from 'react';
 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);
@@ -22,14 +22,14 @@ function useStreamFrames(setStreamBlocks) {
             if (next)
                 setStreamBlocks(next);
         });
-    }, []);
+    }, [setStreamBlocks]);
     return { cancelPendingStreamFrame, scheduleStreamBlocks };
 }
 /** Composer / transcript / session state behind {@link useTheoremChat}. */
-export function useTheoremChatState(initial) {
-    const [blocks, setBlocksState] = useState(initial?.blocks ?? []);
+export function useTheoremChatState(initialText = '') {
+    const [blocks, setBlocksState] = useState([]);
     const [streamBlocks, setStreamBlocks] = useState([]);
-    const [draftText, setDraftText] = useState('');
+    const [draftText, setDraftText] = useState(initialText);
     const [pendingFiles, setPendingFiles] = useState([]);
     const [pendingVoice, setPendingVoice] = useState([]);
     const [pendingMessages, setPendingMessages] = useState([]);
@@ -37,13 +37,13 @@ export function useTheoremChatState(initial) {
     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 [chatStarted, setChatStarted] = useState(false);
     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 [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);
-    // Set as it is written, so a caller awaiting a turn reads the transcript the turn left.
+    // 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);
@@ -61,6 +61,9 @@ export function useTheoremChatState(initial) {
     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);
@@ -102,6 +105,7 @@ export function useTheoremChatState(initial) {
         delivery,
         setDelivery,
         deliveryRef,
+        composerRef,
         blocksRef,
         busyRef,
         abortRef,

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

@@ -1,20 +1,49 @@
 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 };
+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;
-    /** 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.
+     * 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.
      */
-    onChange?: (snapshot: ChatSnapshot) => void;
+    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. */
+/** What `sendText` hands back: the blocks the turn added, its user message, and the reply. */
 export type SentTurn = {
     blocks: TranscriptBlock[];
 };
@@ -23,7 +52,7 @@ export type SentTurn = {
  * queue / steer / stash, tool gates. Render it with `@theoremjs/react/ui` or
  * your own components.
  */
-export declare function useTheoremChat({ transport, iface, initial, onChange }: UseTheoremChatOptions): {
+export declare function useTheoremChat({ transport, iface, conversation: initialConversation, conversationView, initialText, onConversationChange, slots, onSlotsChange, context, pageTools, onTurnEvent, }: UseTheoremChatOptions): {
     iface: ComposerProfileInterface | null;
     blocks: TranscriptBlock[];
     chatStarted: boolean;
@@ -31,7 +60,7 @@ export declare function useTheoremChat({ transport, iface, initial, onChange }:
     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[];
+    issues: import("@theoremjs/agents").AttachmentValidationIssue[];
     pendingFiles: File[];
     pendingMessages: ComposerPendingMessage[];
     pendingVoice: File[];
@@ -45,9 +74,9 @@ export declare function useTheoremChat({ transport, iface, initial, onChange }:
     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[]>>;
+    setIssues: import("react").Dispatch<import("react").SetStateAction<import("@theoremjs/agents").AttachmentValidationIssue[]>>;
     handleAuthenticated: (_index: number, secret?: string) => Promise<void>;
-    handleBranch: (index: number) => void;
+    handleBranch: (index: number) => Promise<void>;
     handleSubmit: () => Promise<void>;
     handleStop: () => void;
     handleMenuAction: (action: import("@theoremjs/agents/interface").ComposerMenuAction) => void;
@@ -59,5 +88,10 @@ export declare function useTheoremChat({ transport, iface, initial, onChange }:
         modelId: string;
         effort?: string;
     }) => void;
-    sendText: (text: string) => Promise<SentTurn | null>;
+    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>;
 };