@datalayer/agent-runtimes 1.5.27 → 1.5.28

package/lib/apps/apps/AppKept.js

@@ -4,6 +4,7 @@ import { contribution, definePlugin, signal } from '@datalayer/reactor';
 import { useContributions, useSignalValue } from '@datalayer/reactor/react';
 import { LoopChatTurn, LoopPromptPanel } from '../core';
 import { beforeFirstMessage } from './kept';
+import { ASSISTANT_CLEARANCE_VAR } from '../../chat/assistant/clearance';
 export const APP_KEPT_PLUGIN_NAME = '@datalayer/loop-plugin-app-kept';
 /* A signal to read when no chat contributed a turn: the hook needs one. */
 const NO_TURN = signal({ id: 0, status: 'idle' });
@@ -13,7 +14,10 @@ export function AppKept({ says }) {
     if (!beforeFirstMessage(turn)) {
         return null;
     }
-    return (_jsx("div", { role: "note", style: { padding: '4px 8px' }, children: _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: says }) }));
+    return (
+    // Clear of the floating assistant in its corner, at a phone's width too
+    // (REVIEWS Q-08).
+    _jsx("div", { role: "note", style: { padding: `4px var(${ASSISTANT_CLEARANCE_VAR}, 8px) 4px 8px` }, children: _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: says }) }));
 }
 /**
  * The plugin, for one application: what it keeps, under its prompt. Made

package/lib/apps/embed/element.js

@@ -70,7 +70,7 @@ import { parseAppspec } from '../apps/appspec';
 import { readAppspecYaml } from '../apps/yaml';
 import { AppEmbed, embedAssistantCharacter } from './AppEmbed';
 import { WINDOW_NOT_YET } from './embedSession';
-import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EmbedAttributeError, adoptPropertiesSetEarly, embedLookOf, inlineHeightOf, languageOf, resumeOf, runnable, } from './embedConfig';
+import { EMBED_HOST_VARIABLES, EMBED_OBSERVED_ATTRIBUTES, EMBED_TAG, EMBED_TOKEN_NAMES_NO_DEPLOYMENT, EmbedAttributeError, adoptPropertiesSetEarly, embedLookOf, embedTokenDeployment, inlineHeightOf, languageOf, resumeOf, runnable, } from './embedConfig';
 import { embedShadowCss } from './embedTheme';
 import { DEFAULT_API, readVisitorApp } from './visitorApp';
 export { runnable };
@@ -164,9 +164,15 @@ export async function readEmbeddedApp({ api, origin, app, token, fetcher = fetch
         return { kind: 'frame', src: frameSrcOf(origin, app, token) };
     }
     const spec = runnable(parseAppspec(definition.spec));
-    return spec.kind === 'decision'
-        ? { kind: 'frame', src: frameSrcOf(origin, app, token) }
-        : { kind: 'spec', app: spec };
+    if (spec.kind === 'decision') {
+        return { kind: 'frame', src: frameSrcOf(origin, app, token) };
+    }
+    // The visit runs the deployment its token names, and no other (VOICE.md
+    // decision 16): a token naming none is refused before anything is drawn.
+    if (!embedTokenDeployment(token)) {
+        return { kind: 'said', text: EMBED_TOKEN_NAMES_NO_DEPLOYMENT };
+    }
+    return { kind: 'spec', app: spec };
 }
 /** The script that is running, when it is a script tag. */
 function currentScriptUrl() {

package/lib/apps/embed/embedConfig.d.ts

@@ -25,7 +25,7 @@ export declare const EMBED_STYLESHEET_PATH = "/embed/datalayer-app.css";
 export declare const EMBED_ATTRIBUTES: {
     readonly app: "The application’s id on Datalayer.";
     readonly origin: "Where Datalayer is; the origin the script was loaded from by default.";
-    readonly token: "An embed token for an application that is not public, issued to your server for each visit.";
+    readonly token: "An embed token for an application that is not public, issued to your server for each visit; it names the embedded deployment the visit runs, which nothing else on the page names.";
     readonly spec: "The address of an Appspec (YAML or JSON) to run, in place of `app`.";
     readonly mode: "inline, bubble, panel or assistant; the Appspec’s `deployment.embedded.mode` by default, then inline.";
     readonly accent: "green, rose, sky, lime, sun or violet; the Appspec’s `interface.accent` by default, else the theme’s own colours.";
@@ -39,6 +39,15 @@ export declare const EMBED_ATTRIBUTES: {
     readonly 'user-token': "A token your server signed with the deployment’s secret, naming your user (HS256: sub, name, exp at most an hour away): what an application that says user: signed opens its session with.";
 };
 export type EmbedAttribute = keyof typeof EMBED_ATTRIBUTES;
+/**
+ * The deployment an embed token names (VOICE.md decision 16): the embedded
+ * deployment its owner's server asked it for. Read without vouching for it —
+ * the services that take the token verify it — and the only place the
+ * element learns its deployment: it takes no attribute for one.
+ */
+export declare function embedTokenDeployment(token: string): string | undefined;
+/** What an embed token naming no deployment is told (VOICE.md decision 16). */
+export declare const EMBED_TOKEN_NAMES_NO_DEPLOYMENT = "datalayer-app: the embed token names no deployment. Your server asks for one naming the application\u2019s embedded deployment: POST \u2026/api/spacer/v1/apps/<id>/embed-token with {\"deployment\": \"<its uid>\"}.";
 /** Every attribute the element watches. */
 export declare const EMBED_OBSERVED_ATTRIBUTES: EmbedAttribute[];
 /**

package/lib/apps/embed/embedConfig.js

@@ -16,7 +16,7 @@ export const EMBED_STYLESHEET_PATH = '/embed/datalayer-app.css';
 export const EMBED_ATTRIBUTES = {
     app: 'The application’s id on Datalayer.',
     origin: 'Where Datalayer is; the origin the script was loaded from by default.',
-    token: 'An embed token for an application that is not public, issued to your server for each visit.',
+    token: 'An embed token for an application that is not public, issued to your server for each visit; it names the embedded deployment the visit runs, which nothing else on the page names.',
     spec: 'The address of an Appspec (YAML or JSON) to run, in place of `app`.',
     mode: 'inline, bubble, panel or assistant; the Appspec’s `deployment.embedded.mode` by default, then inline.',
     accent: 'green, rose, sky, lime, sun or violet; the Appspec’s `interface.accent` by default, else the theme’s own colours.',
@@ -29,6 +29,30 @@ export const EMBED_ATTRIBUTES = {
     language: 'The language the visitor reads the application in, as BCP 47 tags it (fr, pt-BR): its translation into it, and the chat’s own words; the visitor’s browser’s by default.',
     'user-token': 'A token your server signed with the deployment’s secret, naming your user (HS256: sub, name, exp at most an hour away): what an application that says user: signed opens its session with.',
 };
+/**
+ * The deployment an embed token names (VOICE.md decision 16): the embedded
+ * deployment its owner's server asked it for. Read without vouching for it —
+ * the services that take the token verify it — and the only place the
+ * element learns its deployment: it takes no attribute for one.
+ */
+export function embedTokenDeployment(token) {
+    const payload = token.split('.')[1];
+    if (!payload) {
+        return undefined;
+    }
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const claims = JSON.parse(atob(base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=')));
+        return typeof claims.deployment_uid === 'string' && claims.deployment_uid
+            ? claims.deployment_uid
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** What an embed token naming no deployment is told (VOICE.md decision 16). */
+export const EMBED_TOKEN_NAMES_NO_DEPLOYMENT = 'datalayer-app: the embed token names no deployment. Your server asks for one naming the application’s embedded deployment: POST …/api/spacer/v1/apps/<id>/embed-token with {"deployment": "<its uid>"}.';
 /** Every attribute the element watches. */
 export const EMBED_OBSERVED_ATTRIBUTES = Object.keys(EMBED_ATTRIBUTES);
 /**

package/lib/apps/plugins/chat/ChatView.js

@@ -1321,9 +1321,9 @@ export default function ChatView({ workspace }) {
     /*
      * Its voice asked of the speech service as this chat speaks to its runtime
      * (VOICE.md VO-37, VO-19): the host's token, else this one — a visitor's,
-     * an embed's or the person's — and the deployment it runs.
+     * an embed's or the person's; an embed's names its deployment (decision 16).
      */
-    const askedVoice = useMemo(() => voiceAskedAs(config?.voice, iamToken || undefined, deploymentUid), [config?.voice, iamToken, deploymentUid]);
+    const askedVoice = useMemo(() => voiceAskedAs(config?.voice, iamToken || undefined), [config?.voice, iamToken]);
     /*
      * A deployment's runtime, and the visitors', answer only the application's
      * own routes (OwnRoutesOnly, PAP_DATALAYER's release gates): its chat calls

package/lib/chat/assistant/AssistantStage.js

@@ -7,6 +7,7 @@ import { Dialog, Text } from '@primer/react';
 import { assistantCharacter } from './characters';
 import { BalloonHistoryLarge, SpeechBalloon, } from './SpeechBalloon';
 import { conversationHeaderText } from './BalloonParts';
+import { ASSISTANT_CLEARANCE_VAR } from './clearance';
 import { AssistantContextMenu, LONG_PRESS_MS, opensContextMenu, } from './AssistantContextMenu';
 import { BalloonExpandContext, ExpandedVisual, focusExpanded, } from './BalloonVisual';
 import { SpriteCharacter } from './SpriteCharacter';
@@ -405,6 +406,22 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
         telling ||
         detailing !== null ||
         stayPut);
+    // What it covers in its corner, for a line written under a prompt there
+    // (REVIEWS Q-08).
+    const cornerRight = place.left === undefined && place.top === undefined
+        ? pixels(place.right)
+        : undefined;
+    const cornerBottom = pixels(place.bottom);
+    useEffect(() => {
+        if (aside || cornerRight === undefined || cornerBottom === undefined) {
+            return;
+        }
+        const root = document.documentElement;
+        root.style.setProperty(ASSISTANT_CLEARANCE_VAR, `${cornerRight + size}px`);
+        return () => {
+            root.style.removeProperty(ASSISTANT_CLEARANCE_VAR);
+        };
+    }, [aside, cornerRight, cornerBottom, size]);
     useMouth(stageRef, mouthLevel, state === 'speaking');
     // A decision being asked, or its answer, keeps the balloon up.
     const [deciding, setDeciding] = useState(false);

package/lib/chat/assistant/clearance.d.ts

@@ -0,0 +1,10 @@
+/**
+ * What the floating assistant covers from the right edge of the window while
+ * it stands in a bottom corner, as a CSS length on the document: a line
+ * written under a prompt there (what an application keeps, R-31) leaves it
+ * free, so that the character never stands over its words at a phone's width
+ * (REVIEWS Q-08). Unset when it stands anywhere else, steps aside or is gone.
+ *
+ * @module chat/assistant/clearance
+ */
+export declare const ASSISTANT_CLEARANCE_VAR = "--assistant-clearance";

package/lib/chat/assistant/clearance.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What the floating assistant covers from the right edge of the window while
+ * it stands in a bottom corner, as a CSS length on the document: a line
+ * written under a prompt there (what an application keeps, R-31) leaves it
+ * free, so that the character never stands over its words at a phone's width
+ * (REVIEWS Q-08). Unset when it stands anywhere else, steps aside or is gone.
+ *
+ * @module chat/assistant/clearance
+ */
+export const ASSISTANT_CLEARANCE_VAR = '--assistant-clearance';

package/lib/specs/voices.js

@@ -328,6 +328,53 @@ export const SPEECH_MODEL_CATALOGUE = {
             },
         ],
     },
+    'whisper-large-v3-turbo': {
+        id: 'whisper-large-v3-turbo',
+        version: '0.0.1',
+        name: 'Whisper Large v3 Turbo',
+        description: "Speech to text on Datalayer's servers, on CPU: OpenAI's Whisper large-v3-turbo (809M parameters, 99 languages), converted to CTranslate2 in half precision and run by faster-whisper, its weights quantized to 8 bits when loaded. A recording of up to a minute at a time; the language is detected when the page does not say it.",
+        provider: 'openai',
+        task: 'stt',
+        engine: 'faster-whisper',
+        dtype: 'float16',
+        languages: ['en', 'fr', 'es', 'it', 'pt', 'de', 'nl', 'ja', 'zh', 'hi'],
+        where: ['server'],
+        streaming: false,
+        licence: {
+            weights: 'MIT',
+            code: 'MIT',
+        },
+        attribution: '',
+        upstream: 'https://huggingface.co/openai/whisper-large-v3-turbo',
+        revision: '0a363e9161cbc7ed1431c9597a8ceaf0c4f78fcf',
+        files: [
+            {
+                path: 'config.json',
+                sha256: 'b0253ea6c0d3bea6b1e19e91a02acfd3b53f4467362efcb5a3e6b16c9b3a9b7e',
+                size: 2263,
+            },
+            {
+                path: 'preprocessor_config.json',
+                sha256: '7ccc62c6f2765af1f3b46c00c9b5894426835a05021c8b9c01eecb6dfb542711',
+                size: 340,
+            },
+            {
+                path: 'tokenizer.json',
+                sha256: '297b13372ac43916285644fb9687add3cc62ee2a1adb60da3dc25cc94c1871fd',
+                size: 2710337,
+            },
+            {
+                path: 'vocabulary.json',
+                sha256: 'c69260f2ab26d659b7c398f9a2b2b48ed0df16c3b47d7326782fd9cba71690c1',
+                size: 1068114,
+            },
+            {
+                path: 'model.bin',
+                sha256: 'e76620f83d5f5b69efd3d87e3dc180c1bd21df9fbebacfd4335e5e1efcc018da',
+                size: 1617884929,
+            },
+        ],
+    },
 };
 /** Whether a voice speaks a language: `fr` and `fr-FR` are spoken by a `fr-FR` voice. */
 export function voiceSpeaks(voice, language) {

package/lib/voice/ComposerVoice.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useRef } from 'react';
 import { DeviceHearing } from './hearing';
+import { ServerHearing, hearingPlace } from './serverHearing';
 import { VoiceInput } from './VoiceInput';
 import { VoiceMenu } from './VoiceMenu';
 /** Whether something rides on a run as a spoken message's metadata (VO-27). */
@@ -14,9 +15,30 @@ export function spokenOf(value) {
         : undefined;
 }
 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]);
