@datalayer/agent-runtimes 1.5.52 → 1.5.53

package/lib/types/chat.d.ts

@@ -640,7 +640,7 @@ export type ThemeOverrides = {
     dark?: Record<string, string>;
 };
 /**
- * A conversation the chat goes on with (LOOP D-13): an embedded
+ * A conversation the chat goes on with (D-13): an embedded
  * application's session, reattached after its page reloaded.
  */
 export type ResumedThread = {
@@ -649,7 +649,7 @@ export type ResumedThread = {
     /** What it holds already; none for a new one. */
     messages: ChatMessage[];
     /**
-     * Opened from a person's history (LOOP P-24): its conversation is read
+     * Opened from a person's history (P-24): its conversation is read
      * from the runtime the application's chat runs on as the chat mounts —
      * held there, else resumed from its record — in place of `messages`.
      */
@@ -684,20 +684,26 @@ export interface ChatBaseProps {
          */
         thread: () => string;
         /**
-         * Stops the agent's voice (VOICE.md VO-10): the chat's own speaker,
+         * Stops the agent's voice (VO-10): the chat's own speaker,
          * for a host whose composer holds the microphone and *Stop speaking*.
          * Absent while its answers are not heard.
          */
         stopSpeaking?: () => void;
         /**
-         * Marks the answer the person spoke over *interrupted* (VOICE.md
-         * VO-13), for a host whose composer holds the microphone.
+         * How loud the chat's speaker plays now, 0 to 1 (VO-13): a
+         * host's hands-free gates barge-in on it. Absent while its answers
+         * are not heard by a speaker that gives a level.
+         */
+        voiceLevel?: () => number;
+        /**
+         * Marks the answer the person spoke over *interrupted* (VO-13),
+         * for a host whose composer holds the microphone.
          */
         markInterrupted: () => void;
     } | null) => void;
     /**
      * Reports whether the agent's voice is speaking, for a host that draws the
-     * composer and so its *Stop speaking* (VOICE.md VO-10).
+     * composer and so its *Stop speaking* (VO-10).
      */
     onSpeakingChange?: (speaking: boolean) => void;
     /**
@@ -781,7 +787,7 @@ export interface ChatBaseProps {
     mentionableAgents?: MentionableAgent[];
     /**
      * Commands the prompt lists while `/` is typed, before its own: an
-     * application's (LOOP P-19). Picking one writes `/<name> `. Lexical only.
+     * application's (P-19). Picking one writes `/<name> `. Lexical only.
      */
     promptCommands?: PromptCommand[];
     /**
@@ -886,7 +892,7 @@ export interface ChatBaseProps {
     themeVariant?: string;
     /**
      * Properties laid over the theme's own, by mode — an application's accent
-     * over the theme it wears (LOOP T-05): without them the chat would wear the
+     * over the theme it wears (T-05): without them the chat would wear the
      * theme's default accent whatever the page around it set.
      */
     themeOverrides?: ThemeOverrides;
@@ -1001,7 +1007,7 @@ export interface ChatBaseProps {
     /**
      * The agent's welcome, said as the first message of the history: drawn as
      * the chat draws the agent's messages, and never sent nor kept. The floating
-     * assistant's balloon opens on it (LOOP T-23).
+     * assistant's balloon opens on it (T-23).
      */
     welcome?: string;
     /**
@@ -1011,7 +1017,7 @@ export interface ChatBaseProps {
      */
     trailingContent?: ReactNode;
     /**
-     * Its voice (VOICE.md V1): a microphone in the composer, push-to-talk,
+     * Its voice (V1): a microphone in the composer, push-to-talk,
      * what is said heard on the device and put in the composer — or sent, with
      * *Send what I say* — marked as spoken (VO-27).
      */
@@ -1020,13 +1026,20 @@ export interface ChatBaseProps {
     voiceSpeaking?: boolean;
     /**
      * The sentence the host's speaker is saying, marked in the conversation
-     * (VOICE.md VO-65); a chat that speaks for itself marks its own.
+     * (VO-65); a chat that speaks for itself marks its own.
      */
     voiceSentence?: string;
     /** Stops the agent's voice: the composer's *Stop speaking*, and the microphone opening (VO-13). */
     onStopSpeaking?: () => void;
     /**
-     * Reads an answer aloud (VOICE.md VO-21): given, each answer the agent has
+     * How loud the host's speaker plays now, between 0 and 1 (`useVoiceSpeaker`'s
+     * `level`): hands-free's barge-in counts speech only above what the answer's
+     * own sound can leave in the microphone (VO-13). A chat that speaks
+     * for itself reads its own.
+     */
+    voiceLevel?: () => number;
+    /**
+     * Reads an answer aloud (VO-21): given, each answer the agent has
      * finished writing has a *Read aloud* under it, which calls it with the
      * answer's text.
      */
@@ -1229,7 +1242,7 @@ export interface ChatBaseProps {
         accessToken?: string;
     }>;
     /**
-     * The conversation to go on with (LOOP D-13): its AG-UI thread — an
+     * The conversation to go on with (D-13): its AG-UI thread — an
      * application's session — and what it holds, drawn in place of the
      * runtime's history, which is its agent's and not one session's. Read
      * when the chat mounts; a new thread (the header's +) is the chat's own.

package/lib/types/messages.d.ts

@@ -124,7 +124,7 @@ export interface ChatMessage {
     metadata?: Record<string, unknown>;
     /**
      * What the message shows besides its words: the displays sent under it
-     * (`reactor.ui`, REACTOR_UI RU-2), in the order they came; each drawn by
+     * (`reactor.ui`, RU-2), in the order they came; each drawn by
      * the renderer a plugin contributed for its type.
      */
     displays?: Display[];

package/lib/types/protocol.d.ts

@@ -45,7 +45,7 @@ export interface ProtocolConfig {
     /** Config endpoint URL for non-Jupyter protocols (if not set, uses Jupyter requestAPI) */
     configEndpoint?: string;
     /**
-     * The ui channel's WebSocket (`ws://` or `wss://`, REACTOR_UI RU-W): an
+     * The ui channel's WebSocket (`ws://` or `wss://`, RU-W): an
      * application's session says on it what its messages show, its steps, its
      * elements, its authors and its window messages, and takes the presses of
      * what they offered. Set for an application's agent; one connection per
@@ -54,7 +54,7 @@ export interface ProtocolConfig {
     uiSocket?: string;
     /**
      * Where a file of a conversation is uploaded before the run or the press
-     * that names it (REACTOR_UI RU-6): Reactor's upload, the bytes as the body,
+     * that names it (RU-6): Reactor's upload, the bytes as the body,
      * the conversation's thread its scope. A run carries the ref it answers,
      * never the bytes. Set for an application's agent.
      */
@@ -69,7 +69,7 @@ export interface ProtocolConfig {
     appSessions?: string;
     /**
      * The runtime answers only the application's own routes (OwnRoutesOnly,
-     * PAP_DATALAYER's release gates): it serves a deployment — kept always on,
+     * the release gates): it serves a deployment — kept always on,
      * launched by a hosted page for it — or is the visitors' runtime. Nothing
      * outside them is opened: not the monitoring stream (an application's
      * session asks its approvals in the conversation, over `uiSocket`), not

package/lib/types/scenes.d.ts

@@ -1,5 +1,5 @@
 /**
- * Scenes (agentspecs `scenes`, `schema: loop.scene/v1`, LOOP A-11): a team,
+ * Scenes (agentspecs `scenes`, `schema: loop.scene/v1`, A-11): a team,
  * staged. The team says who is on stage; the scene says what happens there —
  * the setting, the script, the stage directions, the audience, the rehearsal
  * and where it plays.
@@ -72,7 +72,7 @@ export interface SceneCueSpec {
 }
 /** What kind of answer comes back, and what the page shows. */
 export type SceneAnswerKind = 'words' | 'table' | 'chart' | 'notebook' | 'map' | 'file' | 'image'
-/** The sources it read, as cards that open (STUDIO H-02). */
+/** The sources it read, as cards that open (H-02). */
  | 'sources'
 /** A choice as buttons that answer the application. */
  | 'choice'
@@ -162,7 +162,7 @@ export interface SceneRehearsalBeatSpec {
     mustNotSay?: string[];
     within: string;
 }
-/** A transcript recorded once, played when the scene cannot play live (LOOP H-08). */
+/** A transcript recorded once, played when the scene cannot play live (H-08). */
 export interface SceneRecordingSpec {
     path: string;
     taken: string;
@@ -185,7 +185,7 @@ export interface ScenePlayedBeatSpec {
 }
 /**
  * What came of the last rehearsal `loop scenes rehearse --cloud` played
- * (LOOP A-14): kept beside the specs in `<id>/rehearsal.json`, written by the
+ * (A-14): kept beside the specs in `<id>/rehearsal.json`, written by the
  * command and never by hand. A scene is *Live* when it `passed`; one that did
  * not says so with `says`.
  */
@@ -210,7 +210,7 @@ export interface SceneDeploymentSpec {
     addresses: Record<string, string>;
 }
 /** Specification for a scene: a team, staged. */
-/** Somebody on a scripted scene: a person, an application, a company (PAP_DATALAYER X-02). */
+/** Somebody on a scripted scene: a person, an application, a company (X-02). */
 export interface SceneActorSpec {
     id: string;
     /** The name the audience sees. */
@@ -258,7 +258,7 @@ export interface SceneSpec {
     version: string;
     /**
      * `team`: a team staged, live; `scripted`: actors and lines written out,
-     * played as written, with no team, cast or script (PAP_DATALAYER X-02).
+     * played as written, with no team, cast or script (X-02).
      */
     kind: 'team' | 'scripted';
     /** The tab's name. */

package/lib/types/teams.d.ts

@@ -48,7 +48,7 @@ export interface TeamContextSpec {
     sharing: TeamContextSharing;
     /**
      * The Frames every member works under, in order, `id` or `id:version`
-     * (LOOP A-04): the team's shared context, as a Cog names its own.
+     * (A-04): the team's shared context, as a Cog names its own.
      */
     frames?: string[];
 }
@@ -88,13 +88,13 @@ export interface TeamAgentspec {
     /**
      * MCP server catalogue reference, in place of `ref` and `app`: the member
      * is that server, a system of the scene the others reach over MCP
-     * (LOOP A-04). It asks nobody.
+     * (A-04). It asks nobody.
      */
     server?: string;
     /**
      * Harness catalogue id, in place of `ref`, `app` and `server`: the member is
      * that agent program over ACP behind the Shield — Claude Code, Codex, an
-     * organization's own — asked over A2A or ACP (SHIELD SH-45).
+     * organization's own — asked over A2A or ACP (SH-45).
      */
     harness?: string;
     /** Where its loop turns: in the person's `browser`, or on a `runtime`. */

package/lib/ui-plugins/MCPUIPlugin.d.ts

@@ -2,7 +2,7 @@
  * MCP-UI plugin for chat component.
  * Renders MCP UI protocol messages and resources.
  *
- * What it never draws (STUDIO D-22): the markup of a resource (`text/html`)
+ * What it never draws (D-22): the markup of a resource (`text/html`)
  * and a UI element built from a tool's props. Either is markup a server or a
  * model supplies, and the chat may sit on the platform's origin, where people
  * are signed in: each is refused in a sentence, in place, with no fallback.
@@ -53,7 +53,7 @@ export interface MCPUIMessage {
     };
 }
 /**
- * What the chat says in place of the MCP UI's markup (STUDIO D-22).
+ * What the chat says in place of the MCP UI's markup (D-22).
  */
 export declare const MCP_UI_NOT_DRAWN: {
     readonly html: "This answer carries a page of HTML from its MCP server. It is not drawn here: no markup from a server or a model reaches this page.";

package/lib/ui-plugins/MCPUIPlugin.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
- * What the chat says in place of the MCP UI's markup (STUDIO D-22).
+ * What the chat says in place of the MCP UI's markup (D-22).
  */
 export const MCP_UI_NOT_DRAWN = {
     html: 'This answer carries a page of HTML from its MCP server. It is not drawn here: no markup from a server or a model reaches this page.',

package/lib/voice/ComposerVoice.d.ts

@@ -1,6 +1,6 @@
 /**
- * The microphone of a composer whose text its host holds (VOICE.md VO-10,
- * VO-11): `ChatBase`'s own, and the workspace's (an application's page,
+ * The microphone of a composer whose text its host holds (VO-10, VO-11):
+ * `ChatBase`'s own, and the workspace's (an application's page,
  * whose composer is a plugin of its own). What the box held when the
  * microphone opened stays; the words heard go after it as they come, and the
  * whole of what was heard replaces them once it stops. Put there for the
@@ -31,6 +31,8 @@ export interface ComposerVoiceProps {
     speaking?: boolean;
     /** Stops the agent's voice, also when the microphone opens (VO-13). */
     onStopSpeaking?: () => void;
+    /** How loud the agent's voice plays now, 0 to 1: hands-free's barge-in is gated on it (VO-13). */
+    playbackLevel?: () => number;
     /** The agent is answering: a run is in progress (hands-free, VO-12). */
     running?: boolean;
     /** Stops the run while the answer is still being written (barge-in, VO-13). */
@@ -50,5 +52,5 @@ export interface ComposerVoiceProps {
 }
 /** Whether something rides on a run as a spoken message's metadata (VO-27). */
 export declare function spokenOf(value: unknown): SpokenMetadata | undefined;
-export declare function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled, speaking, onStopSpeaking, running, onStopRun, onInterrupted, onInterimChange, answers, }: ComposerVoiceProps): JSX.Element | null;
+export declare function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled, speaking, onStopSpeaking, playbackLevel, running, onStopRun, onInterrupted, onInterimChange, answers, }: ComposerVoiceProps): JSX.Element | null;
 export default ComposerVoice;

package/lib/voice/ComposerVoice.js

@@ -15,9 +15,9 @@ export function spokenOf(value) {
         ? said
         : undefined;
 }
-export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled = false, speaking = false, onStopSpeaking, running = false, onStopRun, onInterrupted, onInterimChange, answers = false, }) {
+export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled = false, speaking = false, onStopSpeaking, playbackLevel, running = false, onStopRun, onInterrupted, onInterimChange, answers = false, }) {
     // 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).
+    // language or the person's detection asks for it (VO-14, VO-34).
     const place = hearingPlace(voice);
     const hearing = useMemo(() => {
         if (voice.input === 'off') {
@@ -31,7 +31,7 @@ export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled
                 detect: voice.detect,
             })
             : undefined;
-        // `where: auto` (§5): the device when it hears the language and its model
+        // `where: auto`: the device when it hears the language and its model
         // loads, the server otherwise — and back to the device when the server
         // refuses (a visitor's day spent).
         if (server && !voice.detect && (voice.where ?? 'auto') === 'auto') {
@@ -55,7 +55,7 @@ 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, 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', 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) => {

package/lib/voice/HandsFree.d.ts

@@ -1,6 +1,6 @@
 /**
- * *Talk with it*: a conversation by voice, hands-free (VOICE.md VO-12,
- * VO-13), beside the composer's microphone where the application's voice
+ * *Talk with it*: a conversation by voice, hands-free (VO-12, VO-13),
+ * beside the composer's microphone where the application's voice
  * says `input: hands_free`.
  *
  * On, the microphone stays open. The words are written in the composer as
@@ -43,6 +43,12 @@ export interface HandsFreeProps {
     running?: boolean;
     /** The agent's answer is being said. */
     speaking?: boolean;
+    /**
+     * How loud the agent's voice plays now, between 0 and 1 (the speaker's
+     * `level`): while it speaks, speech counts as barge-in only above what the
+     * playback can leave in the microphone (VO-13, `heardOverPlayback`).
+     */
+    playbackLevel?: () => number;
     /** Stops the agent's voice at once (barge-in, VO-13). */
     onStopSpeaking?: () => void;
     /** Stops the run while the answer is still being written (barge-in, VO-13). */
@@ -51,5 +57,5 @@ export interface HandsFreeProps {
     onInterrupted?: () => void;
     disabled?: boolean;
 }
-export declare function HandsFree({ hearing, language, consentKey, microphoneId, turnSilenceMs, send, onInterim, running, speaking, onStopSpeaking, onStopRun, onInterrupted, disabled, }: HandsFreeProps): JSX.Element;
+export declare function HandsFree({ hearing, language, consentKey, microphoneId, turnSilenceMs, send, onInterim, running, speaking, playbackLevel, onStopSpeaking, onStopRun, onInterrupted, disabled, }: HandsFreeProps): JSX.Element;
 export default HandsFree;

package/lib/voice/HandsFree.js

@@ -8,7 +8,7 @@ import { HANDS_FREE_WORDS, IDLE_PAUSE_MS, TURN_SILENCE_MS, bargedIn, handsFreeSt
 import { INTERIM_MS } from './VoiceInput';
 /** 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, onStopSpeaking, onStopRun, onInterrupted, disabled = false, }) {
+export function HandsFree({ hearing, language, consentKey, 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);
@@ -22,6 +22,7 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
     const latest = useRef({
         send,
         onInterim,
+        playbackLevel,
         onStopSpeaking,
         onStopRun,
         onInterrupted,
@@ -29,6 +30,7 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
     latest.current = {
         send,
         onInterim,
+        playbackLevel,
         onStopSpeaking,
         onStopRun,
         onInterrupted,
@@ -118,7 +120,11 @@ export function HandsFree({ hearing, language, consentKey, microphoneId, turnSil
                 if (so.spoke) {
                     quietSince = Date.now();
                 }
-                if (bargedIn(now, so)) {
+                const playing = latest.current.playbackLevel;
+                const levels = playing
+                    ? { microphone: open.level(), playback: playing() }
+                    : undefined;
+                if (bargedIn(now, so, levels)) {
                     // The person speaks over the agent (VO-13): its voice and its run
                     // stop; what was heard goes on as the next turn.
                     latest.current.onStopSpeaking?.();
@@ -173,7 +179,6 @@ 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.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [on, paused, hearing, language, microphoneId, turnSilenceMs]);
     // Esc pauses it.
     useEffect(() => {

package/lib/voice/ReadAloud.d.ts

@@ -1,5 +1,5 @@
 /**
- * *Read aloud*, under an answer (VOICE.md VO-21, `on_request`): the answer,
+ * *Read aloud*, under an answer (VO-21, `on_request`): the answer,
  * read as plain words and cut into sentences, given to the speaker — what it
  * was saying stops first. The press is the gesture a browser plays sound
  * after.

package/lib/voice/VoiceInput.d.ts

@@ -1,6 +1,5 @@
 /**
- * The microphone in the composer (VOICE.md VO-10, VO-11, VO-61, VO-62, VO-65
- * to VO-68).
+ * The microphone in the composer (VO-10, VO-11, VO-61, VO-62, VO-65 to VO-68).
  *
  * Clicked, it listens: the words are written in the composer as they are
  * heard (`onInterim`), and it stops at a second click, or once the person

package/lib/voice/VoiceMenu.d.ts

@@ -1,5 +1,5 @@
 /**
- * The composer's voice menu (VOICE.md VO-14, VO-21, VO-25, VO-30): beside
+ * The composer's voice menu (VO-14, VO-21, VO-25, VO-30): beside
  * the microphone, what a person chooses for themselves — the language they
  * speak and hear, when answers are heard, the voice, its speed and loudness,
  * how long they pause before they are done (VO-69), *Send what I say*, the

package/lib/voice/captions.d.ts

@@ -1,5 +1,5 @@
 /**
- * Captions always (VOICE.md VO-65): the sentence being said is marked in the
+ * Captions always (VO-65): the sentence being said is marked in the
  * open conversation, not by colour alone. The answer that holds it is marked
  * `aria-current` and `data-voice-saying` with a bar beside it; the sentence
  * itself is underlined in place through the CSS Custom Highlight API, which

package/lib/voice/captions.js

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Captions always (VOICE.md VO-65): the sentence being said is marked in the
+ * Captions always (VO-65): the sentence being said is marked in the
  * open conversation, not by colour alone. The answer that holds it is marked
  * `aria-current` and `data-voice-saying` with a bar beside it; the sentence
  * itself is underlined in place through the CSS Custom Highlight API, which

package/lib/voice/capture.d.ts

@@ -1,5 +1,5 @@
 /**
- * The microphone, for one press (VOICE.md VO-10, VO-62): opened by a
+ * The microphone, for one press (VO-10, VO-62): opened by a
  * gesture, shown while open, closed when the press ends or is cancelled.
  * What it heard is kept in memory only, until it is transcribed.
  *

package/lib/voice/capture.js

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * The microphone, for one press (VOICE.md VO-10, VO-62): opened by a
+ * The microphone, for one press (VO-10, VO-62): opened by a
  * gesture, shown while open, closed when the press ends or is cancelled.
  * What it heard is kept in memory only, until it is transcribed.
  *

package/lib/voice/chatVoice.d.ts

@@ -46,7 +46,7 @@ export declare function chatVoiceOf(spec: AppVoiceSpec | undefined, place: ChatV
  * 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. 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
+ * An embed's deployment is the one its token names: the page
  * says none.
  */
 export declare function voiceAskedAs(voice: ChatVoice | undefined, token: string | undefined): ChatVoice | undefined;

package/lib/voice/chatVoice.js

@@ -3,8 +3,8 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * A chat's voice, from what an application or an agent says of it (VOICE.md
- * VO-41, VO-49): the `voice` a host gives `ChatBase`, `ChatFloating` or an
+ * A chat's voice, from what an application or an agent says of it (VO-41, VO-49):
+ * the `voice` a host gives `ChatBase`, `ChatFloating` or an
  * application's workspace, with Datalayer's places filled in — the browser's
  * models from Datalayer's CDN, the packages that hear loaded on first use.
  *
@@ -68,7 +68,7 @@ export function chatVoiceOf(spec, place) {
  * 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. 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
+ * An embed's deployment is the one its token names: the page
  * says none.
  */
 export function voiceAskedAs(voice, token) {

package/lib/voice/choices.d.ts

@@ -1,6 +1,6 @@
 /**
- * What a person may choose for their voice (VOICE.md VO-14, VO-21, VO-25,
- * VO-30), from the catalogue: the languages a voice speaks and the device
+ * What a person may choose for their voice (VO-14, VO-21, VO-25, VO-30),
+ * from the catalogue: the languages a voice speaks and the device
  * hears, the voices of each, the speeds and loudnesses offered, and when
  * answers are heard. Read by the composer's menu (`VoiceMenu`) and by a
  * settings page, so both offer the same.

package/lib/voice/choices.js

@@ -3,8 +3,8 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * What a person may choose for their voice (VOICE.md VO-14, VO-21, VO-25,
- * VO-30), from the catalogue: the languages a voice speaks and the device
+ * What a person may choose for their voice (VO-14, VO-21, VO-25, VO-30),
+ * from the catalogue: the languages a voice speaks and the device
  * hears, the voices of each, the speeds and loudnesses offered, and when
  * answers are heard. Read by the composer's menu (`VoiceMenu`) and by a
  * settings page, so both offer the same.

package/lib/voice/consent.js

@@ -4,7 +4,7 @@
  */
 /**
  * The person's yes to the microphone, asked once per application before the
- * browser's own prompt (VOICE.md VO-61), and remembered where the page keeps
+ * browser's own prompt (VO-61), and remembered where the page keeps
  * its preferences. A page without storage asks again next time.
  *
  * @module voice/consent

package/lib/voice/handsFree.d.ts

@@ -1,5 +1,5 @@
 /**
- * A conversation by voice, hands-free (VOICE.md VO-12, VO-13): what the
+ * A conversation by voice, hands-free (VO-12, VO-13): what the
  * composer is doing at every moment, and when a turn ends or the person
  * speaks over the agent. Pure: the component (`HandsFree`) keeps the
  * microphone and the clock, this decides.
@@ -49,13 +49,38 @@ export interface HeardSoFarLike {
  * turn's silence since (VO-12).
  */
 export declare function turnEnded(heard: HeardSoFarLike, turnSilenceMs?: number): boolean;
+/**
+ * At most this share of what plays is taken to come back into the
+ * microphone once the browser's echo cancellation has done its part (VO-13),
+ * on the meters' own scales (the microphone's `Capture.level`, the speaker's
+ * `level`). A setting, not a measure yet: VO-52 measures it on a laptop's
+ * own speakers.
+ */
+export declare const ECHO_SHARE = 0.6;
+/** How far above that echo the person's voice must be, on the meter's scale. */
+export declare const VOICE_OVER_ECHO = 0.08;
+/** How loud the microphone and the agent's voice are now, each between 0 and 1. */
+export interface Levels {
+    microphone: number;
+    playback: number;
+}
+/**
+ * Whether the microphone holds more than the agent's own voice coming back
+ * (VO-13): nothing plays, or the microphone is louder than the echo the
+ * playback can leave by `VOICE_OVER_ECHO`.
+ */
+export declare function heardOverPlayback(levels: Levels, echoShare?: number): boolean;
 /**
  * Whether the person spoke over the agent (VO-13): speech found since the
  * agent began answering, while it thinks or speaks. The microphone is opened
- * anew when the agent begins, so what it holds is the person's, not the
- * answer's echo — the browser's echo cancellation keeps that out.
+ * anew when the agent begins, so what it holds came since; the browser's
+ * echo cancellation keeps most of the answer's sound out, and while the
+ * answer plays the VAD's speech counts only when the microphone is louder
+ * than what the playback can leave in it (`heardOverPlayback`) — when the
+ * levels are known. A host whose speaker gives no level (the browser's own
+ * voices) relies on echo cancellation alone.
  */
-export declare function bargedIn(state: HandsFreeState, heard: HeardSoFarLike): boolean;
+export declare function bargedIn(state: HandsFreeState, heard: HeardSoFarLike, levels?: Levels): boolean;
 /** A message as the conversation holds it: enough to find the answer spoken over. */
 export interface ConversationItemLike {
     id: string;

package/lib/voice/handsFree.js

@@ -37,14 +37,42 @@ export function handsFreeState(inputs) {
 export function turnEnded(heard, turnSilenceMs = TURN_SILENCE_MS) {
     return heard.spoke && heard.silentMs >= turnSilenceMs;
 }
+/**
+ * At most this share of what plays is taken to come back into the
+ * microphone once the browser's echo cancellation has done its part (VO-13),
+ * on the meters' own scales (the microphone's `Capture.level`, the speaker's
+ * `level`). A setting, not a measure yet: VO-52 measures it on a laptop's
+ * own speakers.
+ */
+export const ECHO_SHARE = 0.6;
+/** How far above that echo the person's voice must be, on the meter's scale. */
+export const VOICE_OVER_ECHO = 0.08;
+/**
+ * Whether the microphone holds more than the agent's own voice coming back
+ * (VO-13): nothing plays, or the microphone is louder than the echo the
+ * playback can leave by `VOICE_OVER_ECHO`.
+ */
+export function heardOverPlayback(levels, echoShare = ECHO_SHARE) {
+    if (levels.playback <= 0) {
+        return true;
+    }
+    return levels.microphone >= levels.playback * echoShare + VOICE_OVER_ECHO;
+}
 /**
  * Whether the person spoke over the agent (VO-13): speech found since the
  * agent began answering, while it thinks or speaks. The microphone is opened
- * anew when the agent begins, so what it holds is the person's, not the
- * answer's echo — the browser's echo cancellation keeps that out.
+ * anew when the agent begins, so what it holds came since; the browser's
+ * echo cancellation keeps most of the answer's sound out, and while the
+ * answer plays the VAD's speech counts only when the microphone is louder
+ * than what the playback can leave in it (`heardOverPlayback`) — when the
+ * levels are known. A host whose speaker gives no level (the browser's own
+ * voices) relies on echo cancellation alone.
  */
-export function bargedIn(state, heard) {
-    return (state === 'speaking' || state === 'thinking') && heard.spoke;
+export function bargedIn(state, heard, levels) {
+    if (!(state === 'speaking' || state === 'thinking') || !heard.spoke) {
+        return false;
+    }
+    return state !== 'speaking' || !levels || heardOverPlayback(levels);
 }
 /**
  * The answer the person spoke over (VO-13): the agent's last message after

package/lib/voice/hearing.d.ts

@@ -23,7 +23,7 @@ export interface HeardSoFar {
     silentMs: number;
 }
 /**
- * What hears a press, wherever it runs (§5): in the page (`DeviceHearing`)
+ * What hears a press, wherever it runs: in the page (`DeviceHearing`)
  * or on Datalayer's servers (`ServerHearing`).
  */
 export interface Hearing {

package/lib/voice/hearing.js

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Hearing on the device (VOICE.md VO-10, VO-14, decision 3): what was said
+ * Hearing on the device (VO-10, VO-14): what was said
  * in one press, kept to its speech by Silero VAD and transcribed by the
  * catalogue's model for the language — Moonshine for English, Whisper for
  * French — in the page, with transformers.js. The audio never leaves the