@datalayer/agent-runtimes 1.3.59 → 1.3.61

package/lib/chat/ChatFloating.d.ts

@@ -110,6 +110,16 @@ export interface ChatFloatingProps extends ChatCommonProps {
      * @default 'paperclip'
      */
     assistantCharacter?: string | AssistantCharacter | AssistantCharacterData;
+    /**
+     * The runtime the floating assistant asks typed decisions at — its
+     * `/api/v1/configure/inference/decisions`, as the `decide` tool asks — and
+     * the token to ask with, if it needs one: its balloon offers *Ask a
+     * decision*, answered there in plain words with its confidence.
+     */
+    decisions?: {
+        serverUrl: string;
+        token?: string;
+    };
     /**
      * Callback when the user switches view mode via the header toggle.
      * The parent component receives the new ChatViewMode value.
@@ -144,5 +154,5 @@ export interface ChatFloatingProps extends ChatCommonProps {
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, themeOverrides, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, assistantCharacter, conversation, }: ChatFloatingProps): React.JSX.Element;
+export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, themeOverrides, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, assistantCharacter, conversation, decisions, }: ChatFloatingProps): React.JSX.Element;
 export default ChatFloating;

package/lib/chat/ChatFloating.js

@@ -31,6 +31,9 @@ import { ButtonGlow } from './display/ButtonGlow';
 import { useViewportDrag } from './useViewportDrag';
 import { disabledChatViewModes, resolveMountPoint } from './viewModes';
 import { AssistantStage } from './assistant/AssistantStage';
+import { decisionsAskerAt } from './assistant/decisions';
+import { DecisionAsk } from './assistant/DecisionAsk';
+import { BalloonApprovalMessage, CONVERSATION_BALLOON_WIDTH, ConversationBalloonClose, balloonTailAt, conversationBalloonHeight, conversationBalloonSx, peekLine, } from './assistant/ConversationBalloon';
 import { SpeechBalloon } from './assistant/SpeechBalloon';
 import { DEFAULT_ASSISTANT_CHARACTER, } from './assistant/characters';
 import { assistantStateOf, latestSaying, newestIsAnswer, keepAway, keptAway, ASSISTANT_WORDS, } from './assistant/state';
@@ -63,7 +66,7 @@ const clamp = (value, max) => Math.max(8, Math.min(value, Math.max(8, max)));
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, themeOverrides, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, assistantCharacter = DEFAULT_ASSISTANT_CHARACTER, conversation, }) {
+export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, themeOverrides, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, assistantCharacter = DEFAULT_ASSISTANT_CHARACTER, conversation, decisions, }) {
     // Store-based state
     const storeIsOpen = useChatOpen();
     const storeMessages = useChatMessages();
@@ -194,6 +197,9 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             },
         }
         : undefined;
+    const assistantDecide = useMemo(() => decisions?.serverUrl
+        ? decisionsAskerAt(decisions.serverUrl, decisions.token)
+        : undefined, [decisions?.serverUrl, decisions?.token]);
     const assistantBalloon = assistantState === 'paused'
         ? { text: ASSISTANT_WORDS.paused }
         : balloonApproval
@@ -201,7 +207,14 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             : assistantState === 'waiting'
                 ? { text: ASSISTANT_WORDS.waiting }
                 : unheard && saying
-                    ? { text: saying.text, more: saying.more }
+                    ? {
+                        // A peek: the first words; the rest is in the conversation.
+                        ...peekLine(saying.text),
+                        onDismiss: () => {
+                            setHeardId(saying.id);
+                            setFreshSaying(false);
+                        },
+                    }
                     : { text: description };
     const balloonInsists = assistantState === 'greeting' ||
         assistantState === 'waiting' ||
@@ -429,19 +442,23 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
     }, [isOpen, handleToggle]);
     /*
      * The conversation as the assistant's balloon: above the character, its
-     * right edge on the character's, and never off the screen.
+     * edge on the character's, never off the screen, and its tail toward the
+     * character — none when it stands beside it.
      */
-    const balloonPlace = () => {
-        const widthPx = typeof width === 'number' ? width : 400;
-        const heightPx = typeof height === 'number' ? height : 550;
+    const viewportWidth = typeof window === 'undefined' ? 1280 : window.innerWidth;
+    const viewportHeight = typeof window === 'undefined' ? 800 : window.innerHeight;
+    const conversationHeight = conversationBalloonHeight(viewportHeight);
+    const balloonGeometry = () => {
+        const widthPx = CONVERSATION_BALLOON_WIDTH;
+        const heightPx = conversationHeight;
         if (stageDrag.position) {
             // Toward the page's inside: above the character, below it, or beside
             // it when the window is too short for either.
             const { left, top } = stageDrag.position;
-            const onLeft = left + ASSISTANT_SIZE / 2 < window.innerWidth / 2;
+            const onLeft = left + ASSISTANT_SIZE / 2 < viewportWidth / 2;
             const above = top - heightPx - 16;
             const below = top + ASSISTANT_SIZE + 16;
-            const beside = above < 8 && below + heightPx > window.innerHeight - 8;
+            const beside = above < 8 && below + heightPx > viewportHeight - 8;
             const x = beside
                 ? onLeft
                     ? left + ASSISTANT_SIZE + 16
@@ -454,17 +471,38 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                 : above >= 8
                     ? above
                     : below;
+            const placedX = clamp(x, viewportWidth - widthPx - 8);
             return {
-                left: px(clamp(x, window.innerWidth - widthPx - 8)),
-                top: px(clamp(y, window.innerHeight - heightPx - 8)),
-                right: 'auto',
-                bottom: 'auto',
+                place: {
+                    left: px(placedX),
+                    top: px(clamp(y, viewportHeight - heightPx - 8)),
+                    right: 'auto',
+                    bottom: 'auto',
+                },
+                tail: beside
+                    ? { edge: 'none' }
+                    : {
+                        edge: above >= 8 ? 'bottom' : 'top',
+                        at: balloonTailAt(left + ASSISTANT_SIZE / 2, placedX),
+                    },
             };
         }
+        const onRight = position.endsWith('right');
+        const characterMiddle = onRight
+            ? viewportWidth - offset - ASSISTANT_SIZE / 2
+            : offset + ASSISTANT_SIZE / 2;
+        const balloonLeft = onRight ? viewportWidth - offset - widthPx : offset;
+        const tail = {
+            edge: position.startsWith('bottom') ? 'bottom' : 'top',
+            at: balloonTailAt(characterMiddle, balloonLeft),
+        };
         const corner = getPositionStyles();
-        return position.startsWith('bottom')
-            ? { ...corner, bottom: offset + ASSISTANT_SIZE + 16 }
-            : { ...corner, top: offset + ASSISTANT_SIZE + 16 };
+        return {
+            place: position.startsWith('bottom')
+                ? { ...corner, bottom: px(offset + ASSISTANT_SIZE + 16) }
+                : { ...corner, top: px(offset + ASSISTANT_SIZE + 16) },
+            tail,
+        };
     };
     // Handle new chat
     const handleNewChat = useCallback(() => {
@@ -516,6 +554,20 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         }, animationDuration);
         return () => clearTimeout(timer);
     }, [hostsConversation, isOpen, animationDuration, focusTrigger]);