+    // In the browser, or on Datalayer's servers where the application, the
+    // language or the person's detection asks for it (§5, VO-14, VO-34).
+    const place = hearingPlace(voice);
+    const hearing = useMemo(() => {
+        if (voice.input === 'off') {
+            return undefined;
+        }
+        const device = new DeviceHearing(voice.modelsUrl, voice.engines);
+        return place === 'server' && voice.speechUrl
+            ? new ServerHearing(device, {
+                speechUrl: voice.speechUrl,
+                token: voice.token,
+                detect: voice.detect,
+            })
+            : device;
+    }, [
+        voice.input,
+        voice.modelsUrl,
+        voice.engines,
+        place,
+        voice.speechUrl,
+        voice.token,
+        voice.detect,
+    ]);
     // What the box held when the microphone opened: the words heard go after it.
     const base = useRef('');
     const afterBase = (words) => [base.current, words].filter(Boolean).join(' ');

package/lib/voice/VoiceInput.d.ts

@@ -18,7 +18,7 @@
  * @module voice/VoiceInput
  */
 import type { JSX } from 'react';
-import type { DeviceHearing } from './hearing';
+import type { Hearing } from './hearing';
 import type { Transcript } from './types';
 /** What the microphone is doing, said in words (VO-67, VO-68). */
 export type ListeningState = 'idle' | 'asking' | 'loading' | 'listening' | 'hearing';
