@datalayer/agent-runtimes 1.3.60 → 1.3.62

package/lib/chat/ChatFloating.js

@@ -32,6 +32,8 @@ 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';
@@ -205,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' ||
@@ -433,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
@@ -458,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(() => {
@@ -520,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)
@@ -604,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
         ? {
@@ -621,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)
@@ -651,8 +747,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     }
                     : getPositionStyles()
                 : {}),
-            ...(assistantShown
-                ? balloonPlace()
+            ...(conversationBalloon
+                ? conversationBalloon.place
                 : assistantMode && !isMobile
                     ? getPositionStyles()
                     : {}),
@@ -746,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',
@@ -759,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,
@@ -775,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,
@@ -791,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
@@ -839,7 +954,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                         left: px(stageDrag.position.left),
                         top: px(stageDrag.position.top),
                     }
-                    : getPositionStyles(), stageRef: stageRef, onDragStart: stageDrag.onHandlePointerDown, open: isOpen, onToggle: handleToggle, balloon: assistantBalloon, insist: balloonInsists, onDismiss: dismissAssistant, ownRef: popupRef, decide: assistantDecide })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
+                    : getPositionStyles(), stageRef: stageRef, onDragStart: stageDrag.onHandlePointerDown, open: isOpen, onToggle: handleToggle, balloon: assistantBalloon, insist: balloonInsists, onDismiss: dismissAssistant, ownRef: popupRef })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
                     ...getPositionStyles(),
                 }, children: _jsxs(Box, { sx: {
                         position: 'relative',

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

@@ -68,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;

package/lib/chat/assistant/AssistantStage.js

@@ -279,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, 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) => {
+        }, 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/SpeechBalloon.d.ts

@@ -1,11 +1,13 @@
 /**
  * A speech balloon over something that stands for the agent — the floating
  * assistant's character, or the floating popup's button while the chat is
- * closed: the agent's newest words, as the Office Assistant said them
- * (LOOP T-23), with *Open the conversation* when there is more — and an
- * approval it waits on, answered there with *Approve* or *Deny* — and, where
- * the runtime can be asked, *Ask a decision*: a typed decision asked of Jev,
- * its answer said back in the balloon.
+ * closed: a peek, one short line — the agent's newest words, as the Office
+ * Assistant said them (LOOP T-23), cut to their first words, or a
+ * notification — that opens the conversation when clicked, and can be
+ * dismissed; an approval it waits on, answered there with *Approve* or
+ * *Deny*, and how many more wait; and, where the runtime can be asked and
+ * the conversation is elsewhere (the LOOP workspace), *Ask a decision*: a
+ * typed decision asked of Jev, its answer said back in the balloon.
  *
  * @module chat/assistant/SpeechBalloon
  */
@@ -34,6 +36,8 @@ export interface SpeechBalloonProps {
     onDecisionActive?: (active: boolean) => void;
     /** Wider, for the decision's form. */
     wide?: boolean;
+    /** Puts the peek away: a × beside its line. Never for an approval. */
+    onDismissPeek?: () => void;
 }
-export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, approval, decide, onDecisionActive, wide, }: SpeechBalloonProps): JSX.Element;
+export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, approval, decide, onDecisionActive, wide, onDismissPeek, }: SpeechBalloonProps): JSX.Element;
 export default SpeechBalloon;

package/lib/chat/assistant/SpeechBalloon.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Button, Text } from '@primer/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';
+import { moreWaiting } from './ConversationBalloon';
 import { DecisionAsk } from './DecisionAsk';
-export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above', align, tailAt, approval, decide, onDecisionActive, wide = false, }) {
+export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above', align, tailAt, approval, decide, onDecisionActive, wide = false, onDismissPeek, }) {
     return (_jsxs(Box, { role: "status", "aria-live": "polite", "data-speech-balloon": "", sx: {
             position: 'absolute',
             // Pixels, as strings: a number here is read as the theme's space
@@ -38,15 +40,18 @@ export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above
                 borderColor: 'border.default',
                 transform: side === 'above' ? 'rotate(45deg)' : 'rotate(225deg)',
             },
-        }, children: [_jsx(Text, { as: "p", sx: { m: 0 }, children: text }), approval && (_jsxs(Box, { "data-balloon-approval": approval.id, sx: { mt: 1 }, children: [_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 }, 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, { as: "p", sx: { m: 0, mt: 1, color: 'fg.muted', fontSize: 0 }, children: `${approval.others} more waiting.` })) : null] })), decide && _jsx(DecisionAsk, { ask: decide, onActiveChange: onDecisionActive }), more && (_jsx(Box, { as: "button", type: "button", onClick: onOpen, sx: {
-                    mt: 1,
-                    p: 0,
-                    border: 0,
-                    bg: 'transparent',
-                    color: 'accent.fg',
-                    textDecoration: 'underline',
-                    cursor: 'pointer',
-                    fontSize: 1,
-                }, children: "Open the conversation" }))] }));
+        }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'flex-start', gap: 1 }, children: [_jsx(Box, { as: "button", type: "button", "data-balloon-peek": "", "data-balloon-more": more ? '' : undefined, onClick: onOpen, sx: {
+                            flex: 1,
+                            minWidth: 0,
+                            m: 0,
+                            p: 0,
+                            border: 0,
+                            bg: 'transparent',
+                            color: 'inherit',
+                            font: 'inherit',
+                            textAlign: 'left',
+                            cursor: 'pointer',
+                            '&:hover': { textDecoration: 'underline' },
+                        }, children: text }), onDismissPeek && !approval ? (_jsx(IconButton, { icon: XIcon, size: "small", variant: "invisible", "aria-label": "Dismiss", "data-balloon-dismiss": "", onClick: onDismissPeek, sx: { mt: '-4px', mr: '-8px', flexShrink: 0 } })) : null] }), approval && (_jsxs(Box, { "data-balloon-approval": approval.id, sx: { mt: 1 }, children: [_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 }, 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, { as: "p", sx: { m: 0, mt: 1, color: 'fg.muted', fontSize: 0 }, children: moreWaiting(approval.others) })) : null] })), decide && _jsx(DecisionAsk, { ask: decide, onActiveChange: onDecisionActive })] }));
 }
 export default SpeechBalloon;

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