+    /*
+     * The assistant's balloon opens on the newest message: the history may
+     * have grown — or arrived — while it was closed.
+     */
+    useEffect(() => {
+        if (!assistantShown || !isOpen) {
+            return undefined;
+        }
+        const timer = setTimeout(() => {
+            const history = popupRef.current?.querySelector('[data-chat-history]');
+            history?.scrollTo?.({ top: history.scrollHeight });
+        }, animationDuration);
+        return () => clearTimeout(timer);
+    }, [assistantShown, isOpen, animationDuration]);
     // Click outside to close
     useEffect(() => {
         if (!clickOutsideToClose || !isOpen)
@@ -600,8 +652,18 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         })
         : undefined;
     // Responsive dimensions
-    const popupWidth = isMobile ? '100%' : width;
-    const popupHeight = isMobile ? '100%' : height;
+    const conversationBalloon = assistantShown ? balloonGeometry() : undefined;
+    // The assistant's conversation is a balloon of its own size (T-23).
+    const popupWidth = isMobile
+        ? '100%'
+        : conversationBalloon
+            ? CONVERSATION_BALLOON_WIDTH
+            : width;
+    const popupHeight = isMobile
+        ? '100%'
+        : conversationBalloon
+            ? conversationHeight
+            : height;
     // Mobile full-screen styles
     const mobileStyles = isMobile
         ? {
@@ -617,6 +679,44 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         : {};
     // Close button for header
     const closeButton = (_jsx(Tooltip, { text: `Close${escapeToClose ? ' (Esc)' : ''}`, direction: "s", children: _jsx(IconButton, { icon: XIcon, "aria-label": "Close", onClick: handleToggle, variant: "invisible", size: "small" }) }));
+    /*
+     * The chat as the assistant's balloon holds it (T-23): the history and the
+     * composer, its Lexical variant, and nothing else — no header, no footer,
+     * none of the session's controls; the welcome as the first message, an
+     * approval as a message with Approve and Deny, and *Ask a decision* beside
+     * the composer when there is a runtime to ask.
+     */
+    const assistantChat = conversationBalloon
+        ? {
+            showHeader: false,
+            showPoweredBy: false,
+            promptVariant: 'lexical',
+            showModelSelector: false,
+            showToolsMenu: false,
+            showSkillsMenu: false,
+            showTokenUsage: false,
+            showContextRing: false,
+            showInformation: false,
+            showToolApprovalBanner: false,
+            showAgentsMenu: false,
+            showTurnFooter: false,
+            compact: true,
+            welcome: description,
+            backgroundColor: 'canvas.default',
+            borderRadius: 'var(--theme-radius-bubble, 16px)',
+            trailingContent: balloonApproval ? (_jsx(BalloonApprovalMessage, { approval: balloonApproval })) : undefined,
+            footerContent: assistantDecide ? (_jsx(Box, { "data-balloon-decisions": "", sx: {
+                    px: 3,
+                    pb: 1,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    alignItems: 'flex-end',
+                    fontSize: 0,
+                    '& form': { alignSelf: 'stretch' },
+                    '& [data-balloon-decision="answered"]': { alignSelf: 'stretch' },
+                }, children: _jsx(DecisionAsk, { ask: assistantDecide }) })) : undefined,
+        }
+        : undefined;
     /* The window itself; where it goes is decided below. */
     const chatWindow = (_jsxs(Box, { ref: popupRef, className: className, sx: {
             position: viewMode === 'panel' && !isMobile && (panelInFlow || dockedInMount)
@@ -647,8 +747,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     }
                     : getPositionStyles()
                 : {}),
-            ...(assistantShown
-                ? balloonPlace()
+            ...(conversationBalloon
+                ? conversationBalloon.place
                 : assistantMode && !isMobile
                     ? getPositionStyles()
                     : {}),
@@ -742,7 +842,16 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             visibility: isOpen || isAnimating ? 'visible' : 'hidden',
             pointerEvents: isOpen ? 'auto' : 'none',
             ...mobileStyles,
-        }, children: [viewMode === 'floating-draggable' && !isMobile && (_jsx(Box, { onPointerDown: drag.onHandlePointerDown, "aria-label": "Move the chat", sx: {
+            // The assistant's balloon: its shape and its tail toward the
+            // character, which the window's own clipping would cut off.
+            ...(conversationBalloon
+                ? conversationBalloonSx(conversationBalloon.tail, 
+                // Out of the composer's band, or of the history's top.
+                conversationBalloon.tail.edge === 'bottom'
+                    ? 'canvas.subtle'
+                    : 'canvas.default')
+                : {}),
+        }, "data-conversation-balloon": conversationBalloon ? '' : undefined, children: [conversationBalloon ? (_jsx(ConversationBalloonClose, { onClose: handleToggle })) : null, viewMode === 'floating-draggable' && !isMobile && (_jsx(Box, { onPointerDown: drag.onHandlePointerDown, "aria-label": "Move the chat", sx: {
                     display: 'flex',
                     alignItems: 'center',
                     justifyContent: 'center',
@@ -755,7 +864,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     borderColor: 'border.muted',
                     touchAction: 'none',
                     '&:active': { cursor: 'grabbing' },
-                }, children: _jsx(GrabberIcon, { size: 16 }) })), conversation ? (_jsxs(_Fragment, { children: [showHeader ? (_jsxs(Box, { sx: {
+                }, children: _jsx(GrabberIcon, { size: 16 }) })), conversation ? (_jsxs(_Fragment, { children: [showHeader && !conversationBalloon ? (_jsxs(Box, { sx: {
                             display: 'flex',
                             alignItems: 'center',
                             gap: 2,
@@ -771,7 +880,17 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                                     overflow: 'hidden',
                                     textOverflow: 'ellipsis',
                                     whiteSpace: 'nowrap',
-                                }, children: title }), closeButton] })) : null, _jsx(Box, { "data-floating-conversation": true, sx: { flex: '1 1 auto', minHeight: 0, display: 'flex' }, children: conversation.body })] })) : (_jsx(ChatBase, { title: title, showHeader: showHeader, useStore: useStoreMode, protocol: protocol, themeVariant: themeVariant, themeOverrides: themeOverrides, colorMode: colorMode, autoFocus: isOpen, focusTrigger: focusTrigger, launching: launching, launchingMessage: launchingMessage, brandIcon: brandIcon || _jsx(AiAgentIcon, { colored: true, size: 20 }), headerButtons: {
+                                }, children: title }), closeButton] })) : null, _jsx(Box, { "data-floating-conversation": true, sx: {
+                            flex: '1 1 auto',
+                            minHeight: 0,
+                            display: 'flex',
+                            ...(conversationBalloon
+                                ? {
+                                    borderRadius: 'var(--theme-radius-bubble, 16px)',
+                                    overflow: 'hidden',
+                                }
+                                : {}),
+                        }, children: conversation.body })] })) : (_jsx(ChatBase, { title: title, showHeader: showHeader, useStore: useStoreMode, protocol: protocol, themeVariant: themeVariant, themeOverrides: themeOverrides, colorMode: colorMode, autoFocus: isOpen, focusTrigger: focusTrigger, launching: launching, launchingMessage: launchingMessage, brandIcon: brandIcon || _jsx(AiAgentIcon, { colored: true, size: 20 }), headerButtons: {
                     showNewChat: showNewChatButton,
                     showClear: showClearButton && messages.length > 0,
                     showSettings: showSettingsButton && !!onSettingsClick,
@@ -787,7 +906,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     ...poweredByProps,
                 }, renderToolResult: renderToolResult, 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, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, ...panelProps, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, children: children }))] }));
