@datalayer/agent-runtimes 1.5.20 → 1.5.22

package/lib/portable/sessions.js

@@ -0,0 +1,134 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { readRunStream } from './agui';
+import { agUiRefusal, refusalBody } from './agUiRefusal';
+import { messagesOfThread } from './thread';
+/** A route that refused: its status and the runtime's sentence. */
+export class RuntimeRefusal extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'RuntimeRefusal';
+    }
+}
+function clientOf({ baseUrl, getAccessToken, fetch: fetcher, }) {
+    const root = baseUrl.replace(/\/+$/, '');
+    const headers = (extra = {}) => {
+        const token = getAccessToken();
+        return {
+            ...extra,
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        };
+    };
+    const refused = async (response) => {
+        throw new RuntimeRefusal(response.status, agUiRefusal(response.status, response.statusText, await refusalBody(response)));
+    };
+    const json = async (path, method = 'GET') => {
+        const response = await fetcher(`${root}${path}`, {
+            method,
+            headers: headers({ Accept: 'application/json' }),
+        });
+        if (!response.ok) {
+            return refused(response);
+        }
+        return (await response.json());
+    };
+    const stream = async (path, body, { onEvent, signal }, method = 'POST') => {
+        const response = await fetcher(`${root}${path}`, {
+            method,
+            headers: headers({
+                'Content-Type': 'application/json',
+                Accept: 'text/event-stream',
+            }),
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!response.ok) {
+            return refused(response);
+        }
+        await readRunStream(response, onEvent);
+    };
+    return { json, stream, refused, headers, root, fetcher };
+}
+const at = (uid) => `/api/v1/apps/sessions/${encodeURIComponent(uid)}`;
+/**
+ * An application's sessions on the runtime that runs it: start, message,
+ * settings, resume (streamed), and stop, end, read (JSON).
+ */
+export function appSessionsClient(options) {
+    const { json, stream } = clientOf(options);
+    return {
+        /** Start a session with its first message. */
+        start: (start, streaming) => stream('/api/v1/apps/sessions', {
+            agent: start.agent,
+            ...(start.deploymentUid
+                ? { deployment_uid: start.deploymentUid }
+                : {}),
+            ...(start.appUid ? { app_uid: start.appUid } : {}),
+            ...(start.version ? { version: start.version } : {}),
+            ...(start.session ? { session: start.session } : {}),
+            opener: start.opener,
+        }, streaming),
+        /** The next turn, or the answer to what the application asked (text, a choice). */
+        message: (uid, text, streaming) => stream(`${at(uid)}/messages`, { text }, streaming),
+        /** A settings change: also what answers a form the application asked. */
+        changeSettings: (uid, values, streaming) => stream(`${at(uid)}/settings`, { values }, streaming, 'PUT'),
+        /** Resume a stopped session — or, with its agent, one the runtime no longer holds, from its record. */
+        resume: (uid, agent, streaming) => stream(`${at(uid)}/resume`, { agent }, streaming),
+        /** Stop: what runs is cancelled; the session waits to be resumed. */
+        stop: (uid) => json(`${at(uid)}/stop`, 'POST'),
+        /** End the conversation for good; its record stays. */
+        end: (uid) => json(`${at(uid)}/end`, 'POST'),
+        /** What the session is: its state (`open`, `running`, `waiting`, `stopped`) and what it asks. */
+        describe: (uid) => json(at(uid)),
+        /** Its conversation as a person reads it (`messagesOfThread`). */
+        messages: async (uid) => messagesOfThread((await json(`${at(uid)}/messages`)).messages),
+    };
+}
+/**
+ * A standalone agent over its AG-UI mount: a run carries the conversation so
+ * far, and stopping it terminates the thread's run on the runtime. A raw
+ * agent has no session, record or question of an application's.
+ */
+export function agentRunClient(options) {
+    const { stream, refused, root, headers, fetcher } = clientOf(options);
+    return {
+        run: (threadId, runId, messages, streaming) => stream(`/api/v1/ag-ui/${encodeURIComponent(options.agent)}/`, {
+            threadId,
+            runId,
+            messages,
+            state: null,
+            tools: [],
+            context: [],
+            forwardedProps: null,
+        }, streaming),
+        /** Stop the thread's run on the runtime (`POST /api/v1/ag-ui/terminate`). */
+        terminate: async (threadId) => {
+            const response = await fetcher(`${root}/api/v1/ag-ui/terminate`, {
+                method: 'POST',
+                headers: headers({ 'Content-Type': 'application/json' }),
+                body: JSON.stringify({ thread_id: threadId }),
+            });
+            if (!response.ok) {
+                await refused(response);
+            }
+        },
+    };
+}
+/**
+ * A runtime's agent-runtimes address from its ingress, as the runtimes
+ * service gives it (`…/jupyter/server/<runtime>` → `…/agent-runtimes/<runtime>`,
+ * `build_agent_runtimes_base_url`). Refused when there is none.
+ */
+export function agentRuntimesUrlOf(ingress) {
+    const base = ingress.trim().replace(/\/+$/, '');
+    if (!/^https?:\/\//.test(base)) {
+        throw new Error(`The runtime gave no address to reach its agents: ${ingress || 'none'}.`);
+    }
+    return base.includes('/jupyter/server/')
+        ? base.replace('/jupyter/server/', '/agent-runtimes/')
+        : base;
+}

package/lib/portable/thread.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A person's conversation with an application, read again: the person-facing
+ * projection of a session's thread, and the thread opened from the runtime
+ * that holds it — or resumed from its record (LOOP P-24, D-13, R-04).
+ *
+ * The web chat (`ChatView`, an embed after its page reloads) and Datalayer
+ * Mobile open a thread with these, so that what a person reads of their own
+ * conversation is the same on each. Pure: the network is the `fetch` given.
+ *
+ * @module portable/thread
+ */
+import type { ChatMessage } from '../types/messages';
+/** What opening a thread says, in a person's words. */
+export declare const THREAD_WORDS: {
+    readonly opening: "Opening your conversation…";
+    readonly notOpened: (detail: string) => string;
+};
+/**
+ * A session's conversation as a person reads it, from the AG-UI messages the
+ * runtime says (`GET …/sessions/{uid}/messages`, a `MESSAGES_SNAPSHOT`): what
+ * was said and answered, in words. A turn a personal agent asked is shown
+ * without what the runtime told the application before the person's words
+ * (`askedOf`, decided 2026-10-14). What its messages showed comes on the
+ * conversation's ui socket (REACTOR_UI RU-W), never here: a `reactor.ui`
+ * activity in a thread is refused.
+ */
+export declare function messagesOfThread(messages: unknown): ChatMessage[];
+/** The AG-UI messages a session-API stream's `MESSAGES_SNAPSHOT` carries, if one does. */
+export declare function snapshotOfStream(text: string): unknown[] | undefined;
+/**
+ * A thread's conversation, read from the runtime its application runs on:
+ * held there, or resumed from its record. Throws the runtime's sentence when
+ * neither answers.
+ */
+export declare function openThread({ agentBaseUrl, agentId, uid, token, fetcher, }: {
+    agentBaseUrl: string;
+    agentId: string;
+    uid: string;
+    token?: string | null;
+    fetcher?: typeof fetch;
+}): Promise<ChatMessage[]>;

package/lib/portable/thread.js

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { eventsOfStream, REACTOR_UI_NAME } from './agui';
+import { askedOf } from './records';
+/** What opening a thread says, in a person's words. */
+export const THREAD_WORDS = {
+    opening: 'Opening your conversation…',
+    notOpened: (detail) => `Your conversation could not be opened, so this is a new one: ${detail}`,
+};
+/**
+ * A session's conversation as a person reads it, from the AG-UI messages the
+ * runtime says (`GET …/sessions/{uid}/messages`, a `MESSAGES_SNAPSHOT`): what
+ * was said and answered, in words. A turn a personal agent asked is shown
+ * without what the runtime told the application before the person's words
+ * (`askedOf`, decided 2026-10-14). What its messages showed comes on the
+ * conversation's ui socket (REACTOR_UI RU-W), never here: a `reactor.ui`
+ * activity in a thread is refused.
+ */
+export function messagesOfThread(messages) {
+    if (!Array.isArray(messages)) {
+        return [];
+    }
+    const drawn = [];
+    for (const message of messages) {
+        if (!message || typeof message !== 'object') {
+            continue;
+        }
+        const { id, role, content, activityType } = message;
+        if (role === 'activity' && activityType === REACTOR_UI_NAME) {
+            throw new Error(`Activity ${String(id)}: what a message showed comes on the ui socket (REACTOR_UI RU-W)`);
+        }
+        if ((role === 'user' || role === 'assistant') &&
+            typeof id === 'string' &&
+            typeof content === 'string' &&
+            content.trim()) {
+            drawn.push({
+                id,
+                role,
+                content: role === 'user' ? askedOf(content) : content,
+                createdAt: new Date(),
+            });
+        }
+    }
+    return drawn;
+}
+/** The AG-UI messages a session-API stream's `MESSAGES_SNAPSHOT` carries, if one does. */
+export function snapshotOfStream(text) {
+    let found;
+    for (const event of eventsOfStream(text)) {
+        if (event.type === 'MESSAGES_SNAPSHOT' && Array.isArray(event.messages)) {
+            found = event.messages;
+        }
+    }
+    return found;
+}
+async function detailOf(response) {
+    try {
+        const body = (await response.json());
+        if (typeof body.detail === 'string' && body.detail) {
+            return body.detail;
+        }
+    }
+    catch {
+        // No sentence: the status says it.
+    }
+    return `${response.status}`;
+}
+/**
+ * A thread's conversation, read from the runtime its application runs on:
+ * held there, or resumed from its record. Throws the runtime's sentence when
+ * neither answers.
+ */
+export async function openThread({ agentBaseUrl, agentId, uid, token, fetcher = fetch, }) {
+    const base = `${agentBaseUrl.replace(/\/+$/, '')}/api/v1/apps/sessions/${encodeURIComponent(uid)}`;
+    const authorization = token
+        ? { Authorization: `Bearer ${token}` }
+        : {};
+    const held = await fetcher(`${base}/messages`, { headers: authorization });
+    if (held.ok) {
+        const body = (await held.json());
+        return messagesOfThread(body.messages);
+    }
+    if (held.status !== 404) {
+        throw new Error(await detailOf(held));
+    }
+    // Not held here: resumed from its record, under the same uid.
+    const resumed = await fetcher(`${base}/resume`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...authorization },
+        body: JSON.stringify({ agent: agentId }),
+    });
+    if (!resumed.ok) {
+        throw new Error(await detailOf(resumed));
+    }
+    const snapshot = snapshotOfStream(await resumed.text());
+    if (!snapshot) {
+        throw new Error(`The runtime said nothing of session ${uid}.`);
+    }
+    return messagesOfThread(snapshot);
+}

