@theoremjs/react 0.3.4-next.649.gf83cea1 → 0.3.4-next.671.gfa09ab2

package/README.md

@@ -203,8 +203,8 @@ A profile whose `providerContinuation.history` is `'stateless'` keeps no convers
 
 ### Send a message from your code
 
-`chatRef` gives you `send(text, files?)`. It sends the text and optional array of browser files as the user. Files use the same profile validation and encoding as composer attachments. When the reply is complete, it returns the blocks that the turn added. It returns `null` if the chat cannot accept a message now. This happens while a reply streams or waits for a gate.
-`chatRef` also gives you `stop()`. It stops the reply that streams, as the composer's stop button does. And it gives you `focus()`, which puts the keyboard in the composer, for example after your own control clears the chat.
+`chatRef` gives you `send(text, options?)`. It sends the text as the user. `options` can add `files` and `voice`, arrays of browser files, which use the same profile validation and encoding as composer attachments. It can also name a `model` and its `effort` for the turn. The model becomes the chat's pick, as if chosen in the composer. A model or file the profile does not take is refused, as the composer refuses it, and the refusal shows in the chat. When the reply is complete, it returns the blocks that the turn added. It returns `null` if the chat cannot accept a message now. This happens while a reply streams or waits for a gate.
+`chatRef` also gives you `stop()`. It stops the reply that streams, as the composer's stop button does. It gives you `focus()`, which puts the keyboard in the composer, for example after your own control clears the chat. And it gives you `controller`, the chat's `ChatController`, for a host that drives the chat from outside, as a composer shared by several chats does.
 
 ```tsx
 const chat = useRef<TheoremChatHandle>(null);

package/components/live/use-live-session-client.d.ts

@@ -1,4 +1,4 @@
-import { type SessionEventOf, type TurnEvent } from '@theoremjs/agents';
+import type { SessionEventOf, TurnEvent } from '@theoremjs/agents';
 import type { LiveCallOptions, LiveConnectPhase, LiveGateAnswer, LiveSessionStatus, LiveToolGatePrompt, TraceFeed } from '@theoremjs/web/client';
 import { type LiveConnection, LiveSessionClient } from '@theoremjs/web/client';
 import { type Dispatch, type MutableRefObject, type SetStateAction } from 'react';

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

@@ -1,8 +1,6 @@
-import { TheoremError } from '@theoremjs/agents';
-import { LiveSessionClient } from '@theoremjs/web/client';
+import { continueGatedToolInvocation, LiveSessionClient, } from '@theoremjs/web/client';
 import { useCallback, useRef, } from 'react';
 import { applyLiveTranscript } from "../../client/live/live-captions.js";
-import { runLiveToolCall } from "../../client/live/run-live-tool-call.js";
 function onLiveStatusChange(next, bindings) {
     bindings.setStatus(next);
     if (next === 'listening' || next === 'ready') {
@@ -26,38 +24,22 @@ function onLiveTranscript(text, isUser, meta, bindings) {
     // 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) {
-        // 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;
-                bindings.setSessionPermissions(next);
-            },
-            waitForGateDecision: bindings.waitForGateDecision,
-        });
-    }
-    catch (err) {
-        bindings.reportFailure(err);
-    }
-    finally {
-        if (!bindings.gatePromptRef.current)
-            bindings.setActiveTool(null);
+/** The user's answer to a gate, as the session takes it; an approval records the permissions it grants. */
+async function onLiveGate(prompt, bindings) {
+    const resolution = await bindings.waitForGateDecision(prompt);
+    if (resolution === 'withdrawn')
+        return 'withdrawn';
+    const reply = continueGatedToolInvocation({
+        toolName: prompt.toolName,
+        gate: prompt.gate,
+        sessionPermissions: bindings.sessionPermissionsRef.current,
+        resolution,
+    });
+    if (reply.decision === 'approve') {
+        bindings.sessionPermissionsRef.current = reply.sessionPermissions;
+        bindings.setSessionPermissions(reply.sessionPermissions);
     }
+    return reply;
 }
 /** Owns LiveSessionClient construction + reconnect identity. */
 export function useLiveSessionClient(bindings) {
@@ -91,6 +73,9 @@ export function useLiveSessionClient(bindings) {
                     bindingsRef.current.reportFailure(event.error);
                     return;
                 }
+                // why: A new call from the model clears the last failure.
+                if (event.type === 'tool' && event.tool.phase === undefined)
+                    bindingsRef.current.clearFailure();
                 bindingsRef.current.handleLiveTurnEvent(event);
             },
             onTrace: (record) => {
@@ -111,7 +96,11 @@ export function useLiveSessionClient(bindings) {
             onSessionEnded: (session) => {
                 bindingsRef.current.reportSessionEnded(session);
             },
-            onToolCall: (name, args, meta) => onLiveToolCall(name, args, meta, bindingsRef.current, clientRef),
+            // why: Read at each call, so a handler the host renders anew is the one that answers.
+            get pageTools() {
+                return bindingsRef.current.pageTools;
+            },
+            onGate: (prompt) => onLiveGate(prompt, bindingsRef.current),
         });
         clientRef.current = client;
         return client;

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

@@ -1,5 +1,5 @@
-import { type ChatOptions, type SentTurn, type ToolDecisionAction } from '@theoremjs/web/client';
-export type { SentTurn };
+import { type ChatOptions, type SendTextOptions, type SentTurn, type ToolDecisionAction } from '@theoremjs/web/client';
+export type { SendTextOptions, SentTurn };
 export type UseTheoremChatOptions = ChatOptions;
 /**
  * Headless chat model: transcript, streaming, composer drafts, pending
@@ -32,7 +32,9 @@ export declare function useTheoremChat(options: UseTheoremChatOptions): {
         modelId: string;
         effort?: string;
     }) => void;
-    sendText: (text: string, files?: readonly File[]) => Promise<SentTurn | null>;
+    sendText: (text: string, options?: SendTextOptions) => Promise<SentTurn | null>;
+    /** The controller under it all, for a host that drives the chat from outside. */
+    controller: import("@theoremjs/web/client").ChatController;
     iface: import("../../../src/interface/types").ComposerProfileInterface | null;
     blocks: import("../../../src/interface/types").TranscriptBlock[];
     streamBlocks: import("../../../src/interface/types").TranscriptBlock[];

package/hooks/use-theorem-chat.js

@@ -36,5 +36,7 @@ export function useTheoremChat(options) {
         handleToolDecision,
         handleGenerationChange: chat.setGeneration,
         sendText: chat.sendText,
+        /** The controller under it all, for a host that drives the chat from outside. */
+        controller: chat,
     };
 }

package/index.d.ts

@@ -9,7 +9,7 @@
  */
 export * from '@theoremjs/web/client';
 export { type EmbeddingIndex, type IndexProgress, useEmbeddingIndex, } from './hooks/use-embedding-index.ts';
-export { type SentTurn, type UseTheoremChatOptions, useTheoremChat, } from './hooks/use-theorem-chat.ts';
+export { type SendTextOptions, type SentTurn, type UseTheoremChatOptions, useTheoremChat, } from './hooks/use-theorem-chat.ts';
 export { type TheoremDecisionState, useTheoremDecision } from './hooks/use-theorem-decision.ts';
 export { type TheoremEmbeddingState, useTheoremEmbedding, } from './hooks/use-theorem-embedding.ts';
 export { type TheoremHostCall, type TheoremHostState, useTheoremHost, } from './hooks/use-theorem-host.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.3.4-next.649.gf83cea1",
+  "version": "0.3.4-next.671.gfa09ab2",
   "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
   "license": "MIT",
   "type": "module",
@@ -60,8 +60,8 @@
     "@stylexjs/stylex": "0.19.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@theoremjs/agents": "^0.3.4-next.649.gf83cea1",
-    "@theoremjs/web": "^0.3.4-next.649.gf83cea1"
+    "@theoremjs/agents": "^0.3.4-next.671.gfa09ab2",
+    "@theoremjs/web": "^0.3.4-next.671.gfa09ab2"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {

package/ui/TheoremChat.d.ts

@@ -1,9 +1,9 @@
 import type { DefinedTheme } from '@astryxdesign/core/theme';
 import { type ComposerPendingMessage } from '@theoremjs/agents/interface';
-import type { PageTools } from '@theoremjs/web/client';
+import type { ChatController, PageTools } from '@theoremjs/web/client';
 import { type ConversationView, type HttpTransportOptions, type TheoremTransport } from '@theoremjs/web/client';
 import { type ReactNode, type Ref } from 'react';
-import { type SentTurn, type UseTheoremChatOptions } from '../hooks/use-theorem-chat.ts';
+import { type SendTextOptions, type SentTurn, type UseTheoremChatOptions } from '../hooks/use-theorem-chat.ts';
 import type { TheoremLabels } from './labels.ts';
 export type TheoremChatProps = {
     /** Where `createTheoremHandler` is mounted. Default `/api/theorem`. Ignored when `transport` is set. */
@@ -112,14 +112,19 @@ export type TheoremChatProps = {
 /** What a host can do to a mounted {@link TheoremChat}. */
 export type TheoremChatHandle = {
     /**
-     * Sends `text` and optional `files` as the user, and resolves with the blocks the turn added once the reply is done;
+     * Sends `text`, and what `options` adds, as the user, and resolves with the blocks the turn added once the reply is done;
      * `null` when the chat can't take a message now (a reply is streaming, or waits on a gate).
      */
-    send: (text: string, files?: readonly File[]) => Promise<SentTurn | null>;
+    send: (text: string, options?: SendTextOptions) => Promise<SentTurn | null>;
     /** Stops the reply that is streaming, as the composer's stop button does. */
     stop: () => void;
     /** Puts the keyboard in the composer. */
     focus: () => void;
+    /**
+     * The chat's controller, for a host that drives it from outside, as a composer shared by
+     * several chats does. See `createChatController` in `@theoremjs/web/client`.
+     */
+    controller: ChatController;
 };
 /**
  * 50% of the chat's width, but never narrower than 640px (or the full width,

package/ui/TheoremChat.js

@@ -69,7 +69,7 @@ function ChatBody({ transport, iface, placeholder, emptyState, density, maxWidth
         pageTools,
         onTurnEvent,
     });
-    const { sendText, handleStop } = chat;
+    const { sendText, handleStop, controller } = chat;
     const blocks = useMemo(() => [...chat.blocks, ...chat.streamBlocks], [chat.blocks, chat.streamBlocks]);
     const handle = t('@theorem.agent.handle', { handle: iface.identity.handle });
     const landing = blocks.length === 0;
@@ -80,7 +80,8 @@ function ChatBody({ transport, iface, placeholder, emptyState, density, maxWidth
         focus: () => {
             inputRef.current?.focus();
         },
-    }), [sendText, handleStop]);
+        controller,
+    }), [sendText, handleStop, controller]);
     const composerRef = useGlide(landing, () => inputRef.current?.focus());
     const inspector = useTraceInspector(iface, transport.traces, trace);
     const header = _jsx(SidePanelHeader, { floating: true, children: inspector.toggle });

package/client/live/run-live-tool-call.d.ts

@@ -1,20 +0,0 @@
-import type { ExecuteToolOnRelay, LiveGateAnswer, LiveToolGatePrompt, PageTools } from '@theoremjs/web/client';
-/**
- * Live provider tool-call handler: the page answers the call if it is the
- * page's; else run the model's call on the relay; at a gate, ask the user and
- * send their decision. The session answers the model
- * however the call ends; its tool events tell the user. A call the model
- * cancels while its gate is open is gone: nothing is sent.
- */
-export declare function runLiveToolCall(args: {
-    executeToolOnRelay: ExecuteToolOnRelay;
-    /** The host's page tools, if it has any. */
-    pageTools?: PageTools;
-    name: string;
-    toolArgs: Record<string, unknown>;
-    callId: string;
-    operationId: string;
-    sessionPermissions: string[];
-    setSessionPermissions: (next: string[]) => void;
-    waitForGateDecision: (prompt: LiveToolGatePrompt) => Promise<LiveGateAnswer>;
-}): Promise<void>;

package/client/live/run-live-tool-call.js

@@ -1,70 +0,0 @@
-import { continueGatedToolInvocation } from '@theoremjs/web/client';
-/**
- * Live provider tool-call handler: the page answers the call if it is the
- * page's; else run the model's call on the relay; at a gate, ask the user and
- * send their decision. The session answers the model
- * however the call ends; its tool events tell the user. A call the model
- * cancels while its gate is open is gone: nothing is sent.
- */
-export async function runLiveToolCall(args) {
-    const { executeToolOnRelay, name, toolArgs, callId, operationId } = args;
-    let sessionPermissions = args.sessionPermissions;
-    // why: A name from the model is looked up among the host's own keys only.
-    const pageTool = args.pageTools && Object.hasOwn(args.pageTools, name) ? args.pageTools[name] : undefined;
-    let step = await executeToolOnRelay({ callId, operationId });
-    const dispatched = new Set();
-    while (step.status !== 'settled') {
-        if (step.status === 'dispatched') {
-            if (dispatched.has(step.grantId))
-                return;
-            dispatched.add(step.grantId);
-            const grantId = step.grantId;
-            const input = step.arguments;
-            const answer = pageTool
-                ? await Promise.resolve()
-                    .then(() => pageTool(input, { callId, operationId }))
-                    .catch(() => undefined)
-                : undefined;
-            step = await executeToolOnRelay({
-                callId,
-                operationId,
-                grantId,
-                ...(answer ? { output: answer.output } : { unanswered: true }),
-            });
-            continue;
-        }
-        const { gate } = step;
-        if (gate.kind === 'page') {
-            await executeToolOnRelay({ callId, operationId, decision: 'deny' });
-            return;
-        }
-        const resolution = await args.waitForGateDecision({
-            callId,
-            toolName: name,
-            input: gate.preparedArguments ?? toolArgs,
-            gate,
-        });
-        if (resolution === 'withdrawn')
-            return;
-        const reply = continueGatedToolInvocation({
-            toolName: name,
-            gate,
-            sessionPermissions,
-            resolution,
-        });
-        if (reply.decision === 'deny') {
-            // why: The session settles the refusal; its tool event tells the user.
-            await executeToolOnRelay({ callId, operationId, decision: 'deny' });
-            return;
-        }
-        sessionPermissions = reply.sessionPermissions;
-        args.setSessionPermissions(reply.sessionPermissions);
-        // why: Signed in: a typed key goes once, with the approval; after an OAuth callback there is none.
-        step = await executeToolOnRelay({
-            callId,
-            decision: 'approve',
-            operationId,
-            ...(reply.secret !== undefined ? { secret: reply.secret } : {}),
-        });
-    }
-}