@datalayer/agent-runtimes 1.5.42 → 1.5.44

package/lib/portable/index.js

@@ -27,7 +27,7 @@ export { conversationEventsOf, sanitizeAssistantContent, snapshotOfMessages, } f
 export { PRESENCE_LINES, presenceOfConversation, presenceState, presenceToolOf, } from './presence';
 // One contract for every renderer of a conversation's components.
 export { ANSWER_BELOW, ANSWER_COMPLETE, composerOf, droppedWords, ENDED_WORDS, messageLabel, OPENING_WORDS, presenceLine, showsQuestion, stepLine, TOOL_STATUS_WORDS, toolLabel, } from './views';
-export { conversationFixture } from './fixtures';
+export { activityFixture, conversationFixture } from './fixtures';
 // The protocol displays a run's tool results carry (MOBILE M-037).
 export { DISPLAY_META_KEY, displayLine, displayOfToolResult, PAP_CONFIRM_TYPE, PAP_HANDOFF_TOOL, PAP_OUTCOME_TYPE, PAP_REPLIES_TYPE, PAP_SIGN_IN_TYPE, protocolDisplayOf, replyAuthor, 
 // A coding agent's diff and terminal (SHIELD §4.3, SH-16).
@@ -42,5 +42,11 @@ export { SIGN_IN_POLL_MS, SIGN_IN_STATUS_PATH, signInStandsOf, signInStatusClien
 export { emptyFields, fieldProblems, MAX_VALUE_LENGTH, PROTECTED_INPUT_WORDS, protectedInputClient, protectedRequestOf, ProtectedRequestGone, sentWords, submitBody, submitWords, ticketComplete, ticketOfPage, } from './protectedInput';
 // How a streamed turn went, measured without its words (MOBILE M-036).
 export { failureOf, otlpMetricsOf, RunMeter, } from './runMeasures';
+// What an application is doing, and its record's entries (LOOP R-15, MOBILE M-015b).
+export { ACTIVITY_WORDS, activityOf, entryOf, entrySaid, mergeActivityPages, runEndOf, scheduledSays, sessionSentence, wakesOn, } from './activity';
+// A deployment's pause, resume and reset, and its recorded events (LOOP R-17, MOBILE M-041b).
+export { deploymentEventLine, deploymentEventOf, notDeletedOf, resetBody, resetCountsOf, resetLines, stateChangeBody, stoppedWorkLine, stoppedWorkOf, } from './lifecycle';
+// A person's agent runtimes, and an agent's summary (MOBILE M-014b).
+export { agentRuntimesOf, agentSummaryOfRuntime, CREATING_STATUSES, isAgentRuntime, isCreatingAgent, runtimeOf, } from './runtimes';
 // The runtime's routes a native client drives.
 export { agentRunClient, agentRuntimesUrlOf, appSessionsClient, RuntimeRefusal, } from './sessions';

package/lib/portable/lifecycle.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A deployment's lifecycle as its owner drives it (LOOP R-17, D-04): pause
+ * and resume one exact version, reset what it holds, and the events recorded
+ * with who did each. The requests' bodies, the answers read and the words
+ * said — the same in the Studio and Datalayer Mobile (MOBILE M-041b). Pure:
+ * each client sends them with its own authentication.
+ *
+ * @module portable/lifecycle
+ */
+/** Whether a deployment answers now. */
+export type DeploymentState = 'live' | 'paused';
+/** Pause or resume, for one exact version: `PATCH /apps/deployments/{uid}`'s body. */
+export declare const stateChangeBody: (version: number, state: DeploymentState) => {
+    version: number;
+    state: DeploymentState;
+};
+/** What pausing stopped, and what it could not, with why. */
+export type StoppedWork = {
+    stopped: {
+        what: string;
+        runtime: string;
+    }[];
+    notStopped: {
+        what: string;
+        runtime: string;
+        why: string;
+    }[];
+};
+export declare function stoppedWorkOf(raw: Record<string, unknown>): StoppedWork;
+/** What pausing did, in a sentence. */
+export declare function stoppedWorkLine(work: StoppedWork): string;
+/** What a Reset deletes, counted for its confirmation. */
+export type ResetCounts = {
+    conversations: number;
+    entries: number;
+    schedules: number;
+    /**
+     * Why its memories stay: they are its application's, not the
+     * deployment's (LOOP R-18) — forgotten under *What it remembers*.
+     */
+    memoriesNote: string;
+};
+export declare function resetCountsOf(raw: Record<string, unknown>): ResetCounts;
+/** The Reset confirmed against the counts the person was shown: `POST …/reset`'s body. */
+export declare const resetBody: (counts: Pick<ResetCounts, "conversations" | "schedules">) => {
+    conversations: number;
+    schedules: number;
+};
+/** What a Reset could not delete, with why: `POST …/reset`'s answer. */
+export declare function notDeletedOf(body: Record<string, unknown>): {
+    what: string;
+    why: string;
+}[];
+/**
+ * What goes, as the confirmation lists it — "12 conversations, 2
+ * schedules" — and what does not, said apart.
+ */
+export declare function resetLines(counts: ResetCounts): {
+    goes: string;
+    stays: string[];
+};
+/** What happened to a deployment, recorded with who did it (D-04, R-17). */
+export type DeploymentEventKind = 'promoted' | 'rolled_back' | 'paused' | 'resumed' | 'reset';
+/** Who promoted, rolled back, paused, resumed or reset a deployment, and when. */
+export type DeploymentEvent = {
+    uid: string;
+    kind: DeploymentEventKind;
+    actor: string;
+    at: string;
+    details: Record<string, unknown>;
+};
+export declare function deploymentEventOf(raw: Record<string, unknown>): DeploymentEvent;
+/**
+ * One event, in a line: "Paused by eric, 4 Oct 2026, 10:12", "Rolled back
+ * from version 3 to version 2 by eric, …".
+ */
+export declare function deploymentEventLine(event: DeploymentEvent, locale?: string): string;

package/lib/portable/lifecycle.js

@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Pause or resume, for one exact version: `PATCH /apps/deployments/{uid}`'s body. */
+export const stateChangeBody = (version, state) => {
+    if (!Number.isInteger(version) || version < 1) {
+        throw new Error(`A deployment's state is changed for one exact version: ${String(version)} is none.`);
+    }
+    return { version, state };
+};
+const listOf = (raw) => Array.isArray(raw)
+    ? raw.filter(item => item && typeof item === 'object')
+    : [];
+const said = (value) => typeof value === 'string' ? value : value == null ? '' : String(value);
+const count = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+};
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+export function stoppedWorkOf(raw) {
+    return {
+        stopped: listOf(raw.stopped).map(item => ({
+            what: said(item.what),
+            runtime: said(item.runtime),
+        })),
+        notStopped: listOf(raw.not_stopped).map(item => ({
+            what: said(item.what),
+            runtime: said(item.runtime),
+            why: said(item.why),
+        })),
+    };
+}
+/** What pausing did, in a sentence. */
+export function stoppedWorkLine(work) {
+    const stopped = work.stopped.length;
+    const first = stopped === 0
+        ? 'Paused: nothing was running.'
+        : `Paused: ${plural(stopped, 'session')} in progress stopped.`;
+    if (!work.notStopped.length) {
+        return first;
+    }
+    const missed = work.notStopped
+        .map(item => `${item.what}${item.runtime ? ` (${item.runtime})` : ''}: ${item.why}`)
+        .join(' ');
+    return `${first} Not stopped — ${missed}`;
+}
+export function resetCountsOf(raw) {
+    return {
+        conversations: count(raw.conversations),
+        entries: count(raw.entries),
+        schedules: count(raw.schedules),
+        memoriesNote: typeof raw.memories_note === 'string' ? raw.memories_note : '',
+    };
+}
+/** The Reset confirmed against the counts the person was shown: `POST …/reset`'s body. */
+export const resetBody = (counts) => ({
+    conversations: counts.conversations,
+    schedules: counts.schedules,
+});
+/** What a Reset could not delete, with why: `POST …/reset`'s answer. */
+export function notDeletedOf(body) {
+    return listOf(body.not_deleted).map(item => ({
+        what: said(item.what),
+        why: said(item.why),
+    }));
+}
+/**
+ * What goes, as the confirmation lists it — "12 conversations, 2
+ * schedules" — and what does not, said apart.
+ */
+export function resetLines(counts) {
+    return {
+        goes: [
+            plural(counts.conversations, 'conversation'),
+            plural(counts.schedules, 'schedule'),
+        ].join(', '),
+        stays: [
+            'The deployment, its address and the version it runs stay.',
+            ...(counts.memoriesNote ? [counts.memoriesNote] : []),
+        ],
+    };
+}
+const EVENT_KINDS = [
+    'promoted',
+    'rolled_back',
+    'paused',
+    'resumed',
+    'reset',
+];
+export function deploymentEventOf(raw) {
+    if (!EVENT_KINDS.includes(raw.kind)) {
+        throw new Error(`A deployment's event of no known kind: ${String(raw.kind)}.`);
+    }
+    return {
+        uid: said(raw.uid),
+        kind: raw.kind,
+        actor: said(raw.actor_handle || raw.actor_uid || ''),
+        at: typeof raw.at === 'string' ? raw.at : '',
+        details: raw.details && typeof raw.details === 'object'
+            ? raw.details
+            : {},
+    };
+}
+/**
+ * One event, in a line: "Paused by eric, 4 Oct 2026, 10:12", "Rolled back
+ * from version 3 to version 2 by eric, …".
+ */
+export function deploymentEventLine(event, locale) {
+    const from = count(event.details.from);
+    const to = count(event.details.to);
+    const moved = from && to ? ` from version ${from} to version ${to}` : '';
+    const verb = {
+        promoted: `Promoted${moved}`,
+        rolled_back: `Rolled back${moved}`,
+        paused: 'Paused',
+        resumed: 'Resumed',
+        reset: 'Reset',
+    }[event.kind];
+    const when = event.at
+        ? new Date(event.at).toLocaleString(locale, {
+            dateStyle: 'medium',
+            timeStyle: 'short',
+        })
+        : '';
+    const deleted = event.details.deleted;
+    const what = event.kind === 'reset' && deleted
+        ? ` — ${plural(count(deleted.conversations), 'conversation')} and ${plural(count(deleted.schedules), 'schedule')} deleted`
+        : '';
+    // Paused by an owner of its owner's organization (I-09): said as such.
+    const forOrganization = event.kind === 'paused' && event.details.by === 'organization_owner'
+        ? ', an owner of your organization'
+        : '';
+    return `${verb}${event.actor ? ` by ${event.actor}${forOrganization}` : ''}${when ? `, ${when}` : ''}${what}`;
+}

package/lib/portable/runtimes.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A person's agent runtimes as the runtimes service lists them
+ * (`GET /api/runtimes/v1/runtimes`), and an agent's summary and status as
+ * every client says them — the web's `AgentSummary` badge and Datalayer
+ * Mobile's Agents (MOBILE M-014b). A raw runtime carries no application
+ * capabilities: no Rules, Protocols or Activity are read from it.
+ *
+ * @module portable/runtimes
+ */
+/** One agent runtime, as a client lists it. */
+export type AgentRuntime = {
+    uid: string;
+    runtimeName: string;
+    givenName: string;
+    environment: string;
+    /** The agentspec it runs, when the runtime says. */
+    agentSpecId: string;
+    type: string;
+    state: string;
+    startedAt: string;
+    expiredAt: string;
+    /** Its Jupyter address, from which its agents' is read (`agentRuntimesUrlOf`). */
+    ingress: string;
+};
+/** A runtime of the runtimes service's answer. */
+export declare function runtimeOf(raw: Record<string, unknown>): AgentRuntime;
+/** The runtimes service's list, agent runtimes only: notebooks and terminals belong to the web workspace. */
+export declare function agentRuntimesOf(body: Record<string, unknown>): AgentRuntime[];
+/** An agent runtime, not a notebook's or a terminal's. */
+export declare const isAgentRuntime: (runtime: AgentRuntime) => boolean;
+/** What a summary of an agent says of it. */
+export interface AgentSummaryData {
+    agentName: string;
+    location: string;
+    specId?: string;
+    /**
+     * The framework turning this agent's loop, as its spec declares it —
+     * `pydantic-ai` server-side, `vercel-ai` in the page.
+     */
+    harness?: string;
+    /**
+     * The runtime variant the host chose: `<location>-<harness>`.
+     *
+     * Shown next to the harness rather than instead of it, because they answer
+     * different questions and can disagree: the harness is what the spec asked
+     * for, the variant is what it actually got.
+     */
+    variant?: string;
+    status?: string;
+    baseUrl?: string;
+    sandboxBaseUrl?: string;
+    agentId?: string;
+    isReady?: boolean;
+    error?: string;
+}
+/**
+ * Statuses that represent an agent actively being created/started. The spinner
+ * only shows for these; app-navigation states ("selected", "switching") and
+ * settled states ("ready", "running", ...) never spin.
+ */
+export declare const CREATING_STATUSES: ReadonlySet<string>;
+/**
+ * An agent genuinely being created: it is not ready, has no id yet, and its
+ * status is one of creation or startup.
+ */
+export declare function isCreatingAgent(summary: AgentSummaryData): boolean;
+/** The summary of an agent the runtimes service lists: named as given, at Datalayer. */
+export declare function agentSummaryOfRuntime(runtime: AgentRuntime): AgentSummaryData;

package/lib/portable/runtimes.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const text = (value) => typeof value === 'string' ? value : '';
+/** A runtime of the runtimes service's answer. */
+export function runtimeOf(raw) {
+    const environment = isRecord(raw.environment) ? raw.environment : {};
+    return {
+        uid: text(raw.uid),
+        runtimeName: text(raw.runtime_name) || text(raw.pod_name),
+        givenName: text(raw.given_name),
+        environment: text(environment.title) ||
+            text(environment.name) ||
+            text(raw.environment_title) ||
+            text(raw.environment_name),
+        agentSpecId: text(raw.agent_spec_id) || text(raw.attached_agent_spec_id_s),
+        type: text(raw.type),
+        state: text(raw.state) || text(raw.status) || 'running',
+        startedAt: text(raw.started_at),
+        expiredAt: text(raw.expired_at),
+        ingress: text(raw.ingress),
+    };
+}
+/** The runtimes service's list, agent runtimes only: notebooks and terminals belong to the web workspace. */
+export function agentRuntimesOf(body) {
+    const listed = Array.isArray(body.runtimes) ? body.runtimes : [];
+    return listed
+        .filter(isRecord)
+        .map(runtimeOf)
+        .filter(runtime => runtime.runtimeName && isAgentRuntime(runtime));
+}
+/** An agent runtime, not a notebook's or a terminal's. */
+export const isAgentRuntime = (runtime) => runtime.type === 'agent' ||
+    Boolean(runtime.agentSpecId) ||
+    /agent/i.test(runtime.environment);
+/**
+ * Statuses that represent an agent actively being created/started. The spinner
+ * only shows for these; app-navigation states ("selected", "switching") and
+ * settled states ("ready", "running", ...) never spin.
+ */
+export const CREATING_STATUSES = new Set([
+    'creating',
+    'starting',
+    'launching',
+    'connecting',
+    'pending',
+    'resuming',
+]);
+/**
+ * An agent genuinely being created: it is not ready, has no id yet, and its
+ * status is one of creation or startup.
+ */
+export function isCreatingAgent(summary) {
+    return (!summary.isReady &&
+        !summary.agentId &&
+        CREATING_STATUSES.has((summary.status || '').toLowerCase()));
+}
+/** The summary of an agent the runtimes service lists: named as given, at Datalayer. */
+export function agentSummaryOfRuntime(runtime) {
+    return {
+        agentName: runtime.givenName || runtime.runtimeName,
+        location: 'datalayer',
+        specId: runtime.agentSpecId || undefined,
+        status: runtime.state,
+        isReady: !CREATING_STATUSES.has(runtime.state.toLowerCase()),
+    };
+}

package/lib/voice/VoiceMenu.d.ts

@@ -2,7 +2,8 @@
  * The composer's voice menu (VOICE.md VO-14, VO-21, VO-25, VO-30): beside
  * the microphone, what a person chooses for themselves — the language they
  * speak and hear, when answers are heard, the voice, its speed and loudness,
- * *Send what I say*, the microphone, and *Keep speech on this device*. Each
+ * how long they pause before they are done (VO-69), *Send what I say*, the
+ * microphone, and *Keep speech on this device*. Each
  * choice is kept in the person's settings and heard at once by every chat
  * on the page; *Use the application's* forgets them all.
  *

package/lib/voice/VoiceMenu.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useState } from 'react';
 import { ActionList, ActionMenu, IconButton } from '@primer/react';
 import { GearIcon } from '@primer/octicons-react';