package/lib/protocols/AGUIAdapter.d.ts

@@ -7,8 +7,6 @@ import type { ProtocolAdapterConfig } from '../types';
 import type { ChatMessage } from '../types/messages';
 import type { ToolDefinition, ToolExecutionResult } from '../types/tools';
 import { BaseProtocolAdapter } from './BaseProtocolAdapter';
-/** What the page says when a run's stream closes before the run said how it ended. */
-export declare const RUN_CUT_SHORT = "The run stopped before it finished, without an answer or an error: send it again.";
 /**
  * AG-UI specific configuration
  */

package/lib/protocols/AGUIAdapter.js

@@ -3,11 +3,9 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { generateMessageId, createAssistantMessage } from '../types/messages';
-import { agUiRefusal, refusalBody } from './agUiRefusal';
+import { agUiRefusal, refusalBody } from '../portable/agUiRefusal';
+import { AgUiFrames, endsRun, REACTOR_UI_NAME, RUN_CUT_SHORT, toolResultOf, UI_ON_RUN, } from '../portable/agui';
 import { BaseProtocolAdapter } from './BaseProtocolAdapter';
-import { AGUI_NAME } from '@datalayer/reactor/ui';
-/** What the page says when a run's stream closes before the run said how it ended. */
-export const RUN_CUT_SHORT = 'The run stopped before it finished, without an answer or an error: send it again.';
 /**
  * AG-UI protocol adapter
  * Uses HTTP POST with SSE streaming for responses
@@ -434,7 +432,8 @@ export class AGUIAdapter extends BaseProtocolAdapter {
             throw new Error('Response body is not readable');
         }
         const decoder = new TextDecoder();
-        let buffer = '';
+        // The stream's frames, read as every client reads them (portable/agui).
+        const frames = new AgUiFrames(data => console.warn('[AGUIAdapter] Failed to parse event data:', data));
         // Always start fresh — each turn gets its own message bubble.
         // Continuations will naturally appear AFTER the tool calls in the
         // display because they create a new message that is appended at the
@@ -459,56 +458,41 @@ export class AGUIAdapter extends BaseProtocolAdapter {
         // or the network — and the page says so instead of waiting for an answer
         // that is not coming (a Preview gave no answer for minutes, 2026-10-12).
         let ended = false;
+        const handle = (events) => {
+            for (const event of events) {
+                if (endsRun(event)) {
+                    ended = true;
+                }
+                this.handleAGUIEvent(event, {
+                    getCurrentMessageId: () => currentMessageId,
+                    setCurrentMessageId: id => {
+                        currentMessageId = id;
+                    },
+                    getCurrentContent: () => currentContent,
+                    appendContent: content => {
+                        currentContent += content;
+                    },
+                    resetContent: () => {
+                        currentContent = '';
+                    },
+                    appendTurnContent: content => {
+                        currentTurnContent += content;
+                    },
+                    getCurrentTurnContent: () => currentTurnContent,
+                });
+            }
+        };
         try {
             while (true) {
                 const { done, value } = await reader.read();
                 if (done) {
+                    handle(frames.end());
                     if (!ended) {
                         throw new Error(RUN_CUT_SHORT);
                     }
                     break;
                 }
-                buffer += decoder.decode(value, { stream: true });
-                const lines = buffer.split('\n');
-                buffer = lines.pop() || '';
-                for (const line of lines) {
-                    if (line.startsWith('event: ')) {
-                        // Event type (currently unused)
-                        // const eventType = line.slice(7);
-                        // Handle event type if needed
-                    }
-                    else if (line.startsWith('data: ')) {
-                        const data = line.slice(6);
-                        try {
-                            const event = JSON.parse(data);
-                            const kind = event.type;
-                            if (kind === 'RUN_FINISHED' || kind === 'RUN_ERROR') {
-                                ended = true;
-                            }
-                            this.handleAGUIEvent(event, {
-                                getCurrentMessageId: () => currentMessageId,
-                                setCurrentMessageId: id => {
-                                    currentMessageId = id;
-                                },
-                                getCurrentContent: () => currentContent,
-                                appendContent: content => {
-                                    currentContent += content;
-                                },
-                                resetContent: () => {
-                                    currentContent = '';
-                                },
-                                appendTurnContent: content => {
-                                    currentTurnContent += content;
-                                },
-                                getCurrentTurnContent: () => currentTurnContent,
-                            });
-                        }
-                        catch (e) {
-                            // Non-JSON data, might be raw content
-                            console.warn('[AGUIAdapter] Failed to parse event data:', e);
-                        }
-                    }
-                }
+                handle(frames.push(decoder.decode(value, { stream: true })));
             }
         }
         finally {
@@ -531,7 +515,7 @@ export class AGUIAdapter extends BaseProtocolAdapter {
     refuseUiOnRun() {
         this.emit({
             type: 'error',
-            error: new Error('A reactor.ui op came on the run stream: it comes over the ui socket (REACTOR_UI RU-W).'),
+            error: new Error(UI_ON_RUN),
             timestamp: new Date(),
         });
     }
@@ -678,36 +662,17 @@ export class AGUIAdapter extends BaseProtocolAdapter {
                 // Tool execution result with actual output
                 // AG-UI uses camelCase (toolCallId)
                 const toolCallId = event.toolCallId || event.tool_call_id;
-                let content = event.content;
-                // Parse JSON content if it's a string
-                if (typeof content === 'string') {
-                    try {
-                        content = JSON.parse(content);
-                    }
-                    catch {
-                        // Keep as string if not valid JSON
-                    }
-                }
                 if (toolCallId) {
-                    // Check for execution errors in the result
-                    // ExecutionResult format: { execution_ok, execution_error, code_error, ... }
-                    const contentObj = content;
-                    const isError = contentObj?.execution_ok === false ||
-                        contentObj?.code_error != null ||
-                        (contentObj?.error != null && !contentObj?.success);
-                    const errorMessage = contentObj?.execution_error ||
-                        contentObj?.error ||
-                        (contentObj?.code_error
-                            ? `${contentObj.code_error?.name || 'Error'}: ${contentObj.code_error?.value || ''}`
-                            : undefined);
-                    // Emit tool result event with the actual content
+                    // Read as every client reads it (portable/agui): JSON when it is,
+                    // failed when the execution result says so.
+                    const said = toolResultOf(event.content);
                     this.emit({
                         type: 'tool-result',
                         toolResult: {
                             toolCallId,
-                            success: !isError,
-                            result: content,
-                            error: isError ? errorMessage : undefined,
+                            success: said.success,
+                            result: said.result,
+                            error: said.error,
                         },
                         timestamp: new Date(),
                     });
@@ -741,14 +706,14 @@ export class AGUIAdapter extends BaseProtocolAdapter {
                 // `reactor.ui` ops come over the conversation's ui socket, never
                 // the run stream (REACTOR_UI RU-W): one here is refused. Any other
                 // activity is nobody's here.
-                if (event.activityType === AGUI_NAME) {
+                if (event.activityType === REACTOR_UI_NAME) {
                     this.refuseUiOnRun();
                 }
                 break;
             }
             case 'CUSTOM': {
                 const name = event.name;
-                if (name === AGUI_NAME) {
+                if (name === REACTOR_UI_NAME) {
                     this.refuseUiOnRun();
                     break;
                 }

package/lib/voice/ComposerVoice.d.ts

@@ -4,7 +4,10 @@
  * whose composer is a plugin of its own). What the box held when the
  * microphone opened stays; the words heard go after it as they come, and the
  * whole of what was heard replaces them once it stops. Put there for the
- * person to edit and send — or sent at once with *Send what I say*.
+ * person to edit and send — or sent at once with *Send what I say*. While
+ * the words are still being heard the host is told (`onInterimChange`), to
+ * grey them until they are final (VO-11). Beside the microphone, the
+ * person's voice menu (`VoiceMenu`, VO-30).
  *
  * @module voice/ComposerVoice
  */
