@datalayer/agent-runtimes 1.5.17 → 1.5.18

package/lib/apps/apps/appspec.d.ts

@@ -24,7 +24,7 @@
  *
  * @module apps/apps/appspec
  */
-import type { AppAccent, AppThemeMode, AppThemeVariant, AppAssistantCharacter, AppEmbedMode, PapProfile, AppCustomComponentSpec, AppVoiceSpec, AppKind, AppLayout, AppPageOutputComponent, AppSpec } from '../../types/agentspecs';
+import type { AppAccent, AppThemeMode, AppThemeVariant, AppAssistantCharacter, AppEmbedMode, PapProfile, AppCustomComponentSpec, AppVoiceSpec, AppKind, AppLayout, AppPageOutputComponent, AppSpec, UiChoice } from '../../types/agentspecs';
 /** The version of the spec itself. */
 export declare const APP_SCHEMA = "loop.app/v1";
 /** The language an application's own words are in, unless it says (LOOP P-26). */
@@ -53,6 +53,36 @@ export declare const APP_ASSISTANT_CHARACTER_ID: RegExp;
 export declare function isAssistantCharacterId(value: unknown): value is AppAssistantCharacter;
 /** The layout a kind starts with. */
 export declare const DEFAULT_LAYOUTS: Record<AppKind, AppLayout>;
+/** The media type of an answer drawn as A2UI surfaces. */
+export declare const A2UI_OUTPUT = "application/json+a2ui";
+/** What `uiFor` reads of an application besides its kind. */
+export interface AppUiFacts {
+    /** Its layout; its kind's own when unsaid. */
+    layout?: AppLayout;
+    /** The media types it answers in. */
+    outputs?: readonly string[];
+    /** It signs people in at companies (`pap.connections`). */
+    signsIn?: boolean;
+    /** It has components of its own (`interface.customComponents`). */
+    ownComponents?: boolean;
+}
+/**
+ * The UI plugins an application is drawn with (AGENTIC_UI R8), as its `ui`
+ * lists them: what `appPreset` mounts for it. A decision: its page alone,
+ * drawn by its host. Every other kind: the conversation — `chat`, which
+ * stands for the conversation base the runtime mounts — then the A2UI
+ * surfaces when it answers in `application/json+a2ui`, the sign-in card when
+ * it signs people in at companies, its page, its layout and the Canvas's
+ * blocks when its layout is not `chat`, and its own components when it has
+ * some. What a host adds (the Preview's sidebar, a frame) is not the
+ * application's.
+ *
+ * agentspecs' `ui_for` is the same function: both are held to
+ * `agent_runtimes/tests/fixtures/app_ui.json`.
+ */
+export declare function uiFor(kind: AppKind, facts?: AppUiFacts): UiChoice[];
+/** The UI plugins an application is drawn with, by what its spec says (`uiFor`). */
+export declare function uiOf(app: Pick<AppSpec, 'kind' | 'interface' | 'pap'>): UiChoice[];
 /** What an application keeps of what it did, when it does not say. */
 export declare const DEFAULT_RECORD_INCLUDE: string[];
 type Data = Record<string, unknown>;

package/lib/apps/apps/appspec.js

@@ -74,6 +74,50 @@ export const DEFAULT_LAYOUTS = {
     decision: 'page',
     worker: 'split',
 };
+/** The media type of an answer drawn as A2UI surfaces. */
+export const A2UI_OUTPUT = 'application/json+a2ui';
+/**
+ * The UI plugins an application is drawn with (AGENTIC_UI R8), as its `ui`
+ * lists them: what `appPreset` mounts for it. A decision: its page alone,
+ * drawn by its host. Every other kind: the conversation — `chat`, which
+ * stands for the conversation base the runtime mounts — then the A2UI
+ * surfaces when it answers in `application/json+a2ui`, the sign-in card when
+ * it signs people in at companies, its page, its layout and the Canvas's
+ * blocks when its layout is not `chat`, and its own components when it has
+ * some. What a host adds (the Preview's sidebar, a frame) is not the
+ * application's.
+ *
+ * agentspecs' `ui_for` is the same function: both are held to
+ * `agent_runtimes/tests/fixtures/app_ui.json`.
+ */
+export function uiFor(kind, facts = {}) {
+    if (kind === 'decision') {
+        return [{ plugin: 'app-page' }];
+    }
+    const drawn = [{ plugin: 'chat' }];
+    if (facts.outputs?.includes(A2UI_OUTPUT)) {
+        drawn.push({ plugin: 'a2ui-surface', renderer: 'a2ui' });
+    }
+    if (facts.signsIn) {
+        drawn.push({ plugin: 'pap-sign-in' });
+    }
+    if ((facts.layout ?? DEFAULT_LAYOUTS[kind]) !== 'chat') {
+        drawn.push({ plugin: 'page-layout' }, { plugin: 'app-page' }, { plugin: 'canvas-blocks' });
+    }
+    if (facts.ownComponents) {
+        drawn.push({ plugin: 'app-components' });
+    }
+    return drawn;
+}
+/** The UI plugins an application is drawn with, by what its spec says (`uiFor`). */
+export function uiOf(app) {
+    return uiFor(app.kind, {
+        layout: app.interface.layout,
+        outputs: app.interface.outputs,
+        signsIn: Boolean(app.pap?.connections.length),
+        ownComponents: Boolean(app.interface.customComponents?.length),
+    });
+}
 /** What an application keeps of what it did, when it does not say. */
 export const DEFAULT_RECORD_INCLUDE = ['conversations', 'actions', 'approvals'];
 const DEFAULT_KEEP_FOR = '1_years';
