@datalayer/agent-runtimes 1.5.60 → 1.5.62

package/lib/apps/apps/AppRenderer.js

@@ -71,6 +71,7 @@ import { keepsFeedback } from './feedback';
 import { keptBeforeFirstMessage } from './kept';
 import { ChatLanguage } from '../../chat/ChatLanguage';
 import { chatVoiceOf } from '../../voice/chatVoice';
+import { keptAudioDays } from '../../voice/keptSound';
 import { defineAppRuntimePlugin } from './AppRuntimePlugins';
 import { hasFolderModules } from './customComponents';
 import { appPluginPair } from './pluginPair';
@@ -471,7 +472,11 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, o
                     ...speech,
                     consentKey: app.id,
                     language,
-                }),
+                }, 
+                // What is said kept as sound, as its record says (VO-63): only for
+                // a person signed in (the host gave their token), never a visitor
+                // nor an embed's.
+                visitor || !speech.token ? undefined : keptAudioDays(app.record)),
             };
         }
         catch (error) {
@@ -482,6 +487,8 @@ export function AppRenderer({ app, plugins = NO_PLUGINS, instance, onPresence, o
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [
         JSON.stringify(app.interface?.voice ?? null),
+        JSON.stringify(app.record?.include ?? null),
+        visitor,
         app.id,
         language,
         speech?.speechUrl,

package/lib/chat/assistant/AssistantStage.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Suspense, lazy, useCallback, useEffect, useId, useRef, useState, } from 'react';
+import { Suspense, lazy, useCallback, useEffect, useId, useReducer, useRef, useState, } from 'react';
 import { ActionList, ActionMenu, IconButton, useTheme } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { CodeIcon, CommentDiscussionIcon, DependabotIcon, InfoIcon, MuteIcon, PencilIcon, PlusIcon, PulseIcon, ScreenNormalIcon, SquareFillIcon, TrashIcon, UnmuteIcon, XIcon, } from '@primer/octicons-react';
@@ -11,6 +11,7 @@ import { ASSISTANT_CLEARANCE_VAR } from './clearance';
 import { AssistantContextMenu, LONG_PRESS_MS, opensContextMenu, } from './AssistantContextMenu';
 import { BalloonExpandContext, ExpandedVisual, focusExpanded, } from './BalloonVisual';
 import { SpriteCharacter } from './SpriteCharacter';
+import { BALLOON_GRACE_MS, BALLOON_HOVER_START, balloonHover, graceRuns, } from './balloonHover';
 import { isAssistantModel3D } from './avatar3d';
 import { conversationCount, } from './toolLine';
 import { ASSISTANT_OBSTACLES, POINTER_CALM_MS, mouthOpening, boxesMeet, pointerNear, } from './state';
@@ -393,7 +394,33 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
     // Drawn for the chat's colour mode: the dark drawing on a dark page (T-25).
     const { colorScheme } = useTheme();
     const colorMode = colorScheme?.startsWith('dark') ? 'dark' : 'light';
-    const [hovered, setHovered] = useState(false);
+    // The figure and its balloon are one hover region: the balloon stays
+    // while the pointer crosses to it, and closes once the pointer has been
+    // on neither for a moment, on Escape or on a press outside.
+    const [hover, dispatchHover] = useReducer(balloonHover, BALLOON_HOVER_START);
+    const hovered = hover.shown;
+    const hoverGrace = graceRuns(hover);
+    useEffect(() => {
+        if (!hoverGrace) {
+            return;
+        }
+        const grace = setTimeout(() => dispatchHover('grace'), BALLOON_GRACE_MS);
+        return () => clearTimeout(grace);
+    }, [hoverGrace]);
+    useEffect(() => {
+        if (!hovered) {
+            return;
+        }
+        const onPress = (event) => {
+            const target = event.target;
+            if (target && stageRef.current?.contains(target)) {
+                return;
+            }
+            dispatchHover('outside');
+        };
+        document.addEventListener('pointerdown', onPress, true);
+        return () => document.removeEventListener('pointerdown', onPress, true);
+    }, [hovered, stageRef]);
     const [menuOpen, setMenuOpen] = useState(false);
     // Its own menu, where it was opened; the inspector and *About* it opens.
     const [menuAt, setMenuAt] = useState(null);
@@ -596,7 +623,28 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
             '@media (prefers-reduced-motion: reduce)': {
                 '& *': { animation: 'none !important' },
             },
-        }, onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false), children: [shown && (_jsx(ExpandedVisual, { visual: shown, target: expandTarget, onClose: () => setExpanded(null) })), showBalloon && balloon && (_jsx(BalloonExpandContext.Provider, { value: expand, children: _jsx(SpeechBalloon, { text: balloon.text, more: balloon.more, approval: balloon.approval, onDismissPeek: balloon.onDismiss, display: balloonDisplay, tool: balloon.tool, speaking: balloon.speaking, busy: balloon.busy, attachment: balloon.attachment, history: balloon.history, onExpand: expand ?? undefined, expandTitle: visual?.title, onExpandHistory: historyVisual
+        }, onMouseEnter: () => dispatchHover('enter'), onMouseLeave: () => dispatchHover('leave'), onFocus: (event) => {
+            // Keyboard focus keeps the balloon; a click's focus does not.
+            let keyboard = true;
+            try {
+                keyboard = event.target.matches(':focus-visible');
+            }
+            catch {
+                // No :focus-visible here: count it.
+            }
+            if (keyboard) {
+                dispatchHover('focus');
+            }
+        }, onBlur: (event) => {
+            const next = event.relatedTarget;
+            if (!next || !event.currentTarget.contains(next)) {
+                dispatchHover('blur');
+            }
+        }, onKeyDown: (event) => {
+            if (event.key === 'Escape' && hovered) {
+                dispatchHover('escape');
+            }
+        }, children: [shown && (_jsx(ExpandedVisual, { visual: shown, target: expandTarget, onClose: () => setExpanded(null) })), showBalloon && balloon && (_jsx(BalloonExpandContext.Provider, { value: expand, children: _jsx(SpeechBalloon, { text: balloon.text, more: balloon.more, approval: balloon.approval, onDismissPeek: balloon.onDismiss, display: balloonDisplay, tool: balloon.tool, speaking: balloon.speaking, busy: balloon.busy, attachment: balloon.attachment, history: balloon.history, onExpand: expand ?? undefined, expandTitle: visual?.title, onExpandHistory: historyVisual
                         ? () => {
                             setExpanded(historyVisual);
                             if (expandTarget) {

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

@@ -0,0 +1,29 @@
+/**
+ * When the assistant's balloon shows for a hover — the hover-intent rule.
+ *
+ * The figure and its balloon are one region: the balloon opens when the
+ * pointer enters either, and stays while it is over either. Leaving them
+ * does not close it at once — the pointer crosses the gap between the figure
+ * and the balloon, or a 3D figure's canvas redraws under it — it closes once
+ * the pointer has been on neither for `BALLOON_GRACE_MS`. Keyboard focus in
+ * the region keeps it open too. Escape, or a press outside, closes it at
+ * once; it opens again on the next enter or focus.
+ *
+ * Pure: the stage dispatches what happened and runs the grace timer while
+ * `graceRuns` says so.
+ */
+/** How long the balloon stays once the pointer is on neither, in ms. */
+export declare const BALLOON_GRACE_MS = 700;
+export interface BalloonHover {
+    /** The balloon shows for the hover. */
+    shown: boolean;
+    /** The pointer is over the figure or its balloon. */
+    over: boolean;
+    /** Keyboard focus is in the figure or its balloon. */
+    focused: boolean;
+}
+export type BalloonHoverEvent = 'enter' | 'leave' | 'focus' | 'blur' | 'grace' | 'escape' | 'outside';
+export declare const BALLOON_HOVER_START: BalloonHover;
+export declare function balloonHover(state: BalloonHover, event: BalloonHoverEvent): BalloonHover;
+/** Whether the grace timer runs: shown, the pointer on neither, no focus. */
+export declare function graceRuns(state: BalloonHover): boolean;

package/lib/chat/assistant/balloonHover.js

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * When the assistant's balloon shows for a hover — the hover-intent rule.
+ *
+ * The figure and its balloon are one region: the balloon opens when the
+ * pointer enters either, and stays while it is over either. Leaving them
+ * does not close it at once — the pointer crosses the gap between the figure
+ * and the balloon, or a 3D figure's canvas redraws under it — it closes once
+ * the pointer has been on neither for `BALLOON_GRACE_MS`. Keyboard focus in
+ * the region keeps it open too. Escape, or a press outside, closes it at
+ * once; it opens again on the next enter or focus.
+ *
+ * Pure: the stage dispatches what happened and runs the grace timer while
+ * `graceRuns` says so.
+ */
+/** How long the balloon stays once the pointer is on neither, in ms. */
+export const BALLOON_GRACE_MS = 700;
+export const BALLOON_HOVER_START = {
+    shown: false,
+    over: false,
+    focused: false,
+};
+export function balloonHover(state, event) {
+    switch (event) {
+        case 'enter':
+            return { ...state, over: true, shown: true };
+        case 'leave':
+            // Still shown: the grace runs.
+            return { ...state, over: false };
+        case 'focus':
+            return { ...state, focused: true, shown: true };
+        case 'blur':
+            return { ...state, focused: false };
+        case 'grace':
+            return state.over || state.focused ? state : { ...state, shown: false };
+        case 'escape':
+            return { ...state, shown: false };
+        case 'outside':
+            return { ...state, shown: false, over: false, focused: false };
+    }
+}
+/** Whether the grace timer runs: shown, the pointer on neither, no focus. */
+export function graceRuns(state) {
+    return state.shown && !state.over && !state.focused;
+}

package/lib/chat/base/ChatBase.js

@@ -3087,7 +3087,14 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         const forwardedProps = spoken
             ? { ...(forwardedPropsGiven ?? {}), voice: spoken }
             : forwardedPropsGiven;
-        const userMessage = createUserMessage(messageContent, spoken ? { ...spoken } : undefined);
+        // The message says how it was heard; its sound, sent to be kept
+        // (VO-63), rides on the run only, never on the conversation.
+        let heardAs;
+        if (spoken) {
+            const { sound: _sound, ...rest } = spoken;
+            heardAs = rest;
+        }
+        const userMessage = createUserMessage(messageContent, heardAs ? { ...heardAs } : undefined);
         const currentMessages = displayItems.filter((item) => !isToolCallMessage(item));
         const allMessages = [...currentMessages, userMessage];
         {

package/lib/voice/ComposerVoice.js

@@ -55,14 +55,14 @@ export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled
     if (!hearing) {
         return null;
     }
-    return (_jsxs("span", { "data-composer-voice": "", style: { display: 'inline-flex', alignItems: 'center', gap: 2 }, children: [_jsx(VoiceMenu, { voice: voice, answers: answers, disabled: disabled }), voice.input === 'hands_free' ? (_jsx(HandsFree, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', microphoneId: voice.microphoneId, turnSilenceMs: voice.turnSilenceMs, disabled: disabled, running: running, speaking: speaking, playbackLevel: playbackLevel, onStopSpeaking: onStopSpeaking, onStopRun: onStopRun, onInterrupted: onInterrupted, onInterim: (words) => {
+    return (_jsxs("span", { "data-composer-voice": "", style: { display: 'inline-flex', alignItems: 'center', gap: 2 }, children: [_jsx(VoiceMenu, { voice: voice, answers: answers, disabled: disabled }), voice.input === 'hands_free' ? (_jsx(HandsFree, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', keepsAudio: voice.keepsAudio, microphoneId: voice.microphoneId, turnSilenceMs: voice.turnSilenceMs, disabled: disabled, running: running, speaking: speaking, playbackLevel: playbackLevel, onStopSpeaking: onStopSpeaking, onStopRun: onStopRun, onInterrupted: onInterrupted, onInterim: (words) => {
                     setInput(words ? afterBase(words) : base.current);
                     onInterimChange?.(words !== '');
                 }, send: (text, metadata) => {
                     onInterimChange?.(false);
                     setInput(base.current);
                     send(text, metadata);
-                } })) : null, _jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', silenceMs: voice.silenceMs, microphoneId: voice.microphoneId, disabled: disabled, speaking: speaking, onStopSpeaking: onStopSpeaking, onListen: () => {
+                } })) : null, _jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', keepsAudio: voice.keepsAudio, silenceMs: voice.silenceMs, microphoneId: voice.microphoneId, disabled: disabled, speaking: speaking, onStopSpeaking: onStopSpeaking, onListen: () => {
                     base.current = input.trim();
                     onStopSpeaking?.();
                 }, 

package/lib/voice/HandsFree.d.ts

@@ -5,7 +5,7 @@
  *
  * On, the microphone stays open. The words are written in the composer as
  * they are heard (VO-11); once the person has spoken and been silent for the
- * turn's silence (`turnSilenceMs`, 700 ms unless said), what was said is
+ * turn's silence (`turnSilenceMs`, 500 ms unless said), what was said is
  * heard whole and **sent** — nothing waits for a click. The answer is said as
  * it is written (hands-free implies `output: always`), and listening goes
  * on through it: speech heard while the agent thinks or speaks is
@@ -24,6 +24,12 @@
  */
 import type { JSX } from 'react';
 import type { Hearing } from './hearing';
+/**
+ * While the agent answers, how often the microphone is looked at for the
+ * person speaking over it, by the VAD alone (VO-52): looked at every
+ * `INTERIM_MS` with the words transcribed, barge-in waited up to 0.7 s.
+ */
+export declare const BARGE_IN_POLL_MS = 150;
 import type { SpokenMetadata } from './types';
 export interface HandsFreeProps {
     hearing: Hearing;
@@ -31,9 +37,14 @@ export interface HandsFreeProps {
     language: string;
     /** Whose consent to the microphone is remembered: the application's id. */
     consentKey: string;
+    /**
+     * The days the application keeps what is said as sound (VO-63): asked in
+     * the first sentence, and each turn's recording sent with its words.
+     */
+    keepsAudio?: number;
     /** The microphone the person chose (VO-30); the browser's own when unsaid. */
     microphoneId?: string;
-    /** The silence after speech that ends a turn, in ms; 700 unless said (VO-12). */
+    /** The silence after speech that ends a turn, in ms; 500 unless said (VO-12). */
     turnSilenceMs?: number;
     /** A turn, heard whole: sent at once. */
     send: (text: string, metadata: SpokenMetadata) => void;
@@ -57,5 +68,5 @@ export interface HandsFreeProps {
     onInterrupted?: () => void;
     disabled?: boolean;
 }
-export declare function HandsFree({ hearing, language, consentKey, microphoneId, turnSilenceMs, send, onInterim, running, speaking, playbackLevel, onStopSpeaking, onStopRun, onInterrupted, disabled, }: HandsFreeProps): JSX.Element;
+export declare function HandsFree({ hearing, language, consentKey, keepsAudio, microphoneId, turnSilenceMs, send, onInterim, running, speaking, playbackLevel, onStopSpeaking, onStopRun, onInterrupted, disabled, }: HandsFreeProps): JSX.Element;
 export default HandsFree;

package/lib/voice/HandsFree.js

@@ -2,13 +2,24 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { Button, IconButton, Text, Tooltip } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { openMicrophone } from './capture';
+import { HEARING_RATE, openMicrophone } from './capture';
 import { CONSENT_SENTENCE, SERVER_CONSENT_SENTENCE, consent, consentKeyFor, consented, } from './consent';
 import { HANDS_FREE_WORDS, IDLE_PAUSE_MS, TURN_SILENCE_MS, bargedIn, handsFreeState, turnEnded, } from './handsFree';
+import { keptAudioSentence, soundOf } from './keptSound';
 import { INTERIM_MS } from './VoiceInput';
+/**
+ * While the agent answers, how often the microphone is looked at for the
+ * person speaking over it, by the VAD alone (VO-52): looked at every
+ * `INTERIM_MS` with the words transcribed, barge-in waited up to 0.7 s.
+ */
+export const BARGE_IN_POLL_MS = 150;
+/** The last of the sound looked at for barge-in: 1.5 s, so each look is cheap. */
+const BARGE_IN_WINDOW = Math.round(HEARING_RATE * 1.5);
+/** The least speech that is barge-in, in seconds: a short word (VO-52). */
+const BARGE_IN_SHORTEST = 0.12;
 /** Waits. */
 const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-export function HandsFree({ hearing, language, consentKey, microphoneId, turnSilenceMs = TURN_SILENCE_MS, send, onInterim, running = false, speaking = false, playbackLevel, onStopSpeaking, onStopRun, onInterrupted, disabled = false, }) {
+export function HandsFree({ hearing, language, consentKey, keepsAudio, microphoneId, turnSilenceMs = TURN_SILENCE_MS, send, onInterim, running = false, speaking = false, playbackLevel, onStopSpeaking, onStopRun, onInterrupted, disabled = false, }) {
     const [on, setOn] = useState(false);
     const [paused, setPaused] = useState(false);
     const [asking, setAsking] = useState(false);
@@ -35,7 +46,7 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
         onStopRun,
         onInterrupted,
     };
-    const key = consentKeyFor(consentKey, hearing.where);
+    const key = consentKeyFor(consentKey, hearing.where, keepsAudio);
     const turnOn = useCallback(() => {
         if (!consented(key)) {
             setAsking(true);
@@ -82,8 +93,18 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
             }
             heardWhile.current =
                 stateRef.current === 'listening' ? 'listening' : 'answering';
+            // Once the person spoke in this turn, its end is looked for often,
+            // by the VAD alone, the words between (VO-52).
+            let spokeThisTurn = false;
+            let wordsAt = 0;
             while (alive) {
-                await pause(INTERIM_MS);
+                const quick = (Boolean(hearing.spokeSoFar) &&
+                    (stateRef.current === 'thinking' ||
+                        stateRef.current === 'speaking')) ||
+                    (Boolean(hearing.quietSoFar) &&
+                        spokeThisTurn &&
+                        stateRef.current === 'listening');
+                await pause(quick ? BARGE_IN_POLL_MS : INTERIM_MS);
                 const open = capture.current;
                 if (!alive || !open) {
                     return;
@@ -102,11 +123,27 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
                     }
                     heardWhile.current = answering ? 'answering' : 'listening';
                     quietSince = Date.now();
+                    spokeThisTurn = false;
                     continue;
                 }
                 let so;
                 try {
-                    so = await hearing.hearSoFar(open.peek(), language);
+                    if (answering && hearing.spokeSoFar) {
+                        // Barge-in only: the VAD over the last moment, nothing transcribed.
+                        const sound = open.peek();
+                        const spoke = await hearing.spokeSoFar(sound.subarray(Math.max(0, sound.length - BARGE_IN_WINDOW)), BARGE_IN_SHORTEST);
+                        so = { text: '', spoke, silentMs: 0 };
+                    }
+                    else if (spokeThisTurn &&
+                        hearing.quietSoFar &&
+                        Date.now() - wordsAt < INTERIM_MS) {
+                        // The turn's end looked for: the VAD alone, no words.
+                        so = await hearing.quietSoFar(open.peek());
+                    }
+                    else {
+                        so = await hearing.hearSoFar(open.peek(), language);
+                        wordsAt = Date.now();
+                    }
                 }
                 catch {
                     so = undefined;
@@ -119,6 +156,9 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
                 }
                 if (so.spoke) {
                     quietSince = Date.now();
+                    if (now === 'listening') {
+                        spokeThisTurn = true;
+                    }
                 }
                 const playing = latest.current.playbackLevel;
                 const levels = playing
@@ -155,7 +195,10 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
                     }
                     latest.current.onInterim?.('');
                     if (heard) {
-                        latest.current.send(heard.text, heard.metadata);
+                        // Kept as sound too, as the person agreed (VO-63).
+                        latest.current.send(heard.text, keepsAudio
+                            ? { ...heard.metadata, sound: soundOf(audio) }
+                            : heard.metadata);
                     }
                     try {
                         capture.current = await openMicrophone(microphoneId);
@@ -165,6 +208,7 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
                     }
                     heardWhile.current = 'listening';
                     quietSince = Date.now();
+                    spokeThisTurn = false;
                     continue;
                 }
                 if (now === 'listening' && Date.now() - quietSince >= IDLE_PAUSE_MS) {
@@ -179,7 +223,7 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
             capture.current = undefined;
         };
         // The loop reads the state through a ref: it is not restarted on it.
-    }, [on, paused, hearing, language, microphoneId, turnSilenceMs]);
+    }, [on, paused, hearing, language, microphoneId, turnSilenceMs, keepsAudio]);
     // Esc pauses it.
     useEffect(() => {
         if (!on) {
@@ -215,7 +259,7 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
                             latest.current.onInterim?.('');
                         } }))] })) : null, problem ? (_jsx(Text, { sx: { fontSize: 0, color: 'danger.fg' }, "data-hands-free-problem": "", children: problem })) : null, asking ? (_jsxs(Box, { role: "dialog", "aria-label": "The microphone", "data-hands-free-consent": "", position: "absolute", bottom: "100%", left: 0, 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: () => setAsking(false), children: "Not now" }), _jsx(Button, { size: "small", variant: "primary", "data-hands-free-consent-yes": "", onClick: () => {
+                            : CONSENT_SENTENCE }), keepsAudio ? (_jsx(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, "data-voice-consent-kept": "", children: keptAudioSentence(keepsAudio) })) : null, _jsxs(Box, { display: "flex", gap: 2, justifyContent: "flex-end", children: [_jsx(Button, { size: "small", onClick: () => setAsking(false), children: "Not now" }), _jsx(Button, { size: "small", variant: "primary", "data-hands-free-consent-yes": "", onClick: () => {
                                     consent(key);
                                     setAsking(false);
                                     setProblem(undefined);

package/lib/voice/VoiceInput.d.ts

@@ -48,10 +48,15 @@ export interface VoiceInputProps {
     onListen?: () => void;
     /** Whose consent is remembered: the application's id. */
     consentKey: string;
+    /**
+     * The days the application keeps what is said as sound (VO-63): asked in
+     * the first sentence, and each turn's recording sent with its words.
+     */
+    keepsAudio?: number;
     disabled?: boolean;
     /** The agent is speaking: offer to stop it. */
     speaking?: boolean;
     onStopSpeaking?: () => void;
 }
-export declare function VoiceInput({ hearing, language, onTranscript, onInterim, silenceMs, microphoneId, onListen, consentKey, disabled, speaking, onStopSpeaking, }: VoiceInputProps): JSX.Element;
+export declare function VoiceInput({ hearing, language, onTranscript, onInterim, silenceMs, microphoneId, onListen, consentKey, keepsAudio, disabled, speaking, onStopSpeaking, }: VoiceInputProps): JSX.Element;
 export default VoiceInput;

package/lib/voice/VoiceInput.js

@@ -6,6 +6,7 @@ import { MicrophoneIcon } from '@datalayer/icons-react';
 import { MuteIcon } from '@primer/octicons-react';
 import { MicrophoneRefused, openMicrophone } from './capture';
 import { CONSENT_SENTENCE, SERVER_CONSENT_SENTENCE, consent, consentKeyFor, consented, } from './consent';
+import { keptAudioSentence, soundOf } from './keptSound';
 const WORDS = {
     idle: '',
     asking: '',
@@ -27,7 +28,7 @@ function prefersStill() {
     return (typeof window !== 'undefined' &&
         !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches);
 }
-export function VoiceInput({ hearing, language, onTranscript, onInterim, silenceMs = 1500, microphoneId, onListen, consentKey, disabled = false, speaking = false, onStopSpeaking, }) {
+export function VoiceInput({ hearing, language, onTranscript, onInterim, silenceMs = 1500, microphoneId, onListen, consentKey, keepsAudio, disabled = false, speaking = false, onStopSpeaking, }) {
     const [state, setState] = useState('idle');
     const [said, setSaid] = useState('');
     const [problem, setProblem] = useState();
@@ -49,7 +50,7 @@ export function VoiceInput({ hearing, language, onTranscript, onInterim, silence
         if (disabled || stateRef.current !== 'idle') {
             return;
         }
-        if (!consented(consentKeyFor(consentKey, hearing.where))) {
+        if (!consented(consentKeyFor(consentKey, hearing.where, keepsAudio))) {
             setState('asking');
             return;
         }
@@ -75,7 +76,15 @@ export function VoiceInput({ hearing, language, onTranscript, onInterim, silence
                 ? error.message
                 : 'The microphone could not be opened.');
         }
-    }, [consentKey, disabled, hearing, language, microphoneId, onListen]);
+    }, [
+        consentKey,
+        keepsAudio,
+        disabled,
+        hearing,
+        language,
+        microphoneId,
+        onListen,
+    ]);
     const stop = useCallback(async () => {
         const open = capture.current;
         capture.current = undefined;
@@ -99,7 +108,13 @@ export function VoiceInput({ hearing, language, onTranscript, onInterim, silence
                 return;
             }
             setSaid(`Heard: ${transcript.text}`);
-            onTranscript(transcript);
+            // Kept as sound too, as the person agreed (VO-63).
+            onTranscript(keepsAudio
+                ? {
+                    ...transcript,
+                    metadata: { ...transcript.metadata, sound: soundOf(audio) },
+                }
+                : transcript);
         }
         catch (error) {
             setState('idle');
@@ -287,8 +302,8 @@ export function VoiceInput({ hearing, language, onTranscript, onInterim, silence
                         }
                     } }) }), 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));
+                            : CONSENT_SENTENCE }), keepsAudio ? (_jsx(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, "data-voice-consent-kept": "", children: keptAudioSentence(keepsAudio) })) : null, _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, keepsAudio));
                                     // Asked, and said yes: listen now, without another press.
                                     stateRef.current = 'idle';
                                     setState('idle');

package/lib/voice/chatVoice.d.ts

@@ -40,7 +40,7 @@ export interface ChatVoicePlace {
  * - **Speaking**: its answers said by Datalayer's speech service, on request
  *   or always (VO-20, VO-21); refused here when its host says no service.
  */
-export declare function chatVoiceOf(spec: AppVoiceSpec | undefined, place: ChatVoicePlace): ChatVoice | undefined;
+export declare function chatVoiceOf(spec: AppVoiceSpec | undefined, place: ChatVoicePlace, keepsAudio?: number): ChatVoice | undefined;
 /**
  * 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 —

package/lib/voice/chatVoice.js

@@ -41,7 +41,7 @@ export const DATALAYER_VOICE_ENGINES = {
  * - **Speaking**: its answers said by Datalayer's speech service, on request
  *   or always (VO-20, VO-21); refused here when its host says no service.
  */
-export function chatVoiceOf(spec, place) {
+export function chatVoiceOf(spec, place, keepsAudio) {
     if (!spec?.enabled || (spec.input === 'off' && spec.output === 'off')) {
         return undefined;
     }
@@ -61,6 +61,8 @@ export function chatVoiceOf(spec, place) {
         token: place.token,
         consentKey: place.consentKey,
         where: spec.where ?? 'auto',
+        // Kept as sound only when it listens, as its record says (VO-63).
+        ...(keepsAudio && spec.input !== 'off' ? { keepsAudio } : {}),
     };
 }
 /**

package/lib/voice/consent.d.ts

@@ -10,5 +10,9 @@ export declare const CONSENT_SENTENCE = "What you say is transcribed on this dev
  * 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;
+/**
+ * Whose consent is remembered for hearing in a place: the application's,
+ * apart for the server, and apart again when what is said is kept as sound
+ * (VO-63) — a yes to being heard is not a yes to being kept.
+ */
+export declare function consentKeyFor(app: string, where: 'device' | 'server', keepsAudio?: number): string;

package/lib/voice/consent.js

@@ -38,7 +38,12 @@ export const CONSENT_SENTENCE = 'What you say is transcribed on this device: the
  * 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;
+/**
+ * Whose consent is remembered for hearing in a place: the application's,
+ * apart for the server, and apart again when what is said is kept as sound
+ * (VO-63) — a yes to being heard is not a yes to being kept.
+ */
+export function consentKeyFor(app, where, keepsAudio) {
+    const heard = where === 'server' ? `${app}:server` : app;
+    return keepsAudio ? `${heard}:kept` : heard;
 }

package/lib/voice/handsFree.d.ts

@@ -5,7 +5,7 @@
  * microphone and the clock, this decides.
  *
  * - **Listening**: the microphone is open; the turn ends after
- *   `turnSilenceMs` of silence once the person has spoken (700 ms unless
+ *   `turnSilenceMs` of silence once the person has spoken (500 ms unless
  *   the application or the person says otherwise), and is sent.
  * - **Thinking**: the turn was sent and the agent is answering, nothing
  *   said yet.
@@ -23,7 +23,7 @@ export type HandsFreeState = 'off' | 'listening' | 'thinking' | 'speaking' | 'pa
 /** The word for each state, as the composer shows it. */
 export declare const HANDS_FREE_WORDS: Record<HandsFreeState, string>;
 /** The silence after speech that ends a turn, in ms, unless said otherwise (VO-12). */
-export declare const TURN_SILENCE_MS = 700;
+export declare const TURN_SILENCE_MS = 500;
 /** Listening with nothing said for this long pauses it: a microphone is not left open on an empty room. */
 export declare const IDLE_PAUSE_MS: number;
 /** What decides the state. */

package/lib/voice/handsFree.js

@@ -11,7 +11,7 @@ export const HANDS_FREE_WORDS = {
     paused: 'Paused',
 };
 /** The silence after speech that ends a turn, in ms, unless said otherwise (VO-12). */
-export const TURN_SILENCE_MS = 700;
+export const TURN_SILENCE_MS = 500;
 /** Listening with nothing said for this long pauses it: a microphone is not left open on an empty room. */
 export const IDLE_PAUSE_MS = 5 * 60_000;
 /** The state for what is known: speaking wins over thinking, pausing over both. */

package/lib/voice/hearing.d.ts

@@ -35,6 +35,17 @@ export interface Hearing {
     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>;
+    /**
+     * Whether there is speech in some sound, found by the VAD alone — nothing
+     * transcribed, nothing sent (VO-52): hands-free's quick look for barge-in.
+     */
+    spokeSoFar?(audio: Float32Array, shortestSeconds?: number): Promise<boolean>;
+    /**
+     * Whether there is speech in some sound and how long it has been quiet
+     * since, by the VAD alone — no words (VO-52): hands-free's quick look for
+     * the end of a turn once the person has spoken.
+     */
+    quietSoFar?(audio: Float32Array): Promise<HeardSoFar>;
 }
 /** Joins the speech a VAD found, in order. */
 export declare function joinSegments(segments: Float32Array[]): Float32Array;
@@ -73,6 +84,8 @@ export declare class DeviceHearing implements Hearing {
      * words, for the composer as they come, and how long it has been silent
      * since the speech ended — what stops a click to talk (VO-10).
      */
+    spokeSoFar(audio: Float32Array, shortestSeconds?: number): Promise<boolean>;
+    quietSoFar(audio: Float32Array): Promise<HeardSoFar>;
     hearSoFar(audio: Float32Array, language: string): Promise<HeardSoFar>;
     /**
      * What was said in a press, or `undefined` when nothing was: its speech

package/lib/voice/hearing.js

@@ -179,6 +179,14 @@ export class DeviceHearing {
      * words, for the composer as they come, and how long it has been silent
      * since the speech ended — what stops a click to talk (VO-10).
      */
+    async spokeSoFar(audio, shortestSeconds = 0.2) {
+        const { speech } = await this.findSpeech(audio);
+        return speech.length >= HEARING_RATE * shortestSeconds;
+    }
+    async quietSoFar(audio) {
+        const { speech, silentMs } = await this.findSpeech(audio);
+        return { text: '', spoke: speech.length >= HEARING_RATE * 0.2, silentMs };
+    }
     async hearSoFar(audio, language) {
         const { speech, silentMs } = await this.findSpeech(audio);
         if (speech.length < HEARING_RATE * 0.2) {