@@ -26,8 +29,18 @@ export interface ComposerVoiceProps {
     speaking?: boolean;
     /** Stops the agent's voice, also when the microphone opens (VO-13). */
     onStopSpeaking?: () => void;
+    /**
+     * The words in the box are still being heard (`true`), or final
+     * (`false`): the host greys them until they are (VO-11).
+     */
+    onInterimChange?: (interim: boolean) => void;
+    /**
+     * The application lets its answers be heard: the voice menu offers when,
+     * the voice, its speed and loudness (VO-21, VO-25, VO-30).
+     */
+    answers?: boolean;
 }
 /** Whether something rides on a run as a spoken message's metadata (VO-27). */
 export declare function spokenOf(value: unknown): SpokenMetadata | undefined;
-export declare function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled, speaking, onStopSpeaking, }: ComposerVoiceProps): JSX.Element | null;
+export declare function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled, speaking, onStopSpeaking, onInterimChange, answers, }: ComposerVoiceProps): JSX.Element | null;
 export default ComposerVoice;

package/lib/voice/ComposerVoice.js

@@ -1,7 +1,8 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useRef } from 'react';
 import { DeviceHearing } from './hearing';
 import { VoiceInput } from './VoiceInput';
+import { VoiceMenu } from './VoiceMenu';
 /** Whether something rides on a run as a spoken message's metadata (VO-27). */
 export function spokenOf(value) {
     const said = value;
@@ -12,7 +13,7 @@ export function spokenOf(value) {
         ? said
         : undefined;
 }
-export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled = false, speaking = false, onStopSpeaking, }) {
+export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled = false, speaking = false, onStopSpeaking, onInterimChange, answers = false, }) {
     const hearing = useMemo(() => voice.input !== 'off'
         ? new DeviceHearing(voice.modelsUrl, voice.engines)
         : undefined, [voice.input, voice.modelsUrl, voice.engines]);
@@ -22,20 +23,25 @@ export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled
     if (!hearing) {
         return null;
     }
-    return (_jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', silenceMs: voice.silenceMs, microphoneId: voice.microphoneId, disabled: disabled, speaking: speaking, onStopSpeaking: onStopSpeaking, onListen: () => {
-            base.current = input.trim();
-            onStopSpeaking?.();
-        }, 
-        // The words as they are heard, in the box (VO-11); '' gives it back.
-        onInterim: (words) => setInput(afterBase(words)), onTranscript: (transcript) => {
-            if (voice.sendWhatISay) {
-                setInput(base.current);
-                send(transcript.text, transcript.metadata);
-                return;
-            }
-            // In the box, for the person to edit and send: never sent here.
-            onSpoken(transcript.metadata);
-            setInput(afterBase(transcript.text));
-        } }));
+    return (_jsxs("span", { "data-composer-voice": "", style: { display: 'inline-flex', alignItems: 'center', gap: 2 }, children: [_jsx(VoiceMenu, { voice: voice, answers: answers, disabled: disabled }), _jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', silenceMs: voice.silenceMs, microphoneId: voice.microphoneId, disabled: disabled, speaking: speaking, onStopSpeaking: onStopSpeaking, onListen: () => {
+                    base.current = input.trim();
+                    onStopSpeaking?.();
+                }, 
+                // The words as they are heard, in the box (VO-11), greyed until
+                // final; '' gives it back.
+                onInterim: (words) => {
+                    setInput(afterBase(words));
+                    onInterimChange?.(words !== '');
+                }, onTranscript: (transcript) => {
+                    onInterimChange?.(false);
+                    if (voice.sendWhatISay) {
+                        setInput(base.current);
+                        send(transcript.text, transcript.metadata);
+                        return;
+                    }
+                    // In the box, for the person to edit and send: never sent here.
+                    onSpoken(transcript.metadata);
+                    setInput(afterBase(transcript.text));
+                } })] }));
 }
 export default ComposerVoice;