@@ -27,7 +27,7 @@ export declare const INTERIM_MS = 700;
 /** The longest a microphone listens in one go, in ms: then it stops by itself. */
 export declare const LONGEST_MS = 60000;
 export interface VoiceInputProps {
-    hearing: DeviceHearing;
+    hearing: Hearing;
     /** The language listened to, BCP 47. */
     language: string;
     /** What was said, once heard. */

package/lib/voice/VoiceInput.js

@@ -5,7 +5,7 @@ import { Box } from '@datalayer/primer-addons';
 import { MicrophoneIcon } from '@datalayer/icons-react';
 import { MuteIcon } from '@primer/octicons-react';
 import { MicrophoneRefused, openMicrophone } from './capture';
-import { CONSENT_SENTENCE, consent, consented } from './consent';
+import { CONSENT_SENTENCE, SERVER_CONSENT_SENTENCE, consent, consentKeyFor, consented, } from './consent';
 const WORDS = {
     idle: '',
     asking: '',
@@ -49,7 +49,7 @@ export function VoiceInput({ hearing, language, onTranscript, onInterim, silence
         if (disabled || stateRef.current !== 'idle') {
             return;
         }
-        if (!consented(consentKey)) {
+        if (!consented(consentKeyFor(consentKey, hearing.where))) {
             setState('asking');
             return;
         }
@@ -277,8 +277,10 @@ export function VoiceInput({ hearing, language, onTranscript, onInterim, silence
                                 void start();
                             }
                         }
-                    } }) }), state === 'asking' && (_jsxs(Box, { role: "dialog", "aria-label": "Talk instead of typing", "data-voice-consent": "", position: "absolute", bottom: "100%", right: 0, mb: 2, width: 280, p: 3, bg: "canvas.overlay", border: "1px solid", borderColor: "border.default", borderRadius: 2, boxShadow: "shadow.large", zIndex: 10, children: [_jsx(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: CONSENT_SENTENCE }), _jsxs(Box, { display: "flex", gap: 2, justifyContent: "flex-end", children: [_jsx(Button, { size: "small", onClick: () => setState('idle'), children: "Not now" }), _jsx(Button, { size: "small", variant: "primary", "data-voice-consent-yes": "", onClick: () => {
-                                    consent(consentKey);
+                    } }) }), state === 'asking' && (_jsxs(Box, { role: "dialog", "aria-label": "Talk instead of typing", "data-voice-consent": "", position: "absolute", bottom: "100%", right: 0, mb: 2, width: 280, p: 3, bg: "canvas.overlay", border: "1px solid", borderColor: "border.default", borderRadius: 2, boxShadow: "shadow.large", zIndex: 10, children: [_jsx(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: hearing.where === 'server'
+                            ? SERVER_CONSENT_SENTENCE
+                            : CONSENT_SENTENCE }), _jsxs(Box, { display: "flex", gap: 2, justifyContent: "flex-end", children: [_jsx(Button, { size: "small", onClick: () => setState('idle'), children: "Not now" }), _jsx(Button, { size: "small", variant: "primary", "data-voice-consent-yes": "", onClick: () => {
+                                    consent(consentKeyFor(consentKey, hearing.where));
                                     // Asked, and said yes: listen now, without another press.
                                     stateRef.current = 'idle';
                                     setState('idle');

package/lib/voice/VoiceMenu.js

@@ -20,6 +20,7 @@ export function VoiceMenu({ voice, answers, disabled = false, }) {
     const [devices, setDevices] = useState([]);
     const choose = (key, value) => keep(withVoiceSetting(settings, key, value, catalogueVoiceSpeaks));
     const onDevice = Boolean(settings.onDeviceOnly);
+    const detect = Boolean(settings.detectLanguage);
     const voices = voicesSpeaking(voice.language);
     const named = devices.filter(device => device.label);
     return (_jsxs(ActionMenu, { onOpenChange: open => {
@@ -27,6 +28,6 @@ export function VoiceMenu({ voice, answers, disabled = false, }) {
                 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] }) })] }));
+                                                (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." })] }), voice.speechUrl && !onDevice ? (_jsxs(ActionList.Item, { selected: detect, onSelect: () => choose('detectLanguage', !detect), "data-voice-detect": "", children: ["Detect the language I speak", _jsx(ActionList.Description, { variant: "block", children: "Heard on Datalayer\u2019s servers by Whisper, which finds the language; nothing is kept there." })] })) : null, _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.d.ts

@@ -44,10 +44,11 @@ export declare function chatVoiceOf(spec: AppVoiceSpec | undefined, place: ChatV
  * A chat's voice asked of the speech service as the chat itself speaks to
  * its runtime (VO-37, VO-19): the token its host gave, else the chat's own —
  * a visitor's token minted from ai-inference, an embed's token, or the
- * person's — and the deployment it runs, which an embed's token is checked
- * against. One token for the conversation and its voice, never a second.
+ * person's. One token for the conversation and its voice, never a second.
+ * An embed's deployment is the one its token names (decision 16): the page
+ * says none.
  */
-export declare function voiceAskedAs(voice: ChatVoice | undefined, token: string | undefined, deployment: string | undefined): ChatVoice | undefined;
+export declare function voiceAskedAs(voice: ChatVoice | undefined, token: string | undefined): ChatVoice | undefined;
 /** A chat's voice with every place said: what the chat reads. */
 export type SettledVoice = Required<Pick<ChatVoice, 'language' | 'input' | 'output' | 'voice' | 'modelsUrl' | 'engines' | 'silenceMs'>> & Omit<ChatVoice, 'language' | 'input' | 'output' | 'voice' | 'modelsUrl' | 'engines' | 'silenceMs'>;
 /** How long a silence after speech stops a microphone clicked on, when unsaid (VO-10). */

package/lib/voice/chatVoice.js

@@ -57,26 +57,23 @@ export function chatVoiceOf(spec, place) {
         speechUrl: place.speechUrl,
         token: place.token,
         consentKey: place.consentKey,
+        where: spec.where ?? 'auto',
     };
 }
 /**
  * A chat's voice asked of the speech service as the chat itself speaks to
  * its runtime (VO-37, VO-19): the token its host gave, else the chat's own —
  * a visitor's token minted from ai-inference, an embed's token, or the
- * person's — and the deployment it runs, which an embed's token is checked
- * against. One token for the conversation and its voice, never a second.
+ * person's. One token for the conversation and its voice, never a second.
+ * An embed's deployment is the one its token names (decision 16): the page
+ * says none.
  */
-export function voiceAskedAs(voice, token, deployment) {
+export function voiceAskedAs(voice, token) {
     if (!voice) {
         return undefined;
     }
     const asked = voice.token || token;
-    const runs = voice.deployment || deployment;
-    return {
-        ...voice,
-        ...(asked ? { token: asked } : {}),
-        ...(runs ? { deployment: runs } : {}),
-    };
+    return asked ? { ...voice, token: asked } : { ...voice };
 }
 /** How long a silence after speech stops a microphone clicked on, when unsaid (VO-10). */
 export const SILENCE_MS = 1500;

package/lib/voice/consent.d.ts

@@ -4,3 +4,11 @@ export declare function consented(app: string): boolean;
 export declare function consent(app: string): void;
 /** The sentence said before the first use: where the audio goes (VO-61). */
 export declare const CONSENT_SENTENCE = "What you say is transcribed on this device: the sound never leaves it, and is not kept. The words go in the message box, for you to send.";
+/**
+ * The sentence said before the first use when what is said is heard on
+ * Datalayer's servers (VO-34, VO-61): asked apart from the device's, since
+ * a yes to one is not a yes to the other.
+ */
+export declare const SERVER_CONSENT_SENTENCE = "What you say is sent to Datalayer\u2019s servers to be transcribed: the sound and the words are not kept there. The words go in the message box, for you to send.";
+/** Whose consent is remembered for hearing in a place: the application's, apart for the server. */
+export declare function consentKeyFor(app: string, where: 'device' | 'server'): string;

package/lib/voice/consent.js

@@ -32,3 +32,13 @@ export function consent(app) {
 }
 /** The sentence said before the first use: where the audio goes (VO-61). */
 export const CONSENT_SENTENCE = 'What you say is transcribed on this device: the sound never leaves it, and is not kept. The words go in the message box, for you to send.';
+/**
+ * The sentence said before the first use when what is said is heard on
+ * Datalayer's servers (VO-34, VO-61): asked apart from the device's, since
+ * a yes to one is not a yes to the other.
+ */
+export const SERVER_CONSENT_SENTENCE = 'What you say is sent to Datalayer’s servers to be transcribed: the sound and the words are not kept there. The words go in the message box, for you to send.';
+/** Whose consent is remembered for hearing in a place: the application's, apart for the server. */
+export function consentKeyFor(app, where) {
+    return where === 'server' ? `${app}:server` : app;
+}

package/lib/voice/hearing.d.ts

@@ -22,15 +22,30 @@ export interface HeardSoFar {
     /** How long it has been silent since the speech last ended, in ms. */
     silentMs: number;
 }
+/**
+ * What hears a press, wherever it runs (§5): in the page (`DeviceHearing`)
+ * or on Datalayer's servers (`ServerHearing`).
+ */
+export interface Hearing {
+    /** Where the sound is heard: what the consent says, and a transcript's `where`. */
+    readonly where: 'device' | 'server';
+    /** Load what hears a language, saying how far it has come. */
+    ready(language: string, progress?: HearingProgress): Promise<void>;
+    /** What was said so far while the microphone stays open (VO-11). */
+    hearSoFar(audio: Float32Array, language: string): Promise<HeardSoFar>;
+    /** What was said in a press, or `undefined` when nothing was. */
+    hear(audio: Float32Array, language: string): Promise<Transcript | undefined>;
+}
 /** Joins the speech a VAD found, in order. */
 export declare function joinSegments(segments: Float32Array[]): Float32Array;
 /**
  * The page's hearing: loaded once, on first use, from Datalayer's origin
  * (`modelsUrl`), every file checked against its pin.
  */
-export declare class DeviceHearing {
+export declare class DeviceHearing implements Hearing {
     private readonly modelsUrl;
     private readonly engines;
+    readonly where: "device";
     private recognizers;
     private vad?;
     constructor(modelsUrl: string, engines: VoiceEngines);
@@ -40,6 +55,13 @@ export declare class DeviceHearing {
     sizeFor(language: string): number;
     /** Load what hears a language, saying how far it has come. */
     ready(language: string, progress?: HearingProgress): Promise<void>;
+    /** Load only what finds speech (Silero VAD): what hearing on the server needs here. */
+    readyToFindSpeech(progress?: HearingProgress): Promise<void>;
+    /** The speech in what was heard, and how long it has been silent since it last ended, in ms. */
+    findSpeech(audio: Float32Array): Promise<{
+        speech: Float32Array;
+        silentMs: number;
+    }>;
     private recognizer;
     private activity;
     /** The speech Silero VAD finds in what was heard, and where the last ended, in ms. */

package/lib/voice/hearing.js

@@ -45,6 +45,7 @@ export function joinSegments(segments) {
 export class DeviceHearing {
     modelsUrl;
     engines;
+    where = 'device';
     recognizers = new Map();
     vad;
     constructor(modelsUrl, engines) {
@@ -67,6 +68,22 @@ export class DeviceHearing {
     async ready(language, progress) {
         await Promise.all([this.recognizer(language, progress), this.activity()]);
     }
+    /** Load only what finds speech (Silero VAD): what hearing on the server needs here. */
+    async readyToFindSpeech(progress) {
+        const total = downloadSize('silero-vad');
+        progress?.(0, total);
+        await this.activity();
+        progress?.(total, total);
+    }
+    /** The speech in what was heard, and how long it has been silent since it last ended, in ms. */
+    async findSpeech(audio) {
+        const { speech, lastEnd } = await this.speechIn(audio);
+        const heardMs = (audio.length / HEARING_RATE) * 1000;
+        return {
+            speech,
+            silentMs: lastEnd === undefined ? 0 : Math.max(0, heardMs - lastEnd),
+        };
+    }
     recognizer(language, progress) {
         const model = this.modelFor(language);
         let loading = this.recognizers.get(model.id);
@@ -163,9 +180,7 @@ export class DeviceHearing {
      * since the speech ended — what stops a click to talk (VO-10).
      */
     async hearSoFar(audio, language) {
-        const { speech, lastEnd } = await this.speechIn(audio);
-        const heardMs = (audio.length / HEARING_RATE) * 1000;
-        const silentMs = lastEnd === undefined ? 0 : Math.max(0, heardMs - lastEnd);
+        const { speech, silentMs } = await this.findSpeech(audio);
         if (speech.length < HEARING_RATE * 0.2) {
             return { text: '', spoke: false, silentMs };
         }

package/lib/voice/index.d.ts

@@ -13,6 +13,7 @@ export * from './sentences';
 export * from './pinned';
 export * from './capture';
 export * from './hearing';
+export * from './serverHearing';
 export * from './speaker';
 export * from './consent';
 export * from './settings';
@@ -64,15 +65,19 @@ export interface ChatVoice {
      * (VO-10, VO-69): 1,500 when unsaid; longer for a person who pauses.
      */
     silenceMs?: number;
-    /** ai-agents, whose speech service says the answers. */
+    /** ai-agents, whose speech service says the answers, and hears where the browser does not. */
     speechUrl?: string;
-    /** The token the speech service is asked with. */
-    token?: string;
     /**
-     * The deployment an embedded application's page speaks for (VO-19): what
-     * the speech service checks an embed token against, and counts its spend on.
+     * Where what is said is heard (§5): `device`, the browser; `server`,
+     * Datalayer's speech service; `auto`, the default, the browser where a
+     * model there hears the language, else the server. The Appspec's
+     * `interface.voice.where`.
      */
-    deployment?: string;
+    where?: 'auto' | 'device' | 'server';
+    /** The person asked for their language to be found by Whisper on the server (VO-14). */
+    detect?: boolean;
+    /** The token the speech service is asked with. */
+    token?: string;
     /** Send what is said at once, rather than put it in the composer. */
     sendWhatISay?: boolean;
     /**

package/lib/voice/index.js

@@ -7,6 +7,7 @@ export * from './sentences';
 export * from './pinned';
 export * from './capture';
 export * from './hearing';
+export * from './serverHearing';
 export * from './speaker';
 export * from './consent';
 export * from './settings';

package/lib/voice/serverHearing.d.ts

@@ -0,0 +1,58 @@
+import type { Hearing, HearingProgress, HeardSoFar } from './hearing';
+import type { Transcript } from './types';
+/** Where the speech service hears a recording, on ai-agents' host. */
+export declare const TRANSCRIPTIONS_PATH = "/api/ai-agents/v1/speech/transcriptions";
+/** The model the speech service hears with (agentspecs' catalogue). */
+export declare const SERVER_HEARING_MODEL = "whisper-large-v3-turbo";
+/** Where a chat's voice hears: in the browser, or on Datalayer's servers. */
+export type HearingPlace = 'device' | 'server';
+/** What decides where a chat's voice hears. */
+export interface HearingAsked {
+    language: string;
+    /** The application's `interface.voice.where`; `auto` when unsaid. */
+    where?: 'auto' | 'device' | 'server';
+    /** The person asked for their language to be detected (VO-14). */
+    detect?: boolean;
+    /** The speech service; none, and everything is heard in the browser. */
+    speechUrl?: string;
+}
+/**
+ * Where a chat's voice hears (§5): in the browser unless the speech service
+ * is named and the person asked for detection, the application says
+ * `server`, or it says `auto` and no model in the browser hears the language.
+ */
+export declare function hearingPlace(voice: HearingAsked): HearingPlace;
+/** Mono samples at 16 kHz as a 16-bit PCM WAV file: what the service reads. */
+export declare function wavOf(samples: Float32Array, rate?: number): ArrayBuffer;
+/** What finds the speech in what was heard: the browser's VAD (`DeviceHearing`). */
+export interface SpeechFinder {
+    readyToFindSpeech(progress?: HearingProgress): Promise<void>;
+    findSpeech(audio: Float32Array): Promise<{
+        speech: Float32Array;
+        silentMs: number;
+    }>;
+}
+export interface ServerHearingOptions {
+    /** ai-agents' origin, where the speech service is. */
+    speechUrl: string;
+    /** The token the conversation speaks with: the person's, a visitor's, an embed's. */
+    token?: string;
+    /** Let Whisper find the language (VO-14), rather than tell it. */
+    detect?: boolean;
+    fetcher?: typeof fetch;
+}
+/**
+ * Hears on Datalayer's servers: the browser's VAD finds the speech and when
+ * it stopped; Whisper, on the speech service, writes it.
+ */
+export declare class ServerHearing implements Hearing {
+    private readonly finder;
+    private readonly options;
+    readonly where: "server";
+    constructor(finder: SpeechFinder, options: ServerHearingOptions);
+    /** Only the VAD loads in the page: the words are written on the server. */
+    ready(_language: string, progress?: HearingProgress): Promise<void>;
+    /** Whether speech was found and how long it has been silent; its words come at the end. */
+    hearSoFar(audio: Float32Array): Promise<HeardSoFar>;
+    hear(audio: Float32Array, language: string): Promise<Transcript | undefined>;
+}