@@ -71,7 +71,7 @@ export interface AssistantSaying {
     /** Whether there was more than the balloon holds. */
     more: boolean;
 }
-/** How much of a message the balloon says before *Open the conversation*. */
+/** How much of a message is kept as the agent's saying before it is cut. */
 export declare const SAYING_LIMIT = 220;
 /**
  * The newest thing the agent said, as the Office Assistant said it: in the

package/lib/chat/assistant/state.js

@@ -49,7 +49,7 @@ export const ASSISTANT_WORDS = {
     /** Its deployment is paused (R-17). */
     paused: 'Paused — it answers again once it is resumed.',
 };
-/** How much of a message the balloon says before *Open the conversation*. */
+/** How much of a message is kept as the agent's saying before it is cut. */
 export const SAYING_LIMIT = 220;
 /**
  * The newest thing the agent said, as the Office Assistant said it: in the

package/lib/chat/base/ChatBase.js

@@ -463,6 +463,8 @@ function parseApprovedMcpToolsByServer(mcpStatusData) {
 // ---------------------------------------------------------------------------
 // ChatBase (outer wrapper — ensures QueryClient is available)
 // ---------------------------------------------------------------------------
+/** When the welcome is said: it has no time of its own. */
+const WELCOME_AT = new Date(0);
 /**
  * ChatBase component — Universal chat panel supporting store, protocol, and custom modes.
  */
@@ -507,7 +509,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, renderToolResult, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, 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, renderToolResult, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, welcome, trailingContent, 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, 
 // Identity/Authorization props
@@ -3478,7 +3480,23 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             })
                 .filter(item => item.message)
             : undefined;
-    const messagesContent = children ? (children) : (_jsx(Box, { sx: {
+    /*
+     * The welcome, as the first message: drawn as the agent's own words are,
+     * never sent nor kept. With it, the history is never empty, so the empty
+     * state gives way to it.
+     */
+    const welcomedItems = welcome
+        ? [
+            {
+                id: '__welcome__',
+                role: 'assistant',
+                content: welcome,
+                createdAt: WELCOME_AT,
+            },
+            ...displayItems,
+        ]
+        : displayItems;
+    const messagesContent = children ? (children) : (_jsxs(Box, { sx: {
             display: 'flex',
             flexDirection: 'column',
             minHeight: 0,
@@ -3494,7 +3512,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             maxWidth: 920,
             mx: 'auto',
             bg: 'canvas.default',
-        }, children: _jsx(ChatMessageList, { displayItems: displayItems, isLoading: isLoading, isStreaming: isStreaming, showLoadingIndicator: showLoadingIndicator, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: defaultAvatarConfig, padding: padding, renderToolResult: effectiveRenderToolResult, 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 })) }) }));
+        }, children: [_jsx(ChatMessageList, { displayItems: welcomedItems, isLoading: isLoading, isStreaming: isStreaming, showLoadingIndicator: showLoadingIndicator, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: defaultAvatarConfig, padding: padding, renderToolResult: effectiveRenderToolResult, 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] }));
     const inputToolbar = showInput ? (_jsx(InputPrompt, { input: input, setInput: setInput, isLoading: isLoading, kernelStatus: liveKernelStatus, connectionConfirmed: connectionConfirmed, placeholder: placeholder, 
         /*
           The same openers the empty state offers, typed into the box they would
@@ -3695,7 +3713,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                                 top: 8,
                                 right: 8,
                                 zIndex: 6,
-                            }, children: _jsx(IconButton, { icon: SidebarExpandIcon, "aria-label": "Open chat", onClick: onExpandFromCollapsed, variant: "default", size: "small" }) })) : (_jsx(FloatingBrandButton, { isOpen: false, onToggle: onExpandFromCollapsed, position: "bottom-right", tooltip: "Open chat" })))] })) : (_jsxs(_Fragment, { children: [_jsx(Box, { ref: messagesContainerRef, sx: {
+                            }, children: _jsx(IconButton, { icon: SidebarExpandIcon, "aria-label": "Open chat", onClick: onExpandFromCollapsed, variant: "default", size: "small" }) })) : (_jsx(FloatingBrandButton, { isOpen: false, onToggle: onExpandFromCollapsed, position: "bottom-right", tooltip: "Open chat" })))] })) : (_jsxs(_Fragment, { children: [_jsx(Box, { ref: messagesContainerRef, "data-chat-history": "", sx: {
                             flex: 1,
                             flexGrow: 1,
                             minHeight: 0,