-import { OUTPUT_CHOICES, RATE_CHOICES, VOLUME_CHOICES, catalogueVoiceSpeaks, voiceLanguages, voicesSpeaking, } from './choices';
+import { OUTPUT_CHOICES, PAUSE_CHOICES, RATE_CHOICES, VOLUME_CHOICES, catalogueVoiceSpeaks, voiceLanguages, voicesSpeaking, } from './choices';
 import { withVoiceSetting } from './settings';
 import { useVoiceSettings } from './useVoiceSettings';
 /** The microphones the browser lists; named only once one was allowed. */
@@ -28,6 +28,6 @@ export function VoiceMenu({ voice, answers, disabled = false, }) {
                 void microphones().then(setDevices);
             }
         }, children: [_jsx(ActionMenu.Anchor, { children: _jsx(IconButton, { icon: GearIcon, size: "small", variant: "invisible", "aria-label": "Voice settings", "data-voice-menu": "", disabled: disabled }) }), _jsx(ActionMenu.Overlay, { width: "medium", children: _jsxs(ActionList, { children: [_jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Language" }), voiceLanguages().map(language => (_jsx(ActionList.Item, { selected: language.value === voice.language, onSelect: () => choose('language', language.value), "data-voice-language": language.value, children: language.label }, language.value)))] }), answers && !onDevice ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Answers heard" }), OUTPUT_CHOICES.map(output => (_jsx(ActionList.Item, { selected: output.value === voice.output, onSelect: () => choose('output', output.value), "data-voice-output": output.value, children: output.label }, output.value)))] }), voices.length > 0 ? (_jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Voice" }), voices.map(spoken => (_jsx(ActionList.Item, { selected: spoken.id === voice.voice, onSelect: () => choose('voice', spoken.id), "data-voice-voice": spoken.id, children: spoken.name }, spoken.id)))] })) : null, _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Speed" }), RATE_CHOICES.map(rate => (_jsx(ActionList.Item, { selected: rate.value === (voice.rate ?? 1), onSelect: () => choose('rate', rate.value), "data-voice-rate": rate.value, children: rate.label }, rate.value)))] }), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Loudness" }), VOLUME_CHOICES.map(volume => (_jsx(ActionList.Item, { selected: volume.value === (voice.volume ?? 1), onSelect: () => choose('volume', volume.value), "data-voice-volume": volume.value, children: volume.label }, volume.value)))] })] })) : null, named.length > 1 ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Microphone" }), named.map(device => (_jsx(ActionList.Item, { selected: device.deviceId ===
-                                                (voice.microphoneId ?? named[0].deviceId), onSelect: () => choose('microphoneId', device.deviceId), "data-voice-microphone": device.deviceId, children: device.label }, device.deviceId)))] })] })) : null, _jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "multiple", children: [_jsxs(ActionList.Item, { selected: Boolean(voice.sendWhatISay), onSelect: () => choose('sendWhatISay', !voice.sendWhatISay), "data-voice-send-what-i-say": "", children: ["Send what I say", _jsx(ActionList.Description, { variant: "block", children: "Sent as soon as it is heard, not left in the box." })] }), voice.speechUrl && !onDevice ? (_jsxs(ActionList.Item, { selected: detect, onSelect: () => choose('detectLanguage', !detect), "data-voice-detect": "", children: ["Detect the language I speak", _jsx(ActionList.Description, { variant: "block", children: "Heard on Datalayer\u2019s servers by Whisper, which finds the language; nothing is kept there." })] })) : null, _jsxs(ActionList.Item, { selected: onDevice, onSelect: () => choose('onDeviceOnly', !onDevice), "data-voice-on-device": "", children: ["Keep speech on this device", _jsx(ActionList.Description, { variant: "block", children: "Nothing is sent to Datalayer\u2019s speech service: you are heard in the browser, answers are not spoken." })] })] }), Object.keys(settings).length > 0 ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsx(ActionList.Item, { onSelect: () => keep({}), "data-voice-settings-reset": "", children: "Use the application\u2019s" })] })) : null] }) })] }));
+                                                (voice.microphoneId ?? named[0].deviceId), onSelect: () => choose('microphoneId', device.deviceId), "data-voice-microphone": device.deviceId, children: device.label }, device.deviceId)))] })] })) : null, _jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Pauses before I am done" }), PAUSE_CHOICES.map(pause => (_jsx(ActionList.Item, { selected: pause.value === (settings.pause ?? 1), onSelect: () => choose('pause', pause.value === 1 ? undefined : pause.value), "data-voice-pause": pause.value, children: pause.label }, pause.value)))] }), _jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "multiple", children: [_jsxs(ActionList.Item, { selected: Boolean(voice.sendWhatISay), onSelect: () => choose('sendWhatISay', !voice.sendWhatISay), "data-voice-send-what-i-say": "", children: ["Send what I say", _jsx(ActionList.Description, { variant: "block", children: "Sent as soon as it is heard, not left in the box." })] }), voice.speechUrl && !onDevice ? (_jsxs(ActionList.Item, { selected: detect, onSelect: () => choose('detectLanguage', !detect), "data-voice-detect": "", children: ["Detect the language I speak", _jsx(ActionList.Description, { variant: "block", children: "Heard on Datalayer\u2019s servers by Whisper, which finds the language; nothing is kept there." })] })) : null, _jsxs(ActionList.Item, { selected: onDevice, onSelect: () => choose('onDeviceOnly', !onDevice), "data-voice-on-device": "", children: ["Keep speech on this device", _jsx(ActionList.Description, { variant: "block", children: "Nothing is sent to Datalayer\u2019s speech service: you are heard in the browser, answers are not spoken." })] })] }), Object.keys(settings).length > 0 ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsx(ActionList.Item, { onSelect: () => keep({}), "data-voice-settings-reset": "", children: "Use the application\u2019s" })] })) : null] }) })] }));
 }
 export default VoiceMenu;