@@ -93,22 +137,27 @@ const texts = (value) => Array.isArray(value)
 const records = (value) => Array.isArray(value) ? value.filter(isData) : [];
 /**
  * An application's UI plugins as its document says them (AGENTIC_UI R8):
- * `{plugin, renderer}` each. A bare id — the old shape, a renderer named as a
- * UI — is read as the plugin it names, which `uiProblems` refuses.
+ * `{plugin, renderer}` each. Anything else — a bare id, the old shape — is
+ * not read as a plugin: `parseAppspec` refuses it (`uiShapeProblems`).
  */
 const uiChoices = (value) => Array.isArray(value)
-    ? value.flatMap((item) => typeof item === 'string'
-        ? [{ plugin: item }]
-        : isData(item)
-            ? [
-                {
-                    plugin: text(item.plugin),
-                    ...(text(item.renderer)
-                        ? { renderer: text(item.renderer) }
-                        : {}),
-                },
-            ]
-            : [])
+    ? value.filter(isData).map(item => ({
+        plugin: text(item.plugin),
+        ...(text(item.renderer) ? { renderer: text(item.renderer) } : {}),
+    }))
+    : [];
+/**
+ * An entry of `ui` that is not `{plugin, renderer}`, in agentspecs' sentence
+ * (`ui_choices_problems`): a bare id is refused, never read as the plugin it
+ * names, and one naming a renderer says how to write it.
+ */
+const uiShapeProblems = (value) => Array.isArray(value)
+    ? value
+        .filter(item => !isData(item))
+        .map(item => `\`ui\` lists UI plugins, each as \`{plugin, renderer}\`: ${JSON.stringify(item)} is not one` +
+        (typeof item === 'string' && UI_RENDERER_CATALOGUE[item]
+            ? ` (${JSON.stringify(item)} is a UI renderer: name the plugin it renders, and say it as its \`renderer\`).`
+            : '.'))
     : [];
 /**
  * One turn of a test's conversation as its document says it (STUDIO E-01):
@@ -153,7 +202,8 @@ export function emptyAppspec(kind = 'chat') {
         contents: [],
         connections: [],
         protocols: [],
-        ui: [],
+        // A blank application starts with its kind's UI plugins (AGENTIC_UI R8).
+        ui: uiFor(kind),
         rules: [],
         permissions: {
             spaces: [],
@@ -957,6 +1007,7 @@ export function parseAppspec(document) {
             problems.push(`\`${key}\` is not a field of the spec.`);
         }
     }
+    problems.push(...uiShapeProblems(data.ui));
     const schema = text(data.schema, APP_SCHEMA);
     if (schema !== APP_SCHEMA) {
         problems.push(`This reads ${APP_SCHEMA}; the application is written in ${schema}.`);

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

@@ -1295,6 +1295,16 @@ export default function ChatView({ workspace }) {
     // not know (LOOP R-20): it runs a session of its deployment, and no more.
     const embedToken = reactor.getConfig(AGENTS_PLUGIN_NAME)?.embedToken;
     const iamToken = visitors ? visitor.token : embedToken || memberToken;
+    /*
+     * A deployment's runtime, and the visitors', answer only the application's
+     * own routes (OwnRoutesOnly, PAP_DATALAYER's release gates): its chat calls
+     * nothing else — Stop is its session's, no monitoring stream, no sandbox
+     * socket, no runtime-wide model switch. A Preview runs on the Maker's.
+     */
+    const ownRoutesOnly = Boolean(deploymentUid || visitors);
+    if (ownRoutesOnly && !runsApp) {
+        throw new Error('A deployment’s page runs its application: its host gave no app_spec.');
+    }
     /*
      * A thread opened from the person's history (LOOP P-24): its conversation
      * read from the runtime once it answers — held there, else resumed from
@@ -1420,6 +1430,9 @@ export default function ChatView({ workspace }) {
                         uiSocket: `${agentServerUrl.replace(/^http/, 'ws')}/api/v1/apps/ui`,
                         // Its files, uploaded before what names them (RU-6).
                         uiFiles: `${agentServerUrl}/api/v1/apps/agents/${encodeURIComponent(agentId)}/files`,
+                        // Each thread a session: Stop is its session's.
+                        appSessions: `${agentServerUrl}/api/v1/apps/sessions`,
+                        ...(ownRoutesOnly ? { ownRoutesOnly: true } : {}),
                     }
                     : {}),
                 agentId,
@@ -1442,6 +1455,7 @@ export default function ChatView({ workspace }) {
         agentServerUrl,
         runsApp,
         iamToken,
+        ownRoutesOnly,
     ]);
     /*
      * The model catalogue, and the builtin tools and skills the agent reports.
@@ -1556,6 +1570,10 @@ export default function ChatView({ workspace }) {
      * to agree.
      */
     const selectModel = useCallback(async (model) => {
+        if (ownRoutesOnly) {
+            // Runtime-wide, and not the application's own: never offered here.
+            throw new Error('A deployment’s chat does not switch its runtime’s model.');
+        }
         setPickedModel(model);
         if (inPage || agentServerUrl === undefined) {
             return;
@@ -1565,7 +1583,7 @@ export default function ChatView({ workspace }) {
             headers: { 'content-type': 'application/json' },
             body: JSON.stringify({ model }),
         }).catch(() => undefined);
-    }, [agentServerUrl, inPage]);
+    }, [agentServerUrl, inPage, ownRoutesOnly]);
     /* `bottom-chat` keeps the prompt in the chat column; `bottom`, the default,
        spans the workspace. */
     const besideChat = config?.promptPlacement === 'bottom-chat';
