@datalayer/agent-runtimes 1.5.59 → 1.5.61

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/apps/plugins/chat/ChatView.js

@@ -1720,7 +1720,9 @@ export default function ChatView({ workspace }) {
                     playbackLevel: () => controlsRef.current?.voiceLevel?.() ?? 0, 
                     // Hands-free (VO-12, VO-13): the run in progress, stopped when
                     // the person speaks over it, and the answer marked interrupted.
-                    running: busy, onStopRun: () => controlsRef.current?.stop?.(), onInterrupted: () => controlsRef.current?.markInterrupted(), onInterimChange: setVoiceInterim, 
+                    running: busy, 
+                    // Spoken over, the application's session stays open (VO-46).
+                    onStopRun: () => (controlsRef.current?.interrupt ?? controlsRef.current?.stop)?.(), onInterrupted: () => controlsRef.current?.markInterrupted(), onInterimChange: setVoiceInterim, 
                     // The menu offers when answers are heard where the
                     // application lets them be (VO-21, VO-30).
                     answers: Boolean(config?.voice?.output &&

package/lib/chat/ChatFloating.js

@@ -10,6 +10,7 @@ import { ButtonGlow } from './display/ButtonGlow';
 import { useViewportDrag } from './useViewportDrag';
 import { disabledChatViewModes, resolveMountPoint } from './viewModes';
 import { AssistantStage } from './assistant/AssistantStage';
+import { ASSISTANT_CLEARANCE_VAR } from './assistant/clearance';
 import { decisionsAskerAt } from './assistant/decisions';
 import { DecisionAsk } from './assistant/DecisionAsk';
 import { useSpokenAnswers } from '../voice/useSpokenAnswers';
@@ -854,6 +855,9 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         : undefined;
     /* The window itself; where it goes is decided below. */
     const chatWindow = (_jsxs(Box, { ref: popupRef, className: className, sx: {
+            // Its own conversation stands beside the character, never under it:
+            // its prompt's controls keep their own padding (T-27).
+            ...(assistantShown ? { [ASSISTANT_CLEARANCE_VAR]: 'initial' } : {}),
             position: viewMode === 'panel' && !isMobile && (panelInFlow || dockedInMount)
                 ? 'relative'
                 : 'fixed',

package/lib/chat/base/ChatBase.js

@@ -59,7 +59,7 @@ import { useVoiceSettings } from '../../voice/useVoiceSettings';
 import { useVoiceSpeaker } from '../../voice/useVoiceSpeaker';
 import { useSpokenAnswers } from '../../voice/useSpokenAnswers';
 import { saidMessageId, useSaidSentence } from '../../voice/captions';
-import { lineToSay } from '../../voice/sayAloud';
+import { isVoiceInterrupted, lineToSay, } from '../../voice/sayAloud';
 import { isFloatingChatViewMode } from '../viewModes';
 import { ToolApprovalBanner, ToolApprovalDialog, } from '../tools';
 import { initialModelId, isOffered, offeredModels as offeredModelsFor, } from './modelChoice';
@@ -2986,6 +2986,16 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
      */
     const [voiceSaid, setVoiceSaid] = useState('');
     voiceSayRef.current = activity => {
+        if (isVoiceInterrupted(activity)) {
+            // Spoken over, the runtime says (VO-46): its voice stops.
+            if (onStopSpeaking) {
+                onStopSpeaking();
+            }
+            else if (ownVoice.speaker) {
+                ownVoice.stop();
+            }
+            return;
+        }
         const line = lineToSay(activity);
         if (!line) {
             return;
@@ -3077,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];
         {
@@ -3251,7 +3268,9 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         applyServerApprovalDecision,
     ]);
     // ---- handleStop ----
-    const handleStop = useCallback(() => {
+    // Spoken over (VO-46, VO-13), an application's session is told so and
+    // stays open; Stop leaves it to be resumed.
+    const stopTurn = useCallback((spokenOver) => {
         stoppedRef.current = true;
         abortControllerRef.current?.abort();
         // Best-effort cancellation without tearing down adapter/session.
@@ -3262,7 +3281,10 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                 adapter.stopGeneration();
             }
             // Also tell the backend to stop (server-side cancellation).
-            if (typeof adapter.terminateSession === 'function') {
+            if (spokenOver && typeof adapter.interruptSession === 'function') {
+                void adapter.interruptSession().catch(() => { });
+            }
+            else if (typeof adapter.terminateSession === 'function') {
                 void adapter.terminateSession().catch(() => { });
             }
             else if (typeof adapter.terminateAgent === 'function') {
@@ -3314,6 +3336,8 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         protocol?.authToken,
         protocol?.agentId,
     ]);
+    const handleStop = useCallback(() => stopTurn(false), [stopTurn]);
+    const handleSpokenOver = useCallback(() => stopTurn(true), [stopTurn]);
     /*
      * How a message's display presses what it offered (RU-4,
      * RU-W): with the token of the offer, as the run's press — which
@@ -3390,6 +3414,8 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             voiceLevel: playbackLevel,
             // The answer spoken over, marked for a host's own composer (VO-13).
             markInterrupted,
+            // Spoken over: the run ends, the application's session stays open (VO-46).
+            interrupt: handleSpokenOver,
         });
         return () => {
             onSendReady(null);
@@ -3400,6 +3426,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         onSendMessage,
         handleSend,
         handleStop,
+        handleSpokenOver,
         handleNewChat,
         stopSpeaking,
         playbackLevel,
@@ -3808,7 +3835,9 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         playbackLevel: playbackLevel, 
         // Hands-free (VO-12, VO-13): the run in progress, stopped when the
         // person speaks over it, and the answer marked interrupted.
-        running: isLoading, onStopRun: handleStop, onInterrupted: markInterrupted, onInterimChange: setVoiceInterim, 
+        running: isLoading, 
+        // Spoken over, the application's session stays open (VO-46).
+        onStopRun: handleSpokenOver, onInterrupted: markInterrupted, onInterimChange: setVoiceInterim, 
         // The menu offers when answers are heard where the application
         // lets them be (VO-21, VO-30).
         answers: Boolean(voice?.output && voice.output !== 'off' && voice.speechUrl), onSpoken: metadata => {

package/lib/chat/prompt/InputPrompt.js

@@ -151,6 +151,9 @@ export function InputPrompt({ input, setInput, isLoading, kernelStatus, connecti
                         {
                             id: 'session-controls',
                             px: padding,
+                            // Its right end — the voice controls — is never under
+                            // the floating assistant in its corner (T-27).
+                            clearsAssistant: true,
                             py: 0.5,
                             minHeight: 36,
                             bordered: true,

package/lib/chat/prompt/stack.d.ts

@@ -18,6 +18,19 @@
  * @module chat/prompt/stack
  */
 import type { ReactNode } from 'react';
+/**
+ * A theme space step (`px={2}`) as a CSS length, from the theme's scale or
+ * else Primer's own.
+ */
+export declare function spaceLength(step: number, scale?: readonly (string | number)[]): string;
+/**
+ * The right padding of a band that `clearsAssistant`: the floating
+ * assistant's clearance while it stands in a bottom corner (what it covers
+ * from the window's right edge, `--assistant-clearance`), so that the
+ * character is never drawn over the band's controls and never takes their
+ * clicks; else the band's own `padding`, a CSS length.
+ */
+export declare function clearOfAssistant(padding: string): string;
 /** One band in a region. */
 export type PromptStack = {
     /** Identity, for React and for a host reasoning about which band is which. */
@@ -69,6 +82,15 @@ export type PromptStack = {
      * showing the page behind it — a pale stripe down the right-hand side.
      */
     layout?: 'row' | 'block';
+    /**
+     * Keep the band's right end clear of the floating assistant while it
+     * stands in a bottom corner: its right padding becomes the assistant's
+     * clearance (`--assistant-clearance`), so that the character is never
+     * drawn over the band's controls and never takes their clicks. For a band
+     * that runs to the page's right edge, as the composer's session controls
+     * do on an application's page.
+     */
+    clearsAssistant?: boolean;
 };
 export type PromptStacksProps = {
     /** The bands, top to bottom. */

package/lib/chat/prompt/stack.js

@@ -1,5 +1,37 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useTheme } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
+import { ASSISTANT_CLEARANCE_VAR } from '../assistant/clearance';
+/** Primer's space scale, for a band drawn without a theme. */
+const PRIMER_SPACE = [
+    '0',
+    '4px',
+    '8px',
+    '16px',
+    '24px',
+    '32px',
+    '40px',
+    '48px',
+    '64px',
+];
+/**
+ * A theme space step (`px={2}`) as a CSS length, from the theme's scale or
+ * else Primer's own.
+ */
+export function spaceLength(step, scale = PRIMER_SPACE) {
+    const value = scale[step] ?? PRIMER_SPACE[step] ?? `${step * 8}px`;
+    return typeof value === 'number' ? `${value}px` : value;
+}
+/**
+ * The right padding of a band that `clearsAssistant`: the floating
+ * assistant's clearance while it stands in a bottom corner (what it covers
+ * from the window's right edge, `--assistant-clearance`), so that the
+ * character is never drawn over the band's controls and never takes their
+ * clicks; else the band's own `padding`, a CSS length.
+ */
+export function clearOfAssistant(padding) {
+    return `var(${ASSISTANT_CLEARANCE_VAR}, ${padding})`;
+}
 /**
  * Whether a band would draw anything.
  *
@@ -12,12 +44,19 @@ function isRendered(stack) {
 /** Render a region's bands, skipping the ones with nothing to show. */
 export function PromptStacks({ stacks, disabled = false, }) {
     const visible = stacks.filter(isRendered);
+    const { theme } = useTheme();
     if (visible.length === 0) {
         return null;
     }
     return (_jsx(_Fragment, { children: visible.map(stack => {
             const isDisabled = disabled || stack.disabled;
-            return (_jsx(Box, { "data-prompt-stack": stack.id, "aria-disabled": isDisabled || undefined, px: stack.px ?? 2, py: stack.py ?? 1, minHeight: stack.minHeight, display: stack.layout === 'block' ? undefined : 'flex', alignItems: stack.layout === 'block' ? undefined : 'center', gap: stack.layout === 'block' ? undefined : (stack.gap ?? 2), pt: stack.pt === undefined ? undefined : stack.pt, pb: stack.pb === undefined ? undefined : stack.pb, borderTop: stack.bordered ? '1px solid' : undefined, borderColor: stack.bordered ? 'border.default' : undefined, bg: stack.subtle ? 'canvas.subtle' : undefined, opacity: isDisabled ? 0.5 : undefined, pointerEvents: isDisabled ? 'none' : undefined, children: stack.content }, stack.id));
+            const px = stack.px ?? 2;
+            const right = Array.isArray(px) ? px[px.length - 1] : px;
+            return (_jsx(Box, { "data-prompt-stack": stack.id, "aria-disabled": isDisabled || undefined, px: px, "data-clears-assistant": stack.clearsAssistant ? '' : undefined, sx: stack.clearsAssistant
+                    ? {
+                        paddingRight: clearOfAssistant(spaceLength(right, theme?.space)),
+                    }
+                    : undefined, py: stack.py ?? 1, minHeight: stack.minHeight, display: stack.layout === 'block' ? undefined : 'flex', alignItems: stack.layout === 'block' ? undefined : 'center', gap: stack.layout === 'block' ? undefined : (stack.gap ?? 2), pt: stack.pt === undefined ? undefined : stack.pt, pb: stack.pb === undefined ? undefined : stack.pb, borderTop: stack.bordered ? '1px solid' : undefined, borderColor: stack.bordered ? 'border.default' : undefined, bg: stack.subtle ? 'canvas.subtle' : undefined, opacity: isDisabled ? 0.5 : undefined, pointerEvents: isDisabled ? 'none' : undefined, children: stack.content }, stack.id));
         }) }));
 }
 export default PromptStacks;

package/lib/models/PageTag.d.ts

@@ -15,5 +15,5 @@ export type PageTag = {
 export declare const PAGE_TAGE_NONE: PageTag;
 export declare const PAGE_TAGS: PageTag[];
 export declare const PAGE_TAGS_BY_NAME_MAP: Map<PageTagName | undefined, PageTag>;
-export declare const PAGE_TAGS_BY_COLOR_MAP: Map<"default" | "green" | "lime" | "blue" | "coral" | "gray" | "indigo" | "orange" | "pink" | "purple" | "red" | "teal" | "yellow" | "lemon", PageTag>;
+export declare const PAGE_TAGS_BY_COLOR_MAP: Map<"blue" | "coral" | "gray" | "green" | "indigo" | "lime" | "orange" | "pink" | "purple" | "red" | "teal" | "yellow" | "default" | "lemon", PageTag>;
 export {};

package/lib/protocols/AGUIAdapter.d.ts

@@ -66,6 +66,14 @@ export declare class AGUIAdapter extends BaseProtocolAdapter {
      * Terminate a running agent thread on the backend
      */
     terminateAgent(threadId?: string): Promise<void>;
+    /**
+     * The person spoke over the agent (VO-46, VO-13): an application's
+     * session is told (`POST {sessions}/{uid}/interrupt`) — what runs is
+     * cancelled, its code's `@app.interrupted` runs, and it stays open for
+     * what is said next, where Stop would leave it waiting to be resumed.
+     * Another agent's run is stopped, as Stop stops it.
+     */
+    interruptSession(threadId?: string): Promise<void>;
     /**
      * Stop an application's session (`POST {sessions}/{uid}/stop`): what runs
      * is cancelled and it waits to be resumed. Its thread is the session; with

package/lib/protocols/AGUIAdapter.js

@@ -126,6 +126,32 @@ export class AGUIAdapter extends BaseProtocolAdapter {
             // Ignore errors - agent may have already completed
         }
     }
+    /**
+     * The person spoke over the agent (VO-46, VO-13): an application's
+     * session is told (`POST {sessions}/{uid}/interrupt`) — what runs is
+     * cancelled, its code's `@app.interrupted` runs, and it stays open for
+     * what is said next, where Stop would leave it waiting to be resumed.
+     * Another agent's run is stopped, as Stop stops it.
+     */
+    async interruptSession(threadId) {
+        const sessions = this.aguiConfig.appSessions;
+        const thread = threadId || this.currentThreadId;
+        if (!sessions) {
+            await this.terminateAgent(threadId);
+            return;
+        }
+        if (!thread) {
+            return;
+        }
+        const url = `${sessions.replace(/\/+$/, '')}/${encodeURIComponent(thread)}/interrupt`;
+        const response = await this.fetchOf()(url, {
+            method: 'POST',
+            headers: this.buildHeaders(),
+        });
+        if (!response.ok) {
+            throw new Error(`The session ${thread} could not be told it was spoken over (${response.status}).`);
+        }
+    }
     /**
      * Stop an application's session (`POST {sessions}/{uid}/stop`): what runs
      * is cancelled and it waits to be resumed. Its thread is the session; with

package/lib/types/chat.d.ts

@@ -700,6 +700,12 @@ export interface ChatBaseProps {
          * for a host whose composer holds the microphone.
          */
         markInterrupted: () => void;
+        /**
+         * The person spoke over the run (VO-46, VO-13): it ends as Stop ends
+         * it, but an application's session is told it was spoken over and
+         * stays open for what is said next — Stop leaves it to be resumed.
+         */
+        interrupt?: () => void;
     } | null) => void;
     /**
      * Reports whether the agent's voice is speaking, for a host that draws the

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 —