+                }, 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, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, ...panelProps, ...assistantChat, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, children: children }))] }));
     /*
      * The floating popup's button. Words not yet heard make it blink for the
      * person's attention, until the chat is opened; hovered, they show in a

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

@@ -17,6 +17,7 @@
 import type { JSX, RefObject } from 'react';
 import { type AssistantCharacter } from './characters';
 import type { AssistantCharacterData } from './formats/types';
+import type { DecisionAsker } from './decisions';
 import { type AssistantAway, type AssistantState, type BalloonApproval } from './state';
 /**
  * Where the balloon goes so that it stays inside the window (T-23): toward
@@ -67,15 +68,17 @@ export interface AssistantStageProps {
     /** Open or close the conversation. */
     onToggle: () => void;
     /**
-     * What the balloon says while the conversation is closed: the agent's
-     * newest words, as the Office Assistant said them (T-23), or a welcome.
-     * `more` adds *Open the conversation* for the rest; `approval`, an
-     * approval to answer there, with *Approve* and *Deny*.
+     * The peek while the conversation is closed: one short line — the agent's
+     * newest words, as the Office Assistant said them (T-23), or a welcome —
+     * that opens the conversation when clicked; `more` says it was cut;
+     * `approval`, an approval to answer there, with *Approve* and *Deny*.
      */
     balloon?: {
         text: string;
         more?: boolean;
         approval?: BalloonApproval;
+        /** Puts the peek away (a × beside its line); never an approval's. */
+        onDismiss?: () => void;
     };
     /** Show the balloon without being hovered: something new to say. */
     insist?: boolean;