@@ -1660,7 +1678,8 @@ export default function ChatView({ workspace }) {
         showTokenUsage: chatExtras.showTokenUsage ?? config?.showTokenUsage ?? true,
         showContextRing: true,
         agentUsage: contextUsage ?? undefined,
-        showModelSelector: !presence,
+        // Nor on a deployment's page: the model is its runtime's, for everyone.
+        showModelSelector: !presence && !ownRoutesOnly,
         models: offeredModels,
         decisions,
         selectedModel: activeModel,

package/lib/chat/ChatFloating.js

@@ -35,6 +35,7 @@ import { decisionsAskerAt } from './assistant/decisions';
 import { DecisionAsk } from './assistant/DecisionAsk';
 import { ServerSpeaker } from '../voice/speaker';
 import { useSpokenAnswers } from '../voice/useSpokenAnswers';
+import { readAloud } from '../voice/ReadAloud';
 import { BalloonApprovalMessage, CONVERSATION_BALLOON_WIDTH, ConversationBalloonClose, balloonTailAt, conversationBalloonHeight, conversationBalloonSx, CURRENT_BALLOON_HEIGHT, peekLine, } from './assistant/ConversationBalloon';
 import { ConversationBalloonHeader, CurrentBalloonBody, } from './assistant/BalloonParts';
 import { DEFAULT_BALLOON_DISPLAY, conversationCount, newestToolLine, toolLineText, } from './assistant/toolLine';
@@ -165,7 +166,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
     const [speakerState, setSpeakerState] = useState({
         speaking: false,
     });
-    const speaker = useMemo(() => voice && voice.output === 'always' && voice.speechUrl
+    const speaker = useMemo(() => voice && voice.output !== 'off' && voice.speechUrl
         ? new ServerSpeaker({
             speechUrl: voice.speechUrl,
             voice: voice.voice,
@@ -195,8 +196,15 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             window.removeEventListener('keydown', unlock);
         };
     }, [speaker]);
-    useSpokenAnswers(voiceItems, chatBusy, !!speaker && !speechMuted, speaker);
+    // `always`: each answer heard as it is written; `on_request`: a *Read
+    // aloud* under each (VO-21).
+    useSpokenAnswers(voiceItems, chatBusy, !!speaker && voice?.output === 'always' && !speechMuted, speaker);
     const stopSpeaking = useCallback(() => speaker?.stop(), [speaker]);
+    const readAnswerAloud = useCallback((answer) => {
+        if (speaker) {
+            readAloud(speaker, answer);
+        }
+    }, [speaker]);
     const mouthLevel = useMemo(() => (speaker ? () => speaker.level() : undefined), [speaker]);
     const [arriving, setArriving] = useState(false);
     const [leaving, setLeaving] = useState(false);
@@ -1057,7 +1065,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     ...poweredByProps,
                 }, description: description, onStateUpdate: onStateUpdate, onNewChat: onNewChat, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: {
                     showAvatars: true,
-                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt ?? suggestionPrompt, inspector: inspector, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, voice: voice, voiceSpeaking: speakerState.speaking, onStopSpeaking: speaker ? stopSpeaking : undefined, ...panelProps, ...assistantChat, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, onSendReady: handleSendReady, children: conversationBalloon && currentOpen ? (
+                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt ?? suggestionPrompt, inspector: inspector, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, voice: voice, voiceSpeaking: speakerState.speaking, onStopSpeaking: speaker ? stopSpeaking : undefined, onReadAloud: speaker ? readAnswerAloud : undefined, ...panelProps, ...assistantChat, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, onSendReady: handleSendReady, children: conversationBalloon && currentOpen ? (
                 // Current: the one thing said or done now, over the composer.
                 _jsx(Box, { px: 3, pt: 3, pb: 2, overflow: "hidden", children: _jsx(CurrentBalloonBody, { text: toolSaid ? undefined : (currentWords ?? description), fullText: toolSaid ? undefined : currentWhole, tool: toolSaid, busy: atWork, speaking: answering && atWork, waiting: atWork && !answering }) })) : (children) }))] }));
     /*
@@ -1109,7 +1117,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     }
                     : getPositionStyles(), stageRef: stageRef, onDragStart: stageDrag.onHandlePointerDown, open: isOpen, onToggle: handleToggle, balloon: assistantBalloon, balloonDisplay: balloonDisplay, expandTarget: expandTarget, insist: balloonInsists, onDismiss: dismissAssistant, ownRef: popupRef, mouthLevel: mouthLevel, suggestions: balloonSuggestions, onSuggestion: sendSuggestion, inspector: inspector, onBalloonDisplayChange: changeBalloonDisplay, onStop: chatBusy && chatControls.current
                     ? () => chatControls.current?.stop()
-                    : undefined, onNewChat: !conversation && showNewChatButton ? handleNewChat : undefined, onClear: !conversation && useStoreMode ? handleClear : undefined, onChangeCharacter: onChangeCharacter, speech: speaker
+                    : undefined, onNewChat: !conversation && showNewChatButton ? handleNewChat : undefined, onClear: !conversation && useStoreMode ? handleClear : undefined, onChangeCharacter: onChangeCharacter, speech: speaker && voice?.output === 'always'
                     ? {
                         muted: speechMuted,
                         onToggle: () => {

package/lib/chat/base/ChatBase.js

@@ -36,7 +36,7 @@ import { askedOf } from '../../apps/apps/records';
 import { extractChatMessagesFromFullContext } from './fullContextMessages';
 import { generateMessageId, createUserMessage, createAssistantMessage, } from '../../types/messages';
 import { AI_MODEL_CATALOGUE, DEFAULT_MODEL, isChatModel, } from '../../specs/models';
-import { internalQueryClient, isToolCallMessage, convertHistoryToDisplayItems, createProtocolAdapter, getApiBaseFromConfig, sanitizeAssistantContent, } from '../../utils';
+import { internalQueryClient, isToolCallMessage, getMessageText, convertHistoryToDisplayItems, createProtocolAdapter, getApiBaseFromConfig, sanitizeAssistantContent, } from '../../utils';
 import { useConfig, useSkills, useSkillActions, useContextSnapshot, useSandbox, } from '../../hooks';
 import { useAgentRuntimeWebSocket } from '../../hooks/useAgentRuntimes';
 import { agentRuntimeStore, useAgentRuntimeStore, useAgentRuntimeWsState, } from '../../stores/agentRuntimeStore';
@@ -50,6 +50,7 @@ import { ChatMessageList, } from '../messages/ChatMessageList';
 import { InputPrompt } from '../prompt/InputPrompt';
 import { DeviceHearing } from '../../voice/hearing';
 import { VoiceInput } from '../../voice/VoiceInput';
+import { ReadAloud, readsAloud } from '../../voice/ReadAloud';
 import { isFloatingChatViewMode } from '../viewModes';
 import { ToolApprovalBanner, ToolApprovalDialog, } from '../tools';
 import { initialModelId, isOffered, offeredModels as offeredModelsFor, } from './modelChoice';
@@ -416,7 +417,7 @@ function ChatBaseInner({ title, subtitle, showHeader = false, showTokenUsage = t
 // Mode selection
 useStore: useStoreMode = true, protocol: protocolRaw, onSendMessage, onSendReady, onLoadingChange, onContextSnapshot, enableStreaming = false, 
 // Extended props
-brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, welcome, trailingContent, voice, voiceSpeaking = false, onStopSpeaking, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, onItemsChange, onDisplayItemsChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, 
+brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, welcome, trailingContent, voice, voiceSpeaking = false, onStopSpeaking, onReadAloud, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, onItemsChange, onDisplayItemsChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, 
 // Tool invocation hooks
 onToolCallStart, onToolCallComplete, inspector: inspectorGiven, 
 // Identity/Authorization props
@@ -1467,7 +1468,9 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     useEffect(() => {
         onContextSnapshot?.(agentUsage);
     }, [agentUsage, onContextSnapshot]);
-    const sandboxStatusQuery = useSandbox(configQueriesEnabled && showHeader, protocol?.configEndpoint, protocol?.authToken, protocol?.agentId);
+    // Never on a runtime held to the application's own routes: it answers no
+    // sandbox socket (OwnRoutesOnly).
+    const sandboxStatusQuery = useSandbox(configQueriesEnabled && showHeader && !protocol?.ownRoutesOnly, protocol?.configEndpoint, protocol?.authToken, protocol?.agentId);
     // ---- Refs ----
     const adapterRef = useRef(null);
     const unsubscribeRef = useRef(null);
@@ -1794,8 +1797,16 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     const wsBaseUrl = protocol?.configEndpoint
         ? protocol.configEndpoint.replace(/\/api\/v1\/(config|configure)\/?$/, '')
         : (protocol?.endpoint?.replace(/\/api\/v1\/.*$/, '') ?? '');
+    /*
+     * Not on a runtime held to the application's own routes (OwnRoutesOnly): it
+     * answers no monitoring stream, and an application's session asks its
+     * approvals in the conversation, over its ui socket.
+     */
     useAgentRuntimeWebSocket({
-        enabled: !!protocol && !!wsBaseUrl && !isAgentNodeTunnelAgUi,
+        enabled: !!protocol &&
+            !!wsBaseUrl &&
+            !isAgentNodeTunnelAgUi &&
+            !protocol.ownRoutesOnly,
         baseUrl: wsBaseUrl,
         authToken: protocol?.authToken,
         agentId: protocol?.agentId,
@@ -3739,6 +3750,21 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             ...displayItems,
         ]
         : displayItems;
+    /*
+     * *Read aloud* under each answer the agent has finished (VOICE.md VO-21),
+     * when the host reads answers aloud on request.
+     */
+    const writingId = isLoading || isStreaming
+        ? [...welcomedItems]
+            .reverse()
+            .find((item) => !isToolCallMessage(item) && item.role === 'assistant')?.id
+        : undefined;
+    const readAloudFooter = onReadAloud
+        ? (message) => {
+            const text = getMessageText(message);
+            return readsAloud(message, text, writingId) ? (_jsx(ReadAloud, { onRead: () => onReadAloud(text) })) : null;
+        }
+        : undefined;
     const messagesContent = children ? (children) : (_jsxs(Box, { display: "flex", flexDirection: "column", minHeight: 0, 
         /*
             A reading column, not a full-bleed sheet.
@@ -3752,7 +3778,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                 // Tool calls are drawn by the page's Reactor plugins; a named
                 // notebook's cell surfaces stand in for the default row of its tools,
                 // so every chat with a headless notebook gets the same transcript.
-                notebookToolSurfacesId: notebookToolSurfacesId, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, showTurnFooters: showTurnFooter, agentUsage: agentUsage, onRemoveItems: handleRemoveItems, mcpServers: filteredMcpServers, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }), trailingContent] }));
+                notebookToolSurfacesId: notebookToolSurfacesId, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, showTurnFooters: showTurnFooter, renderMessageFooter: readAloudFooter, agentUsage: agentUsage, onRemoveItems: handleRemoveItems, mcpServers: filteredMcpServers, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }), trailingContent] }));
     // The microphone, in the composer's footer (VO-10).
     const voiceControl = hearing && voice ? (_jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', disabled: disabled || launching, speaking: voiceSpeaking, onStopSpeaking: onStopSpeaking, onListen: onStopSpeaking, onTranscript: (transcript) => {
             if (voice.sendWhatISay) {

package/lib/chat/messages/ChatMessageList.js

@@ -611,7 +611,7 @@ export function ChatMessageList({ displayItems, actOn, upload, isLoading, isStre
                                                 whiteSpace: 'pre-wrap',
                                                 wordBreak: 'break-word',
                                             }, children: [message.metadata?.input === 'voice' ? (_jsx(Box, { as: "span", "data-spoken": "", title: "Said aloud", "aria-label": "Said aloud:", display: "inline-flex", verticalAlign: "text-bottom", mr: 1, opacity: 0.85, children: _jsx(MicrophoneIcon, { size: 14, "aria-hidden": "true" }) })) : null, text] }));
-                                    })()) : message.live && !getMessageText(message) ? (_jsx(TypingDots, { size: 6 })) : (_jsx(ChatMarkdown, { density: density, text: getMessageText(message) || (isStreaming ? '...' : '') }))] }), message.displays?.length ? (_jsx(Box, { "data-chat-displays": "", display: "flex", flexDirection: "column", gap: 2, mt: 2, width: "100%", children: message.displays.map(display => platform ? (_jsx(ReactorDisplay, { display: display, act: actOn?.(display), upload: upload }, display.id)) : (_jsx(DisplayText, { display: display }, display.id))) })) : null, renderMessageFooter ? (_jsx(Box, { display: "flex", gap: 2, alignItems: "center", mt: 1, flexWrap: "wrap", flexDirection: isUser ? 'row-reverse' : 'row', children: renderMessageFooter(message) })) : null] })] }) }, message.id));
+                                    })()) : message.live && !getMessageText(message) ? (_jsx(TypingDots, { size: 6 })) : (_jsx(ChatMarkdown, { density: density, text: getMessageText(message) || (isStreaming ? '...' : '') }))] }), message.displays?.length ? (_jsx(Box, { "data-chat-displays": "", display: "flex", flexDirection: "column", gap: 2, mt: 2, width: "100%", children: message.displays.map(display => platform ? (_jsx(ReactorDisplay, { display: display, act: actOn?.(display), upload: upload }, display.id)) : (_jsx(DisplayText, { display: display }, display.id))) })) : null, renderMessageFooter?.(message) ? (_jsx(Box, { display: "flex", gap: 2, alignItems: "center", mt: 1, flexWrap: "wrap", flexDirection: isUser ? 'row-reverse' : 'row', children: renderMessageFooter(message) })) : null] })] }) }, message.id));
     };
     return (_jsxs(_Fragment, { children: [displayItems.map((item, index) => {
                 const itemUI = renderItem(item, index);

package/lib/examples/AgentA2ATeamExample.js

@@ -11,12 +11,13 @@ import { useBrowserInference } from '../hooks/useBrowserInference';
 import { readJwtClaims, tokenLifetimeMs, useAnonymousSessionStore, } from '../runtimes/browser/anonymousToken';
 import { connectA2APeer } from '../runtimes/browser/a2aPeer';
 import { A2ATeamGraph, SceneView, NOTEBOOK_AND_WORDS, teamConnectionsOf, teamToolClassifier, useA2ATeam, usePeerSandbox, } from '../components/teams';
-import { ACCOUNTING_APP_0_0_1, SALES_APP_0_0_2 } from '../specs/apps';
+import { APP_CATALOGUE } from '../specs/apps';
 import { AgentInspector, classifyToolCall, traceA2AFetch, useAgentInspector, } from '../components/inspector';
-import { SALES_AND_ACCOUNTING_TEAM_SPEC_0_0_1 } from '../specs/teams/teams';
-const TEAM = SALES_AND_ACCOUNTING_TEAM_SPEC_0_0_1;
-const SALES = SALES_APP_0_0_2;
-const ACCOUNTING = ACCOUNTING_APP_0_0_1;
+import { TEAM_SPECS } from '../specs/teams/teams';
+// By id, never by the version-named constants: a version bump touches no caller.
+const TEAM = TEAM_SPECS['sales-and-accounting'];
+const SALES = APP_CATALOGUE['sales'];
+const ACCOUNTING = APP_CATALOGUE['accounting'];
 /** What Accounting reaches, from its Appspec: Odoo, through the odoo-accounting MCP server. */
 const ACCOUNTING_CONNECTIONS = teamConnectionsOf(ACCOUNTING);
 /** The members of the team, as the team spec says them. */

package/lib/examples/ChatExample.js

@@ -30,13 +30,13 @@ import { uniqueAgentId } from './utils/agentId';
 import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { BROWSER_SIGN_IN_REASON, useExampleAgentProtocol, } from './hooks/useExampleAgentProtocol';
 import { runsInBrowser } from '../runtimes/variants';
-import { EXAMPLE_SIMPLE_AGENTSPEC_0_0_1 } from '../specs/agents/agents';
+import { AGENTSPECS } from '../specs/agents/agents';
 import { ErrorView } from './components';
 import { Chat } from '../chat';
 setupPrimerPortals();
 const AGENTSPEC_ID = 'example-simple';
 const AGENT_NAME = 'simple';
-const SPEC = EXAMPLE_SIMPLE_AGENTSPEC_0_0_1;
+const SPEC = AGENTSPECS[AGENTSPEC_ID];
 const AgentRuntimeChatExample = () => {
     const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
     const { agentId, baseUrl, error, status, isReady, variant } = useExampleAgentRuntime({

package/lib/examples/VoiceChatExample.js

@@ -45,21 +45,27 @@ const LANGUAGES = [
     { tag: 'en-US', label: 'English' },
     { tag: 'fr-FR', label: 'Français' },
 ];
+/** When answers are heard (VO-21): on request is the Appspec's default. */
+const OUTPUTS = [
+    { output: 'on_request', label: 'Read aloud on request' },
+    { output: 'always', label: 'Always read aloud' },
+];
 const VoiceChatExample = () => {
     const { token } = useSimpleAuthStore();
     const [language, setLanguage] = useState('en-US');
+    const [output, setOutput] = useState('on_request');
     const voiceSpec = voiceFor(language) ?? VOICE_CATALOGUE['kokoro-af-heart'];
     const voice = useMemo(() => ({
         language,
         input: 'push_to_talk',
-        output: 'always',
+        output,
         voice: voiceSpec.id,
         modelsUrl: MODELS,
         engines: ENGINES,
         speechUrl: SPEECH,
         token: token || undefined,
         consentKey: 'voice-chat-example',
-    }), [language, voiceSpec.id, token]);
-    return (_jsx(ThemedProvider, { children: _jsxs(Box, { minHeight: "100vh", bg: "canvas.default", p: 4, children: [_jsxs(Box, { maxWidth: 720, mx: "auto", children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Voice chat" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 3 }, children: ["Talk to the assistant instead of typing: hold the microphone in its composer, or ", _jsx("kbd", { children: "Ctrl" }), "+", _jsx("kbd", { children: "Space" }), ", speak, and let go. What you say is heard in this page and never leaves it; the words go in the message box for you to send. Its answers are read aloud as they are written, by Datalayer\u2019s speech service, and not kept.", ' ', _jsx("kbd", { children: "Esc" }), " stops its voice."] }), _jsxs(Box, { display: "flex", alignItems: "center", gap: 3, mb: 3, children: [_jsx(SegmentedControl, { "aria-label": "Language", children: LANGUAGES.map(option => (_jsx(SegmentedControl.Button, { selected: language === option.tag, onClick: () => setLanguage(option.tag), "data-voice-language": option.tag, children: option.label }, option.tag))) }), _jsxs(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: ["Voice: ", voiceSpec.name] })] }), voiceSpec.attribution && (_jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mb: 3 }, children: voiceSpec.attribution })), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted' }, children: ["Models from ", MODELS, ", speech from ", SPEECH, ", the agent at ", SERVER, ". See", ' ', _jsx(Link, { href: "https://agent-runtimes.datalayer.tech/chat/voice", children: "Voice" }), ' ', "for how to run each."] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: "paperclip", protocol: "vercel-ai", endpoint: `${SERVER}/api/v1/vercel-ai/assistant`, title: "Assistant", description: "Hello! Hold the microphone and ask me anything.", position: "bottom-right", useStore: false, voice: voice })] }) }));
+    }), [language, output, voiceSpec.id, token]);
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { minHeight: "100vh", bg: "canvas.default", p: 4, children: [_jsxs(Box, { maxWidth: 720, mx: "auto", children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Voice chat" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 3 }, children: ["Talk to the assistant instead of typing: hold the microphone in its composer, or ", _jsx("kbd", { children: "Ctrl" }), "+", _jsx("kbd", { children: "Space" }), ", speak, and let go. What you say is heard in this page and never leaves it; the words go in the message box for you to send. Its answers are read aloud by Datalayer\u2019s speech service, and not kept: on request, with", ' ', _jsx("em", { children: "Read aloud" }), " under an answer, or always, as they are written.", ' ', _jsx("kbd", { children: "Esc" }), " stops its voice."] }), _jsxs(Box, { display: "flex", alignItems: "center", gap: 3, mb: 3, flexWrap: "wrap", children: [_jsx(SegmentedControl, { "aria-label": "Language", children: LANGUAGES.map(option => (_jsx(SegmentedControl.Button, { selected: language === option.tag, onClick: () => setLanguage(option.tag), "data-voice-language": option.tag, children: option.label }, option.tag))) }), _jsx(SegmentedControl, { "aria-label": "When answers are heard", children: OUTPUTS.map(option => (_jsx(SegmentedControl.Button, { selected: output === option.output, onClick: () => setOutput(option.output), "data-voice-output": option.output, children: option.label }, option.output))) }), _jsxs(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: ["Voice: ", voiceSpec.name] })] }), voiceSpec.attribution && (_jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mb: 3 }, children: voiceSpec.attribution })), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted' }, children: ["Models from ", MODELS, ", speech from ", SPEECH, ", the agent at ", SERVER, ". See", ' ', _jsx(Link, { href: "https://agent-runtimes.datalayer.tech/chat/voice", children: "Voice" }), ' ', "for how to run each."] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: "paperclip", protocol: "vercel-ai", endpoint: `${SERVER}/api/v1/vercel-ai/assistant`, title: "Assistant", description: "Hello! Hold the microphone and ask me anything.", position: "bottom-right", useStore: false, voice: voice })] }) }));
 };
 export default VoiceChatExample;

package/lib/hooks/useBrowserAgent.d.ts

@@ -14,7 +14,7 @@ export type UseBrowserAgentOptions = CreateBrowserAgentOptions & {
  * ```tsx
  * const frontendTools = useNotebookTools(notebookId);
  * const { messages, sendMessage, status } = useBrowserAgent({
- *   spec: JUPYTER_NOTEBOOK_COMPACTOR_AGENTSPEC_0_0_1,
+ *   spec: AGENTSPECS['jupyter-notebook-compactor'],
  *   frontendTools,
  *   inference: { inferenceUrl, token },
  * });

package/lib/hooks/useBrowserAgent.js

@@ -35,7 +35,7 @@ import { createBrowserAgent, } from '../runtimes/browser';
  * ```tsx
  * const frontendTools = useNotebookTools(notebookId);
  * const { messages, sendMessage, status } = useBrowserAgent({
- *   spec: JUPYTER_NOTEBOOK_COMPACTOR_AGENTSPEC_0_0_1,
+ *   spec: AGENTSPECS['jupyter-notebook-compactor'],
  *   frontendTools,
  *   inference: { inferenceUrl, token },
  * });

package/lib/protocols/AGUIAdapter.d.ts

@@ -15,6 +15,11 @@ export declare const RUN_CUT_SHORT = "The run stopped before it finished, withou
 export interface AGUIAdapterConfig extends ProtocolAdapterConfig {
     /** Runtime URL (e.g., /api/copilotkit) */
     runtimeUrl?: string;
+    /**
+     * An application's sessions (`…/api/v1/apps/sessions`): Stop is the
+     * thread's session's (`ProtocolConfig.appSessions`).
+     */
+    appSessions?: string;
 }
 /**
  * AG-UI protocol adapter
@@ -63,6 +68,12 @@ export declare class AGUIAdapter extends BaseProtocolAdapter {
      * Terminate a running agent thread on the backend
      */
     terminateAgent(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
+     * none, nothing was sent and there is nothing to stop.
+     */
+    private stopSession;
     /**
      * Send a message through AG-UI protocol
      * @param message - The new message to send

package/lib/protocols/AGUIAdapter.js

@@ -86,8 +86,10 @@ export class AGUIAdapter extends BaseProtocolAdapter {
     disconnect() {
         // Abort every ongoing fetch request, not merely the newest.
         this.stopGeneration();
-        // Send terminate request to backend if we have a thread ID
-        if (this.currentThreadId) {
+        // Send terminate request to backend if we have a thread ID. Never an
+        // application's session: a page going away, or the chat rebuilt with a
+        // fresh token, is not the person's Stop — it waits for them to come back.
+        if (this.currentThreadId && !this.aguiConfig.appSessions) {
             this.terminateAgent(this.currentThreadId).catch(err => {
                 console.warn('[AGUIAdapter] Failed to terminate agent:', err);
             });
@@ -98,6 +100,11 @@ export class AGUIAdapter extends BaseProtocolAdapter {
      * Terminate a running agent thread on the backend
      */
     async terminateAgent(threadId) {
+        const sessions = this.aguiConfig.appSessions;
+        if (sessions) {
+            await this.stopSession(sessions, threadId || this.currentThreadId);
+            return;
+        }
         try {
             // Derive the terminate endpoint from the base URL
             // e.g., http://localhost:8765/api/v1/ag-ui/default -> http://localhost:8765/api/v1/ag-ui/terminate
@@ -121,6 +128,24 @@ export class AGUIAdapter extends BaseProtocolAdapter {
             // Ignore errors - agent may have already completed
         }
     }
+    /**
+     * 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
+     * none, nothing was sent and there is nothing to stop.
+     */
+    async stopSession(sessions, threadId) {
+        if (!threadId) {
+            return;
+        }
+        const url = `${sessions.replace(/\/+$/, '')}/${encodeURIComponent(threadId)}/stop`;
+        const response = await this.fetchOf()(url, {
+            method: 'POST',
+            headers: this.buildHeaders(),
+        });
+        if (!response.ok) {
+            throw new Error(`The session ${threadId} could not be stopped (${response.status}).`);
+        }
+    }
     /**
      * Send a message through AG-UI protocol
      * @param message - The new message to send

package/lib/specs/apps.d.ts

@@ -8,38 +8,38 @@
  * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
  */
 import type { AppBuilt, AppKind, AppSpec } from '../types/agentspecs';
-export declare const ACCOUNTING_APP_0_0_1: AppSpec;
-export declare const BOOKKEEPING_DESK_APP_0_0_1: AppSpec;
-export declare const CHANGE_DETECTION_APP_0_0_1: AppSpec;
-export declare const CROP_MONITORING_APP_0_0_1: AppSpec;
-export declare const CUSTOMER_INTERVIEW_APP_0_0_2: AppSpec;
-export declare const DATA_QUALITY_APP_0_0_2: AppSpec;
-export declare const DECIDE_APP_0_0_1: AppSpec;
-export declare const DISASTER_ASSESSMENT_APP_0_0_1: AppSpec;
-export declare const ERRAND_RUNNER_APP_0_0_1: AppSpec;
-export declare const EVENT_RESPONSE_APP_0_0_2: AppSpec;
-export declare const EXCHANGE_DESK_APP_0_0_2: AppSpec;
-export declare const GUEST_DESK_APP_0_0_1: AppSpec;
-export declare const INBOX_TRIAGE_APP_0_0_1: AppSpec;
-export declare const LIVE_SHOP_CHAT_APP_0_0_1: AppSpec;
-export declare const MODEL_CHOICE_APP_0_0_2: AppSpec;
-export declare const MONTH_END_CLOSE_APP_0_0_1: AppSpec;
-export declare const ORDER_DESK_APP_0_0_1: AppSpec;
-export declare const ORDER_TRACKER_APP_0_0_1: AppSpec;
-export declare const PIPELINE_REPORT_APP_0_0_1: AppSpec;
-export declare const QUOTE_CALCULATOR_APP_0_0_5: AppSpec;
-export declare const REPORT_FROM_A_FILE_APP_0_0_4: AppSpec;
-export declare const RETURNS_DESK_APP_0_0_1: AppSpec;
-export declare const SALES_APP_0_0_2: AppSpec;
-export declare const SHIP_OR_FIX_APP_0_0_2: AppSpec;
-export declare const SHOP_CONCIERGE_APP_0_0_1: AppSpec;
-export declare const SHOPPING_DESK_APP_0_0_1: AppSpec;
-export declare const SIGN_IN_DESK_APP_0_0_1: AppSpec;
-export declare const SIGNED_READER_APP_0_0_1: AppSpec;
-export declare const SUPPLIER_COMPARISON_APP_0_0_2: AppSpec;
-export declare const SUPPORT_DESK_APP_0_0_4: AppSpec;
-export declare const TRAVEL_DESK_APP_0_0_1: AppSpec;
-export declare const WEB_RESEARCH_APP_0_0_1: AppSpec;
+export declare const ACCOUNTING_APP_0_0_2: AppSpec;
+export declare const BOOKKEEPING_DESK_APP_0_0_2: AppSpec;
+export declare const CHANGE_DETECTION_APP_0_0_2: AppSpec;
+export declare const CROP_MONITORING_APP_0_0_2: AppSpec;
+export declare const CUSTOMER_INTERVIEW_APP_0_0_3: AppSpec;
+export declare const DATA_QUALITY_APP_0_0_3: AppSpec;
+export declare const DECIDE_APP_0_0_2: AppSpec;
+export declare const DISASTER_ASSESSMENT_APP_0_0_2: AppSpec;
+export declare const ERRAND_RUNNER_APP_0_0_2: AppSpec;
+export declare const EVENT_RESPONSE_APP_0_0_3: AppSpec;
+export declare const EXCHANGE_DESK_APP_0_0_3: AppSpec;
+export declare const GUEST_DESK_APP_0_0_2: AppSpec;
+export declare const INBOX_TRIAGE_APP_0_0_2: AppSpec;
+export declare const LIVE_SHOP_CHAT_APP_0_0_2: AppSpec;
+export declare const MODEL_CHOICE_APP_0_0_3: AppSpec;
+export declare const MONTH_END_CLOSE_APP_0_0_2: AppSpec;
+export declare const ORDER_DESK_APP_0_0_2: AppSpec;
+export declare const ORDER_TRACKER_APP_0_0_2: AppSpec;
+export declare const PIPELINE_REPORT_APP_0_0_2: AppSpec;
+export declare const QUOTE_CALCULATOR_APP_0_0_6: AppSpec;
+export declare const REPORT_FROM_A_FILE_APP_0_0_5: AppSpec;
+export declare const RETURNS_DESK_APP_0_0_2: AppSpec;
+export declare const SALES_APP_0_0_3: AppSpec;
+export declare const SHIP_OR_FIX_APP_0_0_3: AppSpec;
+export declare const SHOP_CONCIERGE_APP_0_0_2: AppSpec;
+export declare const SHOPPING_DESK_APP_0_0_2: AppSpec;
+export declare const SIGN_IN_DESK_APP_0_0_2: AppSpec;
+export declare const SIGNED_READER_APP_0_0_2: AppSpec;
+export declare const SUPPLIER_COMPARISON_APP_0_0_3: AppSpec;
+export declare const SUPPORT_DESK_APP_0_0_5: AppSpec;
+export declare const TRAVEL_DESK_APP_0_0_2: AppSpec;
+export declare const WEB_RESEARCH_APP_0_0_2: AppSpec;
 export declare const APP_CATALOGUE: Record<string, AppSpec>;
 /** An application, by `id` or `id:version`, or undefined. */
 export declare function getApp(ref: string): AppSpec | undefined;