@theoremjs/react 0.3.0 → 0.3.1

package/components/live/use-live-session-client.js

@@ -1,6 +1,6 @@
-import { useCallback, useRef } from 'react';
 import { TheoremError } from '@theoremjs/agents';
-import { applyLiveTranscript, } from "../../client/live/live-captions.js";
+import { useCallback, useRef, } from 'react';
+import { applyLiveTranscript } from "../../client/live/live-captions.js";
 import { runLiveToolCall } from "../../client/live/run-live-tool-call.js";
 import { LiveSessionClient } from "../../client/live-client.js";
 function onLiveStatusChange(next, bindings) {
@@ -23,25 +23,26 @@ function onLiveStatusChange(next, bindings) {
     bindings.setIsVideoOn(false);
 }
 function onLiveTranscript(text, isUser, meta, bindings) {
-    const next = applyLiveTranscript(bindings.captionsRef.current, text, isUser, meta?.interim);
-    bindings.captionsRef.current = next;
-    bindings.setCaptions(next);
+    // why: A thought or a tool call in the same batch is already queued; each folds onto the last.
+    bindings.setCaptions((prev) => applyLiveTranscript(prev, text, isUser, meta?.interim));
 }
 async function onLiveToolCall(name, toolArgs, meta, bindings, clientRef) {
     bindings.setActiveTool(name);
     bindings.clearFailure();
     const client = clientRef.current;
     if (!client) {
-        // lexicon-exempt: internal diagnostic; the user reads error.request
+        // labels-exempt: internal diagnostic; the user reads error.request
         bindings.reportFailure(new TheoremError('request', 'live tool call with no session client'));
         return;
     }
     try {
         await runLiveToolCall({
+            pageTools: bindings.pageTools,
             executeToolOnRelay: (call) => client.executeToolOnRelay(call),
             name,
             toolArgs,
             callId: meta.callId,
+            operationId: meta.operationId,
             sessionPermissions: bindings.sessionPermissionsRef.current,
             setSessionPermissions: (next) => {
                 bindings.sessionPermissionsRef.current = next;
@@ -69,6 +70,8 @@ export function useLiveSessionClient(bindings) {
         const b = bindingsRef.current;
         const client = new LiveSessionClient({
             ...connection,
+            slots: b.slots,
+            context: b.context,
             voiceIngress: b.voiceAvailable,
             onConnectPhase: (phase) => {
                 b.setConnectPhase(phase);
@@ -80,10 +83,10 @@ export function useLiveSessionClient(bindings) {
                 onLiveTranscript(text, isUser, meta, bindingsRef.current);
             },
             onTurnEvent: (event) => {
-                // An `unsupported` event is the host's to read; Theorem's UI shows nothing for it.
+                // why: An `unsupported` event is the host's to read; Theorem's UI shows nothing for it.
                 if (event.type === 'unsupported')
                     return;
-                // A `malformed` one was left out and the call goes on; the user reads that part was skipped.
+                // why: A `malformed` one was left out and the call goes on; the user reads that part was skipped.
                 if (event.type === 'malformed') {
                     bindingsRef.current.reportFailure(event.error);
                     return;

package/components/use-composer-voice.d.ts

@@ -1,19 +1,19 @@
-import { type LexiconOverrides } from '@theoremjs/agents';
+import { type LabelOverrides } from '@theoremjs/agents';
 import type { ProfileInputsInterface } from '@theoremjs/agents/interface';
 import { type VoiceRecorderFailureCode } from '../client/voice-recorder.ts';
 /** A voice note that could not be recorded or staged. */
 export type VoiceFailure = {
     /** A recorder failure, or `too_many_files` when the message is already full. */
     code: VoiceRecorderFailureCode | 'too_many_files';
-    /** What the user reads: the profile lexicon's `voice.<code>` (or the file-limit line). */
+    /** What the user reads: the profile labels' `voice.<code>` (or the file-limit line). */
     error: string;
     /** Raw detail for the builder; never shown to the user. */
     errorInternal?: string;
 };
 export declare function useComposerVoice(args: {
     inputs: ProfileInputsInterface;
-    /** The interface's `lexicon`: the profile's wording for voice failures. */
-    lexicon: LexiconOverrides;
+    /** The interface's `labels`: the profile's wording for voice failures. */
+    labels: LabelOverrides;
     pendingFiles: readonly File[];
     onVoiceStaged?: (file: File) => void;
     onVoiceClear?: () => void;

package/components/use-composer-voice.js

@@ -1,13 +1,13 @@
+import { attachmentIssueText, describeError, labelText, } from '@theoremjs/agents';
 import { useCallback, useRef, useState } from 'react';
-import { attachmentIssueText, describeError, lexiconText, } from '@theoremjs/agents';
 import { canStageVoice } from "../client/composer-attachments.js";
 import { ComposerVoiceRecorder, isVoiceRecorderFailure, } from "../client/voice-recorder.js";
-function voiceFailure(err, fallback, lexicon) {
+function voiceFailure(err, fallback, labels) {
     const code = isVoiceRecorderFailure(err) ? err.code : fallback;
     const internal = describeError(err);
     return {
         code,
-        error: lexiconText(`voice.${code}`, {}, lexicon),
+        error: labelText(`voice.${code}`, {}, labels),
         ...(internal && internal !== code ? { errorInternal: internal } : {}),
     };
 }
@@ -32,7 +32,7 @@ export function useComposerVoice(args) {
         if (!canStageVoice({ fileCount: args.pendingFiles.length, maxFiles })) {
             setFailure({
                 code: 'too_many_files',
-                error: attachmentIssueText({ code: 'too_many_files', params: { maxFiles } }, args.lexicon),
+                error: attachmentIssueText({ code: 'too_many_files', params: { maxFiles } }, args.labels),
             });
             return;
         }
@@ -43,9 +43,9 @@ export function useComposerVoice(args) {
         }
         catch (err) {
             setRecording(false);
-            setFailure(voiceFailure(err, 'unavailable', args.lexicon));
+            setFailure(voiceFailure(err, 'unavailable', args.labels));
         }
-    }, [args.inputs.maxFiles, args.lexicon, args.pendingFiles.length, ensureRecorder]);
+    }, [args.inputs.maxFiles, args.labels, args.pendingFiles.length, ensureRecorder]);
     const stopRecording = useCallback(async () => {
         setFailure(null);
         try {
@@ -57,9 +57,9 @@ export function useComposerVoice(args) {
         catch (err) {
             setRecording(false);
             setInputLevel(0);
-            setFailure(voiceFailure(err, 'failed', args.lexicon));
+            setFailure(voiceFailure(err, 'failed', args.labels));
         }
-    }, [args.lexicon, ensureRecorder]);
+    }, [args.labels, ensureRecorder]);
     const toggleRecording = useCallback(async () => {
         if (recording) {
             await stopRecording();

package/components/use-editor-selection.js

@@ -6,7 +6,10 @@ export function useEditorSelection(ref) {
         const read = () => {
             const root = ref.current;
             const selection = document.getSelection();
-            const inside = root && selection && selection.rangeCount > 0 && root.contains(selection.getRangeAt(0).commonAncestorContainer);
+            const inside = root &&
+                selection &&
+                selection.rangeCount > 0 &&
+                root.contains(selection.getRangeAt(0).commonAncestorContainer);
             setSelected(inside ? selection.toString() : '');
         };
         document.addEventListener('selectionchange', read);

package/components/use-voice-playback.d.ts

@@ -1,10 +1,11 @@
+import type { InkWaveLevels } from './InkWaveform.tsx';
 /**
  * Click-to-play state for a voice note: an `<audio>` ref, whether it plays,
  * and a gentle output level that drives the ink waveform while it does.
  */
 export declare function useVoicePlayback(): {
     playing: boolean;
-    outputLevel: number;
+    levelsRef: import("react").RefObject<InkWaveLevels>;
     toggle: () => Promise<void>;
     audioProps: {
         ref: import("react").RefObject<HTMLAudioElement | null>;

package/components/use-voice-playback.js

@@ -7,19 +7,19 @@ export function useVoicePlayback() {
     const audioRef = useRef(null);
     const [playing, setPlaying] = useState(false);
     const playingRef = useRef(false);
-    const [outputLevel, setOutputLevel] = useState(0);
+    const levelsRef = useRef({ input: 0, output: 0 });
     const rafIdRef = useRef(0);
     function stopMeter() {
         cancelAnimationFrame(rafIdRef.current);
         rafIdRef.current = 0;
-        setOutputLevel(0);
+        levelsRef.current.output = 0;
     }
     function startMeter() {
         stopMeter();
         const tick = (time) => {
             if (!playingRef.current)
                 return;
-            setOutputLevel(0.28 + 0.22 * (0.5 + 0.5 * Math.sin(time * 0.008)));
+            levelsRef.current.output = 0.28 + 0.22 * (0.5 + 0.5 * Math.sin(time * 0.008));
             rafIdRef.current = requestAnimationFrame(tick);
         };
         rafIdRef.current = requestAnimationFrame(tick);
@@ -64,5 +64,5 @@ export function useVoicePlayback() {
                 audioRef.current.currentTime = 0;
         },
     };
-    return { playing, outputLevel, toggle, audioProps };
+    return { playing, levelsRef, toggle, audioProps };
 }

package/hooks/use-described.d.ts

@@ -1,5 +1,9 @@
 import { type ClientFailure } from '../client/failure.ts';
-/** What a transport describes, read once per transport; a failure when it can't be read. */
+/**
+ * What a transport describes, read once per transport; a failure when it can't be read. A new
+ * transport keeps the last description up until it describes itself, so swapping one in (a
+ * recompiled profile) changes the page in place instead of blanking it to a spinner.
+ */
 export declare function useDescribed<T>(transport: {
     describe: (signal?: AbortSignal) => Promise<T>;
 }): {

package/hooks/use-described.js

@@ -1,23 +1,25 @@
 import { useEffect, useState } from 'react';
 import { clientFailure } from "../client/failure.js";
-/** What a transport describes, read once per transport; a failure when it can't be read. */
+/**
+ * What a transport describes, read once per transport; a failure when it can't be read. A new
+ * transport keeps the last description up until it describes itself, so swapping one in (a
+ * recompiled profile) changes the page in place instead of blanking it to a spinner.
+ */
 export function useDescribed(transport) {
-    const [description, setDescription] = useState(null);
+    const [description, setDescription] = useState(NOT_DESCRIBED);
     useEffect(() => {
         const controller = new AbortController();
         transport.describe(controller.signal).then((described) => {
-            if (controller.signal.aborted)
-                return;
-            setDescription({ transport, iface: described, describeFailure: null });
+            if (!controller.signal.aborted)
+                setDescription({ iface: described, describeFailure: null });
         }, (err) => {
             if (!controller.signal.aborted)
-                setDescription({ transport, iface: null, describeFailure: clientFailure(err) });
+                setDescription({ iface: null, describeFailure: clientFailure(err) });
         });
         return () => {
             controller.abort();
         };
     }, [transport]);
-    return description?.transport === transport
-        ? { iface: description.iface, describeFailure: description.describeFailure }
-        : { iface: null, describeFailure: null };
+    return description;
 }
+const NOT_DESCRIBED = { iface: null, describeFailure: null };

package/hooks/use-embedding-index.d.ts

@@ -0,0 +1,27 @@
+import type { EmbeddingInput, EmbeddingUsage } from '@theoremjs/agents';
+import type { EmbeddingInterface, EmbeddingTransport } from '../client/embedding-transport.ts';
+import { type OneCallState } from './use-one-call.ts';
+/** Documents embedded for search: each one's vector, in the order given. */
+export type EmbeddingIndex = {
+    inputs: readonly EmbeddingInput[];
+    vectors: readonly (readonly number[])[];
+    model: string;
+    usage?: EmbeddingUsage;
+    /** How many requests it took. */
+    requests: number;
+};
+/** How far an indexing has come, in requests. */
+export type IndexProgress = {
+    done: number;
+    total: number;
+};
+/**
+ * Documents embedded for search with `task: 'document'`, as many requests as
+ * the profile's limits need, one after another. A new index aborts the one
+ * still running; a request that fails stops it.
+ */
+export declare function useEmbeddingIndex(transport: EmbeddingTransport): OneCallState<'indexing', EmbeddingIndex> & {
+    progress: IndexProgress | null;
+    index: (inputs: readonly EmbeddingInput[], rules: EmbeddingInterface['inputs']) => Promise<void>;
+    cancel: () => void;
+};

package/hooks/use-embedding-index.js

@@ -0,0 +1,43 @@
+import { useState } from 'react';
+import { addUsage, embeddingBatches } from "../client/embedding-input.js";
+import { useOneCall } from "./use-one-call.js";
+async function indexWith(transport, signal, inputs, rules, onProgress) {
+    const batches = embeddingBatches(inputs, rules);
+    const vectors = [];
+    let model = '';
+    let usage;
+    onProgress({ done: 0, total: batches.length });
+    for (const [at, batch] of batches.entries()) {
+        const reply = await transport.embed(batch, { task: 'document' }, signal);
+        // why: Each request's records go to the trace as it lands, so a long index shows its calls one by one.
+        for (const record of reply.traces ?? [])
+            transport.traces?.push(record);
+        vectors.push(...reply.result.embeddings.map((vector) => vector.values));
+        model = reply.result.model;
+        usage = addUsage(usage, reply.result.usage);
+        onProgress({ done: at + 1, total: batches.length });
+    }
+    return {
+        result: {
+            inputs,
+            vectors,
+            model,
+            ...(usage ? { usage } : {}),
+            requests: batches.length,
+        },
+    };
+}
+/**
+ * Documents embedded for search with `task: 'document'`, as many requests as
+ * the profile's limits need, one after another. A new index aborts the one
+ * still running; a request that fails stops it.
+ */
+export function useEmbeddingIndex(transport) {
+    const [progress, setProgress] = useState(null);
+    const { call, ...run } = useOneCall(transport, 'indexing', indexWith);
+    return {
+        ...run,
+        progress: run.status === 'indexing' ? progress : null,
+        index: (inputs, rules) => call(inputs, rules, setProgress),
+    };
+}

package/hooks/use-one-call.d.ts

@@ -0,0 +1,31 @@
+import type { TraceRecord } from '@theoremjs/agents';
+import { type ClientFailure } from '../client/failure.ts';
+import type { TraceFeed } from '../client/trace-feed.ts';
+/** A profile that answers in one call: a decision or an embedding. */
+export type OneCallTransport = {
+    traces?: TraceFeed;
+};
+/** The last call's state: its result is kept while the next one runs and when it fails. */
+export type OneCallState<Busy extends string, Result> = {
+    status: 'idle' | Busy | 'done' | 'error';
+    result: Result | null;
+    /** How long the last call took, round trip, in milliseconds. */
+    elapsedMs: number | null;
+    /** When the call now running began, as `Date.now()`; null while none runs. */
+    startedAt: number | null;
+    failure: ClientFailure | null;
+};
+/**
+ * One call at a time to `transport`, through `send`: a new call aborts the one
+ * still running, and the last result stays on screen while the next one runs.
+ * A new transport (a recompiled profile) keeps the result and any call still
+ * running, as a chat keeps its transcript; give the component a new `key` to
+ * start over. `send` must not change between renders.
+ */
+export declare function useOneCall<T extends OneCallTransport, Busy extends string, Args extends unknown[], Result>(transport: T, busy: Busy, send: (transport: T, signal: AbortSignal, ...args: Args) => Promise<{
+    result: Result;
+    traces?: readonly TraceRecord[];
+}>): OneCallState<Busy, Result> & {
+    call: (...args: Args) => Promise<void>;
+    cancel: () => void;
+};

package/hooks/use-one-call.js

@@ -0,0 +1,76 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { failedTraces } from "../client/decision-transport.js";
+import { clientFailure } from "../client/failure.js";
+const IDLE = {
+    status: 'idle',
+    result: null,
+    elapsedMs: null,
+    startedAt: null,
+    failure: null,
+};
+/** Hands a call's trace records to the transport's feed, when it has one. */
+function feed(transport, records) {
+    for (const record of records ?? [])
+        transport.traces?.push(record);
+}
+/**
+ * One call at a time to `transport`, through `send`: a new call aborts the one
+ * still running, and the last result stays on screen while the next one runs.
+ * A new transport (a recompiled profile) keeps the result and any call still
+ * running, as a chat keeps its transcript; give the component a new `key` to
+ * start over. `send` must not change between renders.
+ */
+export function useOneCall(transport, busy, send) {
+    const [run, setRun] = useState(IDLE);
+    const running = useRef(null);
+    useEffect(() => () => running.current?.abort(), []);
+    const cancel = useCallback(() => {
+        running.current?.abort();
+        running.current = null;
+        setRun((previous) => previous.status === busy
+            ? { ...previous, status: previous.result ? 'done' : 'idle', startedAt: null }
+            : previous);
+    }, [busy]);
+    const call = useCallback(async (...args) => {
+        running.current?.abort();
+        const controller = new AbortController();
+        running.current = controller;
+        setRun((previous) => ({
+            status: busy,
+            result: previous.result,
+            elapsedMs: previous.elapsedMs,
+            startedAt: Date.now(),
+            failure: null,
+        }));
+        const started = performance.now();
+        try {
+            const reply = await send(transport, controller.signal, ...args);
+            if (controller.signal.aborted)
+                return;
+            feed(transport, reply.traces);
+            setRun({
+                status: 'done',
+                result: reply.result,
+                elapsedMs: performance.now() - started,
+                startedAt: null,
+                failure: null,
+            });
+        }
+        catch (err) {
+            if (controller.signal.aborted)
+                return;
+            feed(transport, failedTraces(err));
+            setRun((previous) => ({
+                ...previous,
+                status: 'error',
+                startedAt: null,
+                failure: clientFailure(err),
+            }));
+        }
+        finally {
+            if (running.current === controller)
+                running.current = null;
+        }
+    }, [transport, busy, send]);
+    return { ...run, call, cancel };
+}

package/hooks/use-page-tool-warnings.d.ts

@@ -0,0 +1,6 @@
+import { type PageTools } from '../client/live/live-page-tool.ts';
+/**
+ * Says in the console, once, where the page's tools and the profile's disagree. A wrong name is
+ * the builder's to fix, so it is never said to the visitor.
+ */
+export declare function usePageToolWarnings(declared: readonly string[] | undefined, pageTools: PageTools | undefined): void;

package/hooks/use-page-tool-warnings.js

@@ -0,0 +1,25 @@
+import { useEffect } from 'react';
+import { pageToolMismatch } from "../client/live/live-page-tool.js";
+/**
+ * Says in the console, once, where the page's tools and the profile's disagree. A wrong name is
+ * the builder's to fix, so it is never said to the visitor.
+ */
+export function usePageToolWarnings(declared, pageTools) {
+    const handled = Object.keys(pageTools ?? {})
+        .sort()
+        .join('\n');
+    const named = declared?.join('\n');
+    useEffect(() => {
+        if (named === undefined)
+            return;
+        const { unanswered, unused } = pageToolMismatch(named ? named.split('\n') : [], handled ? handled.split('\n') : []);
+        for (const name of unanswered) {
+            // labels-exempt: builder diagnostic
+            console.warn(`Theorem: page tool '${name}' has no handler in pageTools; the agent gets no answer.`);
+        }
+        for (const name of unused) {
+            // labels-exempt: builder diagnostic
+            console.warn(`Theorem: pageTools has '${name}', which the profile does not declare answeredBy: 'page'.`);
+        }
+    }, [named, handled]);
+}

package/hooks/use-second-ticker.d.ts

@@ -0,0 +1,2 @@
+/** `Date.now()`, refreshed every second while `active`. */
+export declare function useSecondTicker(active: boolean): number;

package/hooks/use-second-ticker.js

@@ -0,0 +1,13 @@
+import { useEffect, useState } from 'react';
+/** `Date.now()`, refreshed every second while `active`. */
+export function useSecondTicker(active) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        if (!active)
+            return;
+        setNow(Date.now());
+        const timer = globalThis.setInterval(() => setNow(Date.now()), 1_000);
+        return () => globalThis.clearInterval(timer);
+    }, [active]);
+    return now;
+}

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

@@ -1,22 +1,15 @@
-import { type MutableRefObject } from 'react';
 import type { AttachmentValidationIssue, ComposerMenuAction, ComposerPendingMessage, ComposerProfileInterface, ComposerRunPhase, InterfaceTurnSession, TranscriptBlock } from '@theoremjs/agents/interface';
-import { type AnsweringGate, type StreamView, type ToolDecisionAction } from '../client/index.ts';
-import { type ClientFailure, type TurnFailure } from '../client/failure.ts';
+import { type MutableRefObject } from 'react';
+import { type ClientFailure } from '../client/failure.ts';
+import { type AnsweringGate, type StreamView, type ToolDecisionAction, type ToolGateResolution } from '../client/index.ts';
+import type { RunOutcome } from '../client/run-session.ts';
 import type { TheoremTransport } from '../client/transport.ts';
 import type { MessageDelivery } from './use-theorem-chat-state.ts';
-export type RunTurnStream = (run: (view: StreamView, 
-/** The work so far of the reply the session waits on (none when it waits on nothing). */
-paused: {
-    workedMs: number;
-}) => Promise<{
-    ok: true;
-    session: InterfaceTurnSession;
-    userBlocks?: TranscriptBlock[];
-    assistantBlocks: TranscriptBlock[];
-} | TurnFailure>, options?: {
-    userBlocksAlreadyApplied?: boolean;
-    /** The run's message walks away from the gates the reply waits on, ending that reply. */
-    walksAway?: boolean;
+export type RunTurnStream = (run: (view: StreamView) => Promise<RunOutcome>, options?: {
+    /** The run sends a message: one that never posts goes back in the composer with its failure. */
+    message?: {
+        restore(): Promise<void>;
+    };
 }) => Promise<void>;
 export type TheoremChatActionArgs = {
     iface: ComposerProfileInterface | null;
@@ -26,6 +19,14 @@ export type TheoremChatActionArgs = {
     draftText: string;
     pendingFiles: File[];
     pendingVoice: File[];
+    /** The composer as it is now, for a run that ends after it changed. */
+    composerRef: MutableRefObject<{
+        draftText: string;
+        pendingFiles: File[];
+        pendingVoice: File[];
+    }>;
+    /** The ref of the conversation the chat continues; none before its first message posts. */
+    conversationRef: MutableRefObject<string | undefined>;
     clearComposer: () => void;
     runTurnStream: RunTurnStream;
     sessionRef: MutableRefObject<InterfaceTurnSession>;
@@ -52,12 +53,13 @@ export type TheoremChatActionArgs = {
     } | null) => void;
     pendingRef: MutableRefObject<ComposerPendingMessage[]>;
 };
+type ComposerFields = {
+    text: string;
+    files: File[];
+    voice: File[];
+};
 export declare function useTheoremChatActions(args: TheoremChatActionArgs): {
-    startTurnFromFields: (fields: {
-        text: string;
-        files: File[];
-        voice: File[];
-    }) => Promise<void>;
+    startTurnFromFields: (fields: ComposerFields) => Promise<void>;
     startTurnFromDraft: (draft: ComposerPendingMessage["draft"], options?: {
         /** Send while the reply waits on gates: the message walks away from them. */
         walkAway?: boolean;
@@ -70,6 +72,8 @@ export declare function useTheoremChatActions(args: TheoremChatActionArgs): {
     handleMenuAction: (action: ComposerMenuAction) => void;
     handleToolDecision: (_index: number, action: ToolDecisionAction) => Promise<void>;
     handleAuthenticated: (_index: number, secret?: string) => Promise<void>;
+    resumeGatedTool: (resolution: ToolGateResolution) => Promise<void>;
     handlePendingRestore: (id: string) => Promise<void>;
     enqueuePending: (kind: "queue" | "steer" | "stash") => Promise<void>;
 };
+export {};