@@ -86,6 +89,11 @@ export interface AssistantStageProps {
      * steps aside for, nor is the pointer working there (T-27).
      */
     ownRef?: RefObject<HTMLElement | null>;
+    /**
+     * Asks a typed decision of the runtime: the balloon offers *Ask a
+     * decision*, and stays while its form or its answer is on screen.
+     */
+    decide?: DecisionAsker;
 }
-export declare function AssistantStage({ character, state, size, place, stageRef, onDragStart, open, onToggle, balloon, insist, onDismiss, ownRef, }: AssistantStageProps): JSX.Element;
+export declare function AssistantStage({ character, state, size, place, stageRef, onDragStart, open, onToggle, balloon, insist, onDismiss, ownRef, decide, }: AssistantStageProps): JSX.Element;
 export default AssistantStage;

package/lib/chat/assistant/AssistantStage.js

@@ -180,7 +180,7 @@ export function useKeepClear(stageRef, own, paused) {
     }, [stageRef, own, paused]);
     return obstructed ? 'obstacle' : pointerBusy ? 'pointer' : undefined;
 }
-export function AssistantStage({ character, state, size = 88, place, stageRef, onDragStart, open, onToggle, balloon, insist = false, onDismiss, ownRef, }) {
+export function AssistantStage({ character, state, size = 88, place, stageRef, onDragStart, open, onToggle, balloon, insist = false, onDismiss, ownRef, decide, }) {
     // A shipped one by id, a drawing contributed by a plugin (T-24), or a
     // character read from a file (T-26).
     const shipped = typeof character === 'string'
@@ -199,7 +199,9 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
     // Where the press began: a press that moves is a drag, not a click.
     const pressedAt = useRef(null);
     const aside = useKeepClear(stageRef, ownRef, menuOpen);
-    const showBalloon = !aside && !open && !!balloon && (hovered || insist);
+    // A decision being asked, or its answer, keeps the balloon up.
+    const [deciding, setDeciding] = useState(false);
+    const showBalloon = !aside && !open && !!balloon && (hovered || insist || deciding);
     return (_jsxs(Box, { ref: stageRef, "data-assistant-state": state, "data-assistant-aside": aside, sx: {
             position: 'fixed',
             zIndex: 1002,
@@ -277,7 +279,7 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
             '@media (prefers-reduced-motion: reduce)': {
                 '& *': { animation: 'none !important' },
             },
-        }, onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false), children: [showBalloon && balloon && (_jsx(SpeechBalloon, { text: balloon.text, more: balloon.more, approval: balloon.approval, onOpen: onToggle, above: size + 8, side: balloonSide(place).side, align: balloonSide(place).align, tailAt: size / 2 })), _jsx(Box, { as: "button", type: "button", "aria-label": open ? `Close the conversation with ${name}` : `Talk to ${name}`, "aria-expanded": open, onPointerDown: (event) => {
+        }, onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false), children: [showBalloon && balloon && (_jsx(SpeechBalloon, { text: balloon.text, more: balloon.more, approval: balloon.approval, onDismissPeek: balloon.onDismiss, decide: decide, onDecisionActive: setDeciding, wide: deciding, onOpen: onToggle, above: size + 8, side: balloonSide(place).side, align: balloonSide(place).align, tailAt: size / 2 })), _jsx(Box, { as: "button", type: "button", "aria-label": open ? `Close the conversation with ${name}` : `Talk to ${name}`, "aria-expanded": open, onPointerDown: (event) => {
                     pressedAt.current = { x: event.clientX, y: event.clientY };
                     onDragStart(event);
                 }, onClick: (event) => {

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

@@ -0,0 +1,71 @@
+/**
+ * The floating assistant's conversation, open: a balloon over the character
+ * that holds the conversation itself — the history as the chat draws it, the
+ * welcome first, an approval as a message with *Approve* and *Deny* (T-23),
+ * the composer last — with no header and no footer, a tail toward the
+ * character, a close control, and a height that leaves the page in sight
+ * while the history scrolls inside it.
+ *
+ * Closed, the character peeks instead (`SpeechBalloon`): one short line, and
+ * what it needs to be answered.
+ *
+ * @module chat/assistant/ConversationBalloon
+ */
+import type { JSX } from 'react';
+import { type BalloonApproval } from './state';
+/** The open balloon's width, in pixels. */
+export declare const CONVERSATION_BALLOON_WIDTH = 380;
+/** The open balloon's tallest, in pixels, and its share of the window. */
+export declare const CONVERSATION_BALLOON_MAX_HEIGHT = 560;
+export declare const CONVERSATION_BALLOON_VIEWPORT_SHARE = 0.6;
+/** The open balloon's height for a window this tall: 60% of it, 560px at most. */
+export declare function conversationBalloonHeight(viewportHeight: number): number;
+/**
+ * Where the open balloon's tail points: from its bottom edge (the balloon
+ * above the character) or its top edge (below it), `at` pixels from its
+ * left; none when the balloon stands beside the character.
+ */
+export type BalloonTail = {
+    edge: 'bottom' | 'top';
+    at: number;
+} | {
+    edge: 'none';
+};
+/**
+ * The tail toward a character whose middle is `characterMiddle` pixels from
+ * the window's left, under or over a balloon whose left is `balloonLeft`:
+ * kept off the balloon's rounded corners.
+ */
+export declare function balloonTailAt(characterMiddle: number, balloonLeft: number, width?: number): number;
+/**
+ * The open balloon's shape: the bubble's radius, and its tail — drawn in the
+ * colour of what it leaves (`tailBg`): the composer's band under the
+ * history, the history over it.
+ */
+export declare function conversationBalloonSx(tail: BalloonTail, tailBg?: string): Record<string, unknown>;
+/** The open balloon's close control, over its top right corner. */
+export declare function ConversationBalloonClose({ name, onClose, }: {
+    /** Who is talking: "Close the conversation with Paper clip". */
+    name?: string;
+    onClose: () => void;
+}): JSX.Element;
+/**
+ * An approval the agent waits on, as a message of the history: what it asks
+ * to do, the rule it was asked under, *Approve* and *Deny*, and how many more
+ * wait (T-23). Brought into view when it arrives.
+ */
+export declare function BalloonApprovalMessage({ approval, }: {
+    approval: BalloonApproval;
+}): JSX.Element;
+/** How many more wait, in two words: "2 more". */
+export declare function moreWaiting(others: number): string;
+/** How much of a message a peek says: its first words. */
+export declare const PEEK_LIMIT = 60;
+/**
+ * A message's first words, for a peek: cut at a word, with an ellipsis, and
+ * whether there was more.
+ */
+export declare function peekLine(text: string, limit?: number): {
+    text: string;
+    more: boolean;
+};

package/lib/chat/assistant/ConversationBalloon.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { Button, IconButton, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { XIcon } from '@primer/octicons-react';
+import { ASSISTANT_WORDS } from './state';
+/** The open balloon's width, in pixels. */
+export const CONVERSATION_BALLOON_WIDTH = 380;
+/** The open balloon's tallest, in pixels, and its share of the window. */
+export const CONVERSATION_BALLOON_MAX_HEIGHT = 560;
+export const CONVERSATION_BALLOON_VIEWPORT_SHARE = 0.6;
+/** The open balloon's height for a window this tall: 60% of it, 560px at most. */
+export function conversationBalloonHeight(viewportHeight) {
+    return Math.max(240, Math.min(CONVERSATION_BALLOON_MAX_HEIGHT, Math.round(viewportHeight * CONVERSATION_BALLOON_VIEWPORT_SHARE)));
+}
+/** The tail's half width, in pixels. */
+const TAIL = 7;
+/**
+ * The tail toward a character whose middle is `characterMiddle` pixels from
+ * the window's left, under or over a balloon whose left is `balloonLeft`:
+ * kept off the balloon's rounded corners.
+ */
+export function balloonTailAt(characterMiddle, balloonLeft, width = CONVERSATION_BALLOON_WIDTH) {
+    return Math.min(width - 24 - TAIL, Math.max(24, characterMiddle - balloonLeft - TAIL));
+}
+/**
+ * The open balloon's shape: the bubble's radius, and its tail — drawn in the
+ * colour of what it leaves (`tailBg`): the composer's band under the
+ * history, the history over it.
+ */
+export function conversationBalloonSx(tail, tailBg = 'canvas.default') {
+    return {
+        borderRadius: 'var(--theme-radius-bubble, 16px)',
+        overflow: 'visible',
+        ...(tail.edge === 'none'
+            ? {}
+            : {
+                '&::after': {
+                    content: '""',
+                    position: 'absolute',
+                    ...(tail.edge === 'bottom'
+                        ? { bottom: `-${TAIL}px` }
+                        : { top: `-${TAIL}px` }),
+                    left: `${tail.at}px`,
+                    width: `${TAIL * 2}px`,
+                    height: `${TAIL * 2}px`,
+                    bg: tailBg,
+                    borderRight: '1px solid',
+                    borderBottom: '1px solid',
+                    borderColor: 'border.default',
+                    transform: tail.edge === 'bottom' ? 'rotate(45deg)' : 'rotate(225deg)',
+                    pointerEvents: 'none',
+                },
+            }),
+    };
+}
+/** The open balloon's close control, over its top right corner. */
+export function ConversationBalloonClose({ name, onClose, }) {
+    return (_jsx(Box, { "data-conversation-balloon-close": "", sx: { position: 'absolute', top: '6px', right: '6px', zIndex: 30 }, children: _jsx(IconButton, { icon: XIcon, size: "small", variant: "invisible", "aria-label": name
+                ? `Close the conversation with ${name}`
+                : 'Close the conversation', onClick: onClose, sx: { bg: 'canvas.default', borderRadius: '50%' } }) }));
+}
+/**
+ * An approval the agent waits on, as a message of the history: what it asks
+ * to do, the rule it was asked under, *Approve* and *Deny*, and how many more
+ * wait (T-23). Brought into view when it arrives.
+ */
+export function BalloonApprovalMessage({ approval, }) {
+    const ref = useRef(null);
+    useEffect(() => {
+        ref.current?.scrollIntoView?.({ block: 'nearest' });
+    }, [approval.id]);
+    return (_jsx(Box, { ref: ref, "data-balloon-approval": approval.id, sx: { px: 3, py: 2, display: 'flex' }, children: _jsxs(Box, { sx: {
+                maxWidth: '90%',
+                px: 3,
+                py: 2,
+                bg: 'attention.subtle',
+                border: '1px solid',
+                borderColor: 'attention.muted',
+                borderRadius: 'var(--theme-radius-bubble, 16px)',
+                fontSize: 1,
+            }, children: [_jsx(Text, { as: "p", sx: { m: 0, color: 'fg.muted', fontSize: 0 }, children: ASSISTANT_WORDS.approval }), _jsx(Text, { as: "p", sx: { m: 0, fontWeight: 'semibold' }, children: approval.asks }), approval.why ? (_jsx(Text, { as: "p", sx: { m: 0, color: 'fg.muted', fontSize: 0 }, children: approval.why })) : null, _jsxs(Box, { sx: { display: 'flex', gap: 2, mt: 2, alignItems: 'center' }, children: [_jsx(Button, { size: "small", variant: "primary", disabled: approval.deciding, onClick: approval.onApprove, children: ASSISTANT_WORDS.approve }), _jsx(Button, { size: "small", disabled: approval.deciding, onClick: approval.onDeny, children: ASSISTANT_WORDS.deny }), approval.others > 0 ? (_jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: moreWaiting(approval.others) })) : null] })] }) }));
+}
+/** How many more wait, in two words: "2 more". */
+export function moreWaiting(others) {
+    return `${others} more`;
+}
+/** How much of a message a peek says: its first words. */
+export const PEEK_LIMIT = 60;
+/**
+ * A message's first words, for a peek: cut at a word, with an ellipsis, and
+ * whether there was more.
+ */
+export function peekLine(text, limit = PEEK_LIMIT) {
+    const plain = text.replace(/\s+/g, ' ').trim();
+    if (plain.length <= limit) {
+        return { text: plain, more: false };
+    }
+    const cut = plain.slice(0, limit);
+    const atWord = cut.slice(0, Math.max(cut.lastIndexOf(' '), limit * 0.6));
+    return { text: `${atWord.trimEnd()}…`, more: true };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * *Ask a decision* in the floating assistant's balloon: a small form — the
+ * situation, the question, its type (yes or no; a choice with its options
+ * listed; a score with its range) — asked of Jev through the runtime, and
+ * the answer said back in the balloon in plain words with its confidence.
+ *
+ * @module chat/assistant/DecisionAsk
+ */
+import type { JSX } from 'react';
+import { type DecisionAsker } from './decisions';
+/** The balloon's words for a decision. */
+export declare const DECISION_WORDS: {
+    readonly ask: "Ask a decision";
+    readonly asking: "Asking…";
+    readonly submit: "Ask";
+    readonly cancel: "Cancel";
+    readonly again: "Ask another";
+    readonly types: {
+        noul: string;
+        choice: string;
+        score: string;
+    };
+};
+export interface DecisionAskProps {
+    /** Asks the runtime. */
+    ask: DecisionAsker;
+    /** The form or its answer is on screen: the balloon must stay. */
+    onActiveChange?: (active: boolean) => void;
+}
+export declare function DecisionAsk({ ask, onActiveChange, }: DecisionAskProps): JSX.Element;
+export default DecisionAsk;