package/lib/voice/chatVoice.d.ts

@@ -59,7 +59,10 @@ export declare const SILENCE_MS = 1500;
  * in: the person's own settings first where they made some (`voiceForPerson`:
  * their language, voice, rate, volume, microphone; VO-14, VO-25, VO-30),
  * else the host's; answers not heard, the language's first voice,
- * Datalayer's models and packages, a silence of 1.5 s. Answers heard need
- * the speech service's address: refused without.
+ * Datalayer's models and packages, a silence of 1.5 s. A person who pauses
+ * longer before they are done has both silences — the one that stops a
+ * microphone clicked on, and the one that ends a hands-free turn — made
+ * longer by their choice (`pause`, VO-69). Answers heard need the speech
+ * service's address: refused without.
  */
 export declare function settledVoice(given: ChatVoice, person?: VoiceSettings): SettledVoice;

package/lib/voice/chatVoice.js

@@ -11,7 +11,8 @@
  * @module voice/chatVoice
  */
 import { voiceFor } from '../specs/voices';
-import { heldVoiceSettings, voiceForPerson, } from './settings';
+import { TURN_SILENCE_MS } from './handsFree';
+import { heldVoiceSettings, saneVoiceSettings, voiceForPerson, } from './settings';
 /**
  * Datalayer's origin for the browser's speech models, as pinned
  * (`s3://datalayer-models-speech` behind its CDN; VO-48, VO-49): each model
@@ -84,11 +85,15 @@ export const SILENCE_MS = 1500;
  * in: the person's own settings first where they made some (`voiceForPerson`:
  * their language, voice, rate, volume, microphone; VO-14, VO-25, VO-30),
  * else the host's; answers not heard, the language's first voice,
- * Datalayer's models and packages, a silence of 1.5 s. Answers heard need
- * the speech service's address: refused without.
+ * Datalayer's models and packages, a silence of 1.5 s. A person who pauses
+ * longer before they are done has both silences — the one that stops a
+ * microphone clicked on, and the one that ends a hands-free turn — made
+ * longer by their choice (`pause`, VO-69). Answers heard need the speech
+ * service's address: refused without.
  */
 export function settledVoice(given, person = heldVoiceSettings()) {
     const voice = voiceForPerson(given, person);
+    const pause = saneVoiceSettings(person).pause ?? 1;
     const output = voice.output ?? 'off';
     if (output !== 'off' && !voice.speechUrl) {
         throw new Error(`A chat whose answers are heard (${output}) names the speech service: its speechUrl is missing.`);
@@ -99,6 +104,7 @@ export function settledVoice(given, person = heldVoiceSettings()) {
         voice: voice.voice || voiceFor(voice.language)?.id || '',
         modelsUrl: voice.modelsUrl || DATALAYER_SPEECH_MODELS_URL,
         engines: voice.engines ?? DATALAYER_VOICE_ENGINES,
-        silenceMs: voice.silenceMs ?? SILENCE_MS,
+        silenceMs: Math.round((voice.silenceMs ?? SILENCE_MS) * pause),
+        turnSilenceMs: Math.round((voice.turnSilenceMs ?? TURN_SILENCE_MS) * pause),
     };
 }

package/lib/voice/choices.d.ts

@@ -28,6 +28,8 @@ export declare function catalogueVoiceSpeaks(voice: string, language: string): b
 /** The speeds offered, as multipliers of the voice's own. */
 export declare const RATE_CHOICES: VoiceChoice<number>[];
 /** The loudnesses offered, 0 to 1. */
+/** How long the person pauses before they are done (VO-69): the silences, times this. */
+export declare const PAUSE_CHOICES: VoiceChoice<number>[];
 export declare const VOLUME_CHOICES: VoiceChoice<number>[];
 /** When answers are heard (VO-21): what a person may choose where the application speaks. */
 export declare const OUTPUT_CHOICES: VoiceChoice<NonNullable<ChatVoice['output']>>[];

package/lib/voice/choices.js

@@ -56,6 +56,12 @@ export const RATE_CHOICES = [
     { value: 1.5, label: 'Fastest' },
 ];
 /** The loudnesses offered, 0 to 1. */
+/** How long the person pauses before they are done (VO-69): the silences, times this. */
+export const PAUSE_CHOICES = [
+    { value: 1, label: 'Usual' },
+    { value: 2, label: 'Longer' },
+    { value: 3, label: 'Much longer' },
+];
 export const VOLUME_CHOICES = [
     { value: 0.25, label: 'Quiet' },
     { value: 0.5, label: 'Half' },

package/lib/voice/index.d.ts

@@ -14,6 +14,7 @@ export * from './pinned';
 export * from './capture';
 export * from './hearing';
 export * from './serverHearing';
+export * from './sayAloud';
 export * from './handsFree';
 export { HandsFree, type HandsFreeProps } from './HandsFree';
 export * from './speaker';

package/lib/voice/index.js

@@ -8,6 +8,7 @@ export * from './pinned';
 export * from './capture';
 export * from './hearing';
 export * from './serverHearing';
+export * from './sayAloud';
 export * from './handsFree';
 export { HandsFree } from './HandsFree';
 export * from './speaker';

package/lib/voice/sayAloud.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What only the runtime knows of voice, as it says it over AG-UI (VOICE.md
+ * VO-35) and Vercel AI (VO-36): `voice.settings` — the running application's
+ * voice and language, at a run's start — and `voice.say` — a short line the
+ * agent wants heard and not written (*One moment*), shown as a caption while
+ * it is said. The chat reads `voice.say` from a run's custom events
+ * (`CUSTOM`, the chat's `activity`) or data parts (`data-voice.say`); it
+ * already knows its application's voice from `/apps/configure` (VO-45), and
+ * `voice.settings` is for clients that do not ask it.
+ *
+ * @module voice/sayAloud
+ */
+/** A line the agent wants heard, not written. */
+export declare const VOICE_SAY_EVENT = "voice.say";
+/** The running application's voice, at a run's start. */
+export declare const VOICE_SETTINGS_EVENT = "voice.settings";
+/** The longest line said aloud: the runtime refuses longer ones. */
+export declare const SAY_ALOUD_MAX_CHARACTERS = 200;
+/** A custom event or data part, as the chat's adapters give it. */
+export interface VoiceActivity {
+    type: string;
+    data: unknown;
+}
+/** The line a `voice.say` says, or `undefined` for anything else. */
+export declare function lineToSay(activity: VoiceActivity): string | undefined;

package/lib/voice/sayAloud.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What only the runtime knows of voice, as it says it over AG-UI (VOICE.md
+ * VO-35) and Vercel AI (VO-36): `voice.settings` — the running application's
+ * voice and language, at a run's start — and `voice.say` — a short line the
+ * agent wants heard and not written (*One moment*), shown as a caption while
+ * it is said. The chat reads `voice.say` from a run's custom events
+ * (`CUSTOM`, the chat's `activity`) or data parts (`data-voice.say`); it
+ * already knows its application's voice from `/apps/configure` (VO-45), and
+ * `voice.settings` is for clients that do not ask it.
+ *
+ * @module voice/sayAloud
+ */
+/** A line the agent wants heard, not written. */
+export const VOICE_SAY_EVENT = 'voice.say';
+/** The running application's voice, at a run's start. */
+export const VOICE_SETTINGS_EVENT = 'voice.settings';
+/** The longest line said aloud: the runtime refuses longer ones. */
+export const SAY_ALOUD_MAX_CHARACTERS = 200;
+const nameOf = (type) => type.replace(/^data-/, '');
+/** The line a `voice.say` says, or `undefined` for anything else. */
+export function lineToSay(activity) {
+    if (nameOf(activity.type) !== VOICE_SAY_EVENT) {
+        return undefined;
+    }
+    const data = activity.data;
+    const text = data && typeof data.text === 'string'
+        ? data.text.split(/\s+/).join(' ').trim()
+        : '';
+    return text ? text.slice(0, SAY_ALOUD_MAX_CHARACTERS) : undefined;
+}

package/lib/voice/serverHearing.d.ts

@@ -2,6 +2,12 @@ import type { Hearing, HearingProgress, HeardSoFar } from './hearing';
 import type { Transcript } from './types';
 /** Where the speech service hears a recording, on ai-agents' host. */
 export declare const TRANSCRIPTIONS_PATH = "/api/ai-agents/v1/speech/transcriptions";
+/** Where the speech service hears speech as it is said. */
+export declare const TRANSCRIPTION_STREAM_PATH = "/api/ai-agents/v1/speech/transcriptions/stream";
+/** A stream no look or hearing has fed for this long is closed: its press was cancelled. */
+export declare const STREAM_IDLE_MS = 3000;
+/** How long the final words of a stream are waited for. */
+export declare const STREAM_FINAL_MS = 60000;
 /** The model the speech service hears with (agentspecs' catalogue). */
 export declare const SERVER_HEARING_MODEL = "whisper-large-v3-turbo";
 /** Where a chat's voice hears: in the browser, or on Datalayer's servers. */
@@ -40,7 +46,26 @@ export interface ServerHearingOptions {
     /** Let Whisper find the language (VO-14), rather than tell it. */
     detect?: boolean;
     fetcher?: typeof fetch;
+    /** Opens a WebSocket; the browser's own unless a test gives one. */
+    socket?: (url: string) => SpeechSocket;
 }
+/** What `ServerHearing` needs of a WebSocket. */
+export interface SpeechSocket {
+    readonly readyState: number;
+    binaryType: string;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    send(data: string | ArrayBuffer): void;
+    close(code?: number): void;
+}
+/** 16 kHz samples in [-1, 1] as little-endian 16-bit PCM: what a `pcm16` stream takes. */
+export declare function pcm16Of(samples: Float32Array): ArrayBuffer;
+/** The ws(s) address of the stream on ai-agents' origin. */
+export declare function streamUrlOf(speechUrl: string): string;
 /**
  * Hears on Datalayer's servers: the browser's VAD finds the speech and when
  * it stopped; Whisper, on the speech service, writes it.
@@ -52,7 +77,14 @@ export declare class ServerHearing implements Hearing {
     constructor(finder: SpeechFinder, options: ServerHearingOptions);
     /** Only the VAD loads in the page: the words are written on the server. */
     ready(_language: string, progress?: HearingProgress): Promise<void>;
-    /** Whether speech was found and how long it has been silent; its words come at the end. */
-    hearSoFar(audio: Float32Array): Promise<HeardSoFar>;
+    /** The press being heard as it is said, while one is. */
+    private press?;
+    /** The press's stream, opened anew when a new press began (its sound is shorter). */
+    private streamFor;
+    /**
+     * Whether speech was found and how long it has been silent, and the words
+     * the speech service heard so far: the sound goes to its stream as it comes.
+     */
+    hearSoFar(audio: Float32Array, language?: string): Promise<HeardSoFar>;
     hear(audio: Float32Array, language: string): Promise<Transcript | undefined>;
 }