package/lib/voice/VoiceMenu.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The composer's voice menu (VOICE.md VO-14, VO-21, VO-25, VO-30): beside
+ * the microphone, what a person chooses for themselves — the language they
+ * speak and hear, when answers are heard, the voice, its speed and loudness,
+ * *Send what I say*, the microphone, and *Keep speech on this device*. Each
+ * choice is kept in the person's settings and heard at once by every chat
+ * on the page; *Use the application's* forgets them all.
+ *
+ * When answers are heard is offered only where the application lets them be
+ * heard: a menu may not turn on what the application turned off.
+ *
+ * @module voice/VoiceMenu
+ */
+import type { JSX } from 'react';
+import type { SettledVoice } from './chatVoice';
+export interface VoiceMenuProps {
+    /** The chat's voice as it is heard now (`settledVoice`). */
+    voice: SettledVoice;
+    /**
+     * The application lets its answers be heard (its own `output` is not
+     * `off`, and it names the speech service): the menu offers when.
+     */
+    answers: boolean;
+    disabled?: boolean;
+}
+export declare function VoiceMenu({ voice, answers, disabled, }: VoiceMenuProps): JSX.Element;
+export default VoiceMenu;

package/lib/voice/VoiceMenu.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from 'react';
+import { ActionList, ActionMenu, IconButton } from '@primer/react';
+import { GearIcon } from '@primer/octicons-react';
+import { OUTPUT_CHOICES, RATE_CHOICES, VOLUME_CHOICES, catalogueVoiceSpeaks, voiceLanguages, voicesSpeaking, } from './choices';
+import { withVoiceSetting } from './settings';
+import { useVoiceSettings } from './useVoiceSettings';
+/** The microphones the browser lists; named only once one was allowed. */
+async function microphones() {
+    try {
+        const devices = await navigator.mediaDevices.enumerateDevices();
+        return devices.filter(device => device.kind === 'audioinput');
+    }
+    catch {
+        return [];
+    }
+}
+export function VoiceMenu({ voice, answers, disabled = false, }) {
+    const [settings, keep] = useVoiceSettings();
+    const [devices, setDevices] = useState([]);
+    const choose = (key, value) => keep(withVoiceSetting(settings, key, value, catalogueVoiceSpeaks));
+    const onDevice = Boolean(settings.onDeviceOnly);
+    const voices = voicesSpeaking(voice.language);
+    const named = devices.filter(device => device.label);
+    return (_jsxs(ActionMenu, { onOpenChange: open => {
+            if (open) {
+                void microphones().then(setDevices);
+            }
+        }, children: [_jsx(ActionMenu.Anchor, { children: _jsx(IconButton, { icon: GearIcon, size: "small", variant: "invisible", "aria-label": "Voice settings", "data-voice-menu": "", disabled: disabled }) }), _jsx(ActionMenu.Overlay, { width: "medium", children: _jsxs(ActionList, { children: [_jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Language" }), voiceLanguages().map(language => (_jsx(ActionList.Item, { selected: language.value === voice.language, onSelect: () => choose('language', language.value), "data-voice-language": language.value, children: language.label }, language.value)))] }), answers && !onDevice ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Answers heard" }), OUTPUT_CHOICES.map(output => (_jsx(ActionList.Item, { selected: output.value === voice.output, onSelect: () => choose('output', output.value), "data-voice-output": output.value, children: output.label }, output.value)))] }), voices.length > 0 ? (_jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Voice" }), voices.map(spoken => (_jsx(ActionList.Item, { selected: spoken.id === voice.voice, onSelect: () => choose('voice', spoken.id), "data-voice-voice": spoken.id, children: spoken.name }, spoken.id)))] })) : null, _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Speed" }), RATE_CHOICES.map(rate => (_jsx(ActionList.Item, { selected: rate.value === (voice.rate ?? 1), onSelect: () => choose('rate', rate.value), "data-voice-rate": rate.value, children: rate.label }, rate.value)))] }), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Loudness" }), VOLUME_CHOICES.map(volume => (_jsx(ActionList.Item, { selected: volume.value === (voice.volume ?? 1), onSelect: () => choose('volume', volume.value), "data-voice-volume": volume.value, children: volume.label }, volume.value)))] })] })) : null, named.length > 1 ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Microphone" }), named.map(device => (_jsx(ActionList.Item, { selected: device.deviceId ===
+                                                (voice.microphoneId ?? named[0].deviceId), onSelect: () => choose('microphoneId', device.deviceId), "data-voice-microphone": device.deviceId, children: device.label }, device.deviceId)))] })] })) : null, _jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "multiple", children: [_jsxs(ActionList.Item, { selected: Boolean(voice.sendWhatISay), onSelect: () => choose('sendWhatISay', !voice.sendWhatISay), "data-voice-send-what-i-say": "", children: ["Send what I say", _jsx(ActionList.Description, { variant: "block", children: "Sent as soon as it is heard, not left in the box." })] }), _jsxs(ActionList.Item, { selected: onDevice, onSelect: () => choose('onDeviceOnly', !onDevice), "data-voice-on-device": "", children: ["Keep speech on this device", _jsx(ActionList.Description, { variant: "block", children: "Nothing is sent to Datalayer\u2019s speech service: you are heard in the browser, answers are not spoken." })] })] }), Object.keys(settings).length > 0 ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsx(ActionList.Item, { onSelect: () => keep({}), "data-voice-settings-reset": "", children: "Use the application\u2019s" })] })) : null] }) })] }));
+}
+export default VoiceMenu;

package/lib/voice/chatVoice.js

@@ -11,7 +11,7 @@
  * @module voice/chatVoice
  */
 import { voiceFor } from '../specs/voices';
-import { keptVoiceSettings, voiceForPerson, } from './settings';
+import { heldVoiceSettings, voiceForPerson, } from './settings';
 /**
  * Datalayer's origin for the browser's speech models, as pinned
  * (`s3://datalayer-models-speech` behind its CDN; VO-48, VO-49): each model
@@ -88,7 +88,7 @@ export const SILENCE_MS = 1500;
  * Datalayer's models and packages, a silence of 1.5 s. Answers heard need
  * the speech service's address: refused without.
  */
-export function settledVoice(given, person = keptVoiceSettings()) {
+export function settledVoice(given, person = heldVoiceSettings()) {
     const voice = voiceForPerson(given, person);
     const output = voice.output ?? 'off';
     if (output !== 'off' && !voice.speechUrl) {