@datalayer/agent-runtimes 1.3.74 → 1.3.75

package/lib/chat/assistant/AssistantStage.js

@@ -1,10 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { Suspense, lazy, useCallback, useEffect, useRef, useState, } from 'react';
 import { ActionList, ActionMenu, IconButton, useTheme } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { XIcon } from '@primer/octicons-react';
+import { CommentDiscussionIcon, InfoIcon, MuteIcon, PencilIcon, PlusIcon, PulseIcon, ScreenNormalIcon, SquareFillIcon, TrashIcon, UnmuteIcon, XIcon, } from '@primer/octicons-react';
+import { Dialog, Text } from '@primer/react';
 import { assistantCharacter } from './characters';
-import { SpeechBalloon } from './SpeechBalloon';
+import { BalloonHistoryLarge, SpeechBalloon, } from './SpeechBalloon';
+import { conversationHeaderText } from './BalloonParts';
+import { AssistantContextMenu, LONG_PRESS_MS, opensContextMenu, } from './AssistantContextMenu';
 import { BalloonExpandContext, ExpandedVisual, focusExpanded, } from './BalloonVisual';
 import { SpriteCharacter } from './SpriteCharacter';
 import { ASSISTANT_OBSTACLES, POINTER_CALM_MS, boxesMeet, pointerNear, } from './state';
@@ -58,6 +61,128 @@ const AWAY_CHOICES = [
     { away: 'session', label: 'Hide for this session' },
     { away: 'always', label: 'Don\u2019t show again' },
 ];
+/** The Agent Inspector's dialog: loaded when it is first asked for. */
+const AgentInspectorDialog = lazy(() => import('../../components/inspector/AgentInspectorDialog'));
+/**
+ * The entries of the assistant's menu, composed from what the host passes:
+ * each shows when what it does is there to do.
+ */
+export function assistantMenuItems(options) {
+    const items = [];
+    if (options.inspect) {
+        items.push({
+            id: 'inspect',
+            label: 'Inspect the agent…',
+            icon: PulseIcon,
+            onSelect: options.inspect,
+        });
+    }
+    if (options.conversationLabel !== false) {
+        items.push({
+            id: 'conversation',
+            label: options.conversationLabel ??
+                (options.open ? 'Close the conversation' : 'Open the conversation'),
+            icon: CommentDiscussionIcon,
+            onSelect: options.onToggle,
+        });
+    }
+    if (options.busy && options.onStop) {
+        items.push({
+            id: 'stop',
+            label: 'Stop the turn',
+            icon: SquareFillIcon,
+            onSelect: options.onStop,
+        });
+    }
+    if (options.onNewChat) {
+        items.push({
+            id: 'new-chat',
+            label: 'New conversation',
+            icon: PlusIcon,
+            onSelect: options.onNewChat,
+        });
+    }
+    if (options.onClear) {
+        items.push({
+            id: 'clear',
+            label: 'Clear the conversation',
+            icon: TrashIcon,
+            onSelect: options.onClear,
+        });
+    }
+    if (options.suggestions?.length && options.onSuggestion) {
+        const send = options.onSuggestion;
+        for (const suggestion of options.suggestions) {
+            items.push({
+                id: `suggestion:${suggestion.label}`,
+                label: suggestion.label,
+                description: suggestion.prompt,
+                group: 'Suggestions',
+                disabled: options.busy,
+                onSelect: () => send(suggestion),
+            });
+        }
+    }
+    if (options.onBalloonDisplayChange) {
+        const change = options.onBalloonDisplayChange;
+        items.push({
+            id: 'balloon-history',
+            label: 'History',
+            group: 'Balloon',
+            checked: options.balloonDisplay !== 'current',
+            onSelect: () => change('history'),
+        }, {
+            id: 'balloon-current',
+            label: 'Current',
+            group: 'Balloon',
+            checked: options.balloonDisplay === 'current',
+            onSelect: () => change('current'),
+        });
+    }
+    if (options.onChangeCharacter) {
+        items.push({
+            id: 'character',
+            label: 'Change character…',
+            icon: PencilIcon,
+            onSelect: options.onChangeCharacter,
+        });
+    }
+    if (options.speech) {
+        items.push({
+            id: 'speech',
+            label: options.speech.muted ? 'Unmute speech' : 'Mute speech',
+            icon: options.speech.muted ? UnmuteIcon : MuteIcon,
+            onSelect: options.speech.onToggle,
+        });
+    }
+    if (options.onResetPosition) {
+        items.push({
+            id: 'reset-position',
+            label: 'Reset position',
+            icon: ScreenNormalIcon,
+            onSelect: options.onResetPosition,
+        });
+    }
+    if (options.about) {
+        items.push({
+            id: 'about',
+            label: `About ${options.name}`,
+            icon: InfoIcon,
+            onSelect: options.about,
+        });
+    }
+    items.push(...(options.extra ?? []));
+    for (const choice of AWAY_CHOICES) {
+        items.push({
+            id: `away:${choice.away}`,
+            label: choice.label,
+            group: 'Send away',
+            icon: XIcon,
+            onSelect: () => options.onDismiss(choice.away),
+        });
+    }
+    return items;
+}
 /** Room the balloon needs above the character before it goes below. */
 const BALLOON_ROOM = 200;
 /** A place's length in pixels, given as a number or as `"<n>px"`. */
@@ -210,7 +335,7 @@ export function useMouth(stageRef, mouthLevel, speaking) {
         };
     }, [stageRef, mouthLevel, speaking]);
 }
-export function AssistantStage({ character, state, size = 88, place, stageRef, onDragStart, open, onToggle, balloon, insist = false, onDismiss, ownRef, decide, mouthLevel, stayPut = false, balloonDisplay = 'history', expandTarget, expandOnArrival = false, }) {
+export function AssistantStage({ character, state, size = 88, place, stageRef, onDragStart, open, onToggle, balloon, insist = false, onDismiss, ownRef, decide, mouthLevel, stayPut = false, balloonDisplay = 'history', expandTarget, expandOnArrival = false, suggestions, onSuggestion, inspector, inspectAgent, conversationLabel, onBalloonDisplayChange, onStop, onNewChat, onClear, onChangeCharacter, speech, onResetPosition, about, contextMenu, }) {
     // 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'
@@ -226,13 +351,48 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
     const colorMode = colorScheme?.startsWith('dark') ? 'dark' : 'light';
     const [hovered, setHovered] = useState(false);
     const [menuOpen, setMenuOpen] = useState(false);
+    // Its own menu, where it was opened; the inspector and *About* it opens.
+    const [menuAt, setMenuAt] = useState(null);
+    const [inspecting, setInspecting] = useState(false);
+    const [telling, setTelling] = useState(false);
+    const characterRef = useRef(null);
+    const longPress = useRef(undefined);
+    const closeMenu = useCallback(() => setMenuAt(null), []);
+    useEffect(() => () => clearTimeout(longPress.current), []);
     // Where the press began: a press that moves is a drag, not a click.
     const pressedAt = useRef(null);
-    const aside = useKeepClear(stageRef, ownRef, menuOpen || stayPut);
+    const aside = useKeepClear(stageRef, ownRef, menuOpen || menuAt !== null || inspecting || telling || stayPut);
     useMouth(stageRef, mouthLevel, state === 'speaking');
     // A decision being asked, or its answer, keeps the balloon up.
     const [deciding, setDeciding] = useState(false);
     const showBalloon = !aside && !open && !!balloon && (hovered || insist || deciding);
+    // Suggestions while it waits for a question.
+    const waitsForQuestion = (state === 'idle' || state === 'greeting') &&
+        !balloon?.tool &&
+        !balloon?.approval &&
+        !balloon?.busy;
+    const busy = state === 'thinking' || state === 'working' || state === 'speaking';
+    const menuItems = assistantMenuItems({
+        name,
+        open,
+        onToggle,
+        onDismiss,
+        conversationLabel,
+        inspect: inspector ? () => setInspecting(true) : undefined,
+        balloonDisplay,
+        onBalloonDisplayChange,
+        suggestions,
+        onSuggestion,
+        busy,
+        onStop,
+        onNewChat,
+        onClear,
+        onChangeCharacter,
+        speech,
+        onResetPosition,
+        about: about ? () => setTelling(true) : undefined,
+        extra: contextMenu,
+    });
     // The large visual drawn now: kept while the balloon moves on to other
     // words, until it is closed or another one is expanded.
     const visual = balloon?.visual;
@@ -245,6 +405,17 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
             }
         }
         : null;
+    // The history, large: drawn from the balloon's messages as they are now.
+    const history = balloon?.history;
+    const historyVisual = balloonDisplay !== 'current' && history && history.length > 0
+        ? {
+            id: 'balloon-history',
+            title: conversationHeaderText(history.length),
+            shrink: true,
+            render: () => (_jsx(BalloonHistoryLarge, { history: history, tool: balloon?.tool, attachment: balloon?.attachment })),
+        }
+        : null;
+    const shown = expanded?.id === 'balloon-history' ? historyVisual : expanded;
     useEffect(() => {
         if (visual && expandOnArrival && expandTarget) {
             setExpanded(visual);
@@ -349,8 +520,43 @@ 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: [expanded && (_jsx(ExpandedVisual, { visual: expanded, target: expandTarget, onClose: () => setExpanded(null) })), showBalloon && balloon && (_jsx(BalloonExpandContext.Provider, { value: expand, children: _jsx(SpeechBalloon, { text: balloon.text, more: balloon.more, approval: balloon.approval, onDismissPeek: balloon.onDismiss, display: balloonDisplay, tool: balloon.tool, speaking: balloon.speaking, busy: balloon.busy, attachment: balloon.attachment, history: balloon.history, onExpand: expand ?? undefined, expandTitle: visual?.title, 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: [shown && (_jsx(ExpandedVisual, { visual: shown, target: expandTarget, onClose: () => setExpanded(null) })), showBalloon && balloon && (_jsx(BalloonExpandContext.Provider, { value: expand, children: _jsx(SpeechBalloon, { text: balloon.text, more: balloon.more, approval: balloon.approval, onDismissPeek: balloon.onDismiss, display: balloonDisplay, tool: balloon.tool, speaking: balloon.speaking, busy: balloon.busy, attachment: balloon.attachment, history: balloon.history, onExpand: expand ?? undefined, expandTitle: visual?.title, onExpandHistory: historyVisual
+                        ? () => {
+                            setExpanded(historyVisual);
+                            if (expandTarget) {
+                                requestAnimationFrame(() => focusExpanded(expandTarget));
+                            }
+                        }
+                        : undefined, suggestions: waitsForQuestion ? suggestions : undefined, fullText: balloon.fullText, waiting: (state === 'thinking' ||
+                        state === 'working' ||
+                        state === 'waiting') &&
+                        !balloon.speaking, onSuggestion: onSuggestion, 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, "aria-haspopup": "menu", ref: characterRef, "data-assistant-figure": "", onContextMenu: (event) => {
+                    event.preventDefault();
+                    clearTimeout(longPress.current);
+                    setMenuAt({ x: event.clientX, y: event.clientY });
+                }, onKeyDown: (event) => {
+                    if (opensContextMenu(event)) {
+                        event.preventDefault();
+                        const box = event.currentTarget.getBoundingClientRect();
+                        setMenuAt({ x: box.left + box.width / 2, y: box.bottom });
+                    }
+                }, onPointerUp: () => clearTimeout(longPress.current), onPointerCancel: () => clearTimeout(longPress.current), onPointerMove: (event) => {
+                    const from = pressedAt.current;
+                    if (from &&
+                        Math.hypot(event.clientX - from.x, event.clientY - from.y) > 8) {
+                        clearTimeout(longPress.current);
+                    }
+                }, onPointerDown: (event) => {
                     pressedAt.current = { x: event.clientX, y: event.clientY };
+                    if (event.pointerType === 'touch') {
+                        const at = { x: event.clientX, y: event.clientY };
+                        clearTimeout(longPress.current);
+                        longPress.current = setTimeout(() => {
+                            // Held, not tapped: the menu, and no click after it.
+                            pressedAt.current = { x: -1e6, y: -1e6 };
+                            setMenuAt(at);
+                        }, LONG_PRESS_MS);
+                    }
                     onDragStart(event);
                 }, onClick: (event) => {
                     const from = pressedAt.current;
@@ -381,6 +587,20 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
                                     bg: 'canvas.default',
                                     borderRadius: '50%',
                                     boxShadow: 'shadow.small',
-                                } }) }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsx(ActionList, { children: AWAY_CHOICES.map(choice => (_jsx(ActionList.Item, { "data-assistant-away": choice.away, onSelect: () => onDismiss(choice.away), children: choice.label }, choice.away))) }) })] }) }))] }));
+                                } }) }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsx(ActionList, { children: AWAY_CHOICES.map(choice => (_jsx(ActionList.Item, { "data-assistant-away": choice.away, onSelect: () => onDismiss(choice.away), children: choice.label }, choice.away))) }) })] }) })), _jsx(AssistantContextMenu, { at: menuAt, items: menuItems, onClose: closeMenu, returnFocusRef: characterRef, label: `${name}\u2019s menu` }), inspecting && (_jsx(Suspense, { fallback: null, children: _jsx(AgentInspectorDialog, { sink: inspector ?? null, agent: inspectAgent, title: `${about?.name ?? name} \u00b7 Agent Inspector`, onClose: () => {
+                        setInspecting(false);
+                        characterRef.current?.focus();
+                    } }) })), telling && about && (_jsx(Dialog, { title: `About ${about.name ?? name}`, onClose: () => {
+                    setTelling(false);
+                    characterRef.current?.focus();
+                }, "data-assistant-about": "", children: [
+                    ['Agent', about.name],
+                    ['Spec', about.spec],
+                    ['Model', about.model],
+                    ['Runs', about.where],
+                    ['Character', name],
+                ]
+                    .filter(([, value]) => value)
+                    .map(([key, value]) => (_jsxs(Text, { as: "p", sx: { m: 0, mb: 1 }, children: [_jsxs(Text, { sx: { color: 'fg.muted' }, children: [key, ": "] }), value] }, key))) }))] }));
 }
 export default AssistantStage;

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

@@ -45,10 +45,24 @@ export declare function ConversationBalloonHeader({ count, }: {
  * done — the tool line while a tool runs, else the words — cut to a few
  * lines, never scrolled; and what goes with them (`attachment`).
  */
-export declare function CurrentBalloonBody({ text, tool, busy, speaking, attachment, }: {
+export declare function CurrentBalloonBody({ text, tool, busy, speaking, attachment, waiting, whole, fullText, onOverflow, }: {
+    /**
+     * Shown whole: the full text (`fullText`, else `text`), unclamped, in a
+     * taller box that scrolls.
+     */
+    whole?: boolean;
+    /** The text uncut, when `text` was cut to fit (`…`). */
+    fullText?: string;
+    /** Whether the clamped text overflows its lines: *more* has more to show. */
+    onOverflow?: (overflowing: boolean) => void;
     text?: string;
     tool?: BalloonToolLine;
     busy?: boolean;
+    /**
+     * At work with nothing written yet (thinking, working, waiting): the
+     * chat's three dots follow the line, or stand alone.
+     */
+    waiting?: boolean;
     /** Words are arriving: read out once they have. */
     speaking?: boolean;
     attachment?: ReactNode;

package/lib/chat/assistant/BalloonParts.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { Text } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { CheckIcon, ToolsIcon, XIcon } from '@primer/octicons-react';
 import { SpecMark, hasMark, marksOfToolCall } from '../marks';
+import { TypingDots } from '../indicators/TypingDots';
 import { toolAnnouncement, toolLineParts, } from './toolLine';
 /** Out of sight, still heard. */
 const VISUALLY_HIDDEN = {
@@ -129,12 +130,28 @@ export function ConversationBalloonHeader({ count, }) {
  * done — the tool line while a tool runs, else the words — cut to a few
  * lines, never scrolled; and what goes with them (`attachment`).
  */
-export function CurrentBalloonBody({ text, tool, busy = false, speaking = false, attachment, }) {
-    return (_jsxs(Box, { "data-balloon-current": "", sx: { display: 'flex', flexDirection: 'column', gap: 1, minWidth: 0 }, children: [_jsx(BalloonNow, { busy: busy }), tool ? (_jsx(BalloonToolLineView, { line: tool })) : text ? (_jsx(Box, { "aria-live": "polite", "aria-busy": speaking, "data-balloon-current-text": "", sx: {
-                    display: '-webkit-box',
-                    WebkitLineClamp: 4,
-                    WebkitBoxOrient: 'vertical',
-                    overflow: 'hidden',
-                    overflowWrap: 'anywhere',
-                }, children: text })) : null, attachment, _jsx(ToolLineAnnouncer, { line: tool })] }));
+export function CurrentBalloonBody({ text, tool, busy = false, speaking = false, attachment, waiting = false, whole = false, fullText, onOverflow, }) {
+    const textRef = useRef(null);
+    useLayoutEffect(() => {
+        const element = textRef.current;
+        if (!element || whole || !onOverflow) {
+            return;
+        }
+        onOverflow(element.scrollHeight > element.clientHeight + 1);
+    }, [text, whole, onOverflow]);
+    return (_jsxs(Box, { "data-balloon-current": "", sx: { display: 'flex', flexDirection: 'column', gap: 1, minWidth: 0 }, children: [_jsx(BalloonNow, { busy: busy }), tool ? (_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(BalloonToolLineView, { line: tool }), waiting && _jsx(TypingDots, { size: 5 })] })) : text ? (_jsxs(Box, { "aria-live": "polite", "aria-busy": speaking, ref: textRef, "data-balloon-current-text": whole ? 'whole' : '', sx: whole
+                    ? {
+                        maxHeight: 240,
+                        overflowY: 'auto',
+                        overflowWrap: 'anywhere',
+                        whiteSpace: 'pre-wrap',
+                        pr: 1,
+                    }
+                    : {
+                        display: '-webkit-box',
+                        WebkitLineClamp: 4,
+                        WebkitBoxOrient: 'vertical',
+                        overflow: 'hidden',
+                        overflowWrap: 'anywhere',
+                    }, children: [whole ? (fullText ?? text) : text, waiting && (_jsx(Box, { as: "span", sx: { ml: 2, display: 'inline-flex' }, children: _jsx(TypingDots, { size: 5 }) }))] })) : waiting ? (_jsx(TypingDots, { size: 6 })) : null, attachment, _jsx(ToolLineAnnouncer, { line: tool })] }));
 }

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

@@ -19,8 +19,16 @@ export interface BalloonVisual {
     id: string;
     /** What it is: `Accounting's notebook`; the dialog's title. */
     title: string;
-    /** The visual, large: drawn only once it is expanded. */
-    render: () => ReactNode;
+    /**
+     * The visual, large: drawn only once it is expanded — in the page's
+     * target, or in a dialog, which already shows `title`.
+     */
+    render: (place: 'target' | 'overlay') => ReactNode;
+    /**
+     * Large, it shrinks back into the balloon (*Shrink*) rather than closes:
+     * the balloon's own content drawn large, such as its history.
+     */
+    shrink?: boolean;
 }
 /** Where an expanded visual goes: an element of the page, or none (a dialog). */
 export type BalloonExpandTarget = RefObject<HTMLElement | null>;

package/lib/chat/assistant/BalloonVisual.js

@@ -3,7 +3,7 @@ import { createContext, useContext } from 'react';
 import { createPortal } from 'react-dom';
 import { Button, Dialog, IconButton } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { ScreenFullIcon, XIcon } from '@primer/octicons-react';
+import { ScreenFullIcon, ScreenNormalIcon, XIcon, } from '@primer/octicons-react';
 /**
  * Expands the visual of the balloon it is in: what its compact form (a
  * notebook's preview) calls when it is clicked. None outside such a balloon.
@@ -29,14 +29,14 @@ export function ExpandedVisual({ visual, target, onClose, }) {
         if (!element) {
             return null;
         }
-        return createPortal(_jsxs(Box, { "data-balloon-expanded": "target", "data-balloon-visual": visual.id, sx: { position: 'relative', minWidth: 0 }, children: [_jsx(Box, { sx: { position: 'absolute', top: 0, right: 0, zIndex: 1 }, children: _jsx(IconButton, { icon: XIcon, size: "small", variant: "invisible", "aria-label": `Close ${visual.title}`, "data-balloon-expanded-close": "", onClick: onClose }) }), visual.render()] }), element);
+        return createPortal(_jsxs(Box, { "data-balloon-expanded": "target", "data-balloon-visual": visual.id, sx: { position: 'relative', minWidth: 0 }, children: [_jsx(Box, { sx: { position: 'absolute', top: 0, right: 0, zIndex: 1 }, children: _jsx(IconButton, { icon: visual.shrink ? ScreenNormalIcon : XIcon, size: "small", variant: "invisible", "aria-label": `${visual.shrink ? 'Shrink' : 'Close'} ${visual.title}`, "data-balloon-expanded-close": "", ...(visual.shrink ? { 'data-balloon-shrink': '' } : {}), onClick: onClose }) }), visual.render('target')] }), element);
     }
     return (_jsx(Dialog, { title: visual.title, onClose: onClose, sx: {
             width: EXPANDED_DIALOG_SIZE.width,
             maxWidth: EXPANDED_DIALOG_SIZE.width,
             height: EXPANDED_DIALOG_SIZE.height,
             maxHeight: EXPANDED_DIALOG_SIZE.height,
-        }, children: _jsx(Box, { "data-balloon-expanded": "overlay", "data-balloon-visual": visual.id, sx: { minWidth: 0 }, children: visual.render() }) }));
+        }, children: _jsxs(Box, { "data-balloon-expanded": "overlay", "data-balloon-visual": visual.id, sx: { minWidth: 0 }, children: [visual.shrink && (_jsx(Button, { size: "small", variant: "invisible", leadingVisual: ScreenNormalIcon, onClick: onClose, "data-balloon-shrink": "", sx: { float: 'right' }, children: "Shrink" })), visual.render('overlay')] }) }));
 }
 /**
  * Brings an expanded visual into view in its target: scrolled to, and the

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

@@ -13,6 +13,9 @@
  * them all — the person's and the agent's, under a header that counts them,
  * scrolled to the newest — rather than the newest line alone.
  *
+ * Given suggestions while the agent waits for a question, it offers them as
+ * chips under its words: one clicked is sent as the person's prompt.
+ *
  * Shown `current` (LOOP T-23), it is the one thing being said or done now:
  * *Now*, then the words as they are written, or the tool being called
  * ("Using **list_invoices**…"), cut to a few lines, and what goes with them
@@ -26,6 +29,16 @@ import type { JSX, ReactNode } from 'react';
 import { type BalloonApproval, type BalloonHistoryMessage } from './state';
 import type { DecisionAsker } from './decisions';
 import type { BalloonDisplay, BalloonToolLine } from './toolLine';
+/** A suggestion the balloon offers: its label, and the prompt it sends. */
+export type BalloonSuggestion = {
+    label: string;
+    prompt: string;
+};
+/** The suggestions, as chips: each sends its prompt. */
+export declare function BalloonSuggestions({ suggestions, onSuggestion, }: {
+    suggestions: readonly BalloonSuggestion[];
+    onSuggestion: (suggestion: BalloonSuggestion) => void;
+}): JSX.Element;
 export interface SpeechBalloonProps {
     text: string;
     /** There is more than the balloon holds. */
@@ -75,10 +88,43 @@ export interface SpeechBalloonProps {
     onExpand?: () => void;
     /** What the large visual is, for the *Expand* button: `Accounting's notebook`. */
     expandTitle?: string;
+    /** Draws the listed history large (`history` display): its *Expand*. */
+    onExpandHistory?: () => void;
+    /**
+     * What the person may ask, as chips under the words: one clicked is sent
+     * as the prompt (`onSuggestion`), as if typed and asked.
+     */
+    suggestions?: readonly BalloonSuggestion[];
+    onSuggestion?: (suggestion: BalloonSuggestion) => void;
+    /**
+     * At work with nothing written yet: the chat's three dots — after the
+     * current line, or last in the history — until words arrive.
+     */
+    waiting?: boolean;
+    /**
+     * The words uncut, when `text` was cut to fit: *more* shows them whole,
+     * in the balloon, *less* folds them back.
+     */
+    fullText?: string;
 }
 /** How tall the listed conversation grows before it scrolls, in pixels. */
 export declare const BALLOON_HISTORY_MAX_HEIGHT = 220;
 /** Shorter, when something goes with the words under it (a notebook). */
 export declare const BALLOON_HISTORY_WITH_ATTACHMENT_MAX_HEIGHT = 120;
-export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, approval, decide, onDecisionActive, wide, onDismissPeek, display, tool, speaking, busy, attachment, history, onExpand, expandTitle, }: SpeechBalloonProps): JSX.Element;
+/**
+ * The conversation in the `history` balloon: a header that counts it and
+ * opens it, then every message, the person's to the right, scrolled to the
+ * newest.
+ */
+/**
+ * The history balloon, large (*Expand*): every message, then the tool being
+ * called and what goes with the words, in the overlay or the page's area,
+ * scrolled there.
+ */
+export declare function BalloonHistoryLarge({ history, tool, attachment, }: {
+    history: readonly BalloonHistoryMessage[];
+    tool?: BalloonToolLine;
+    attachment?: ReactNode;
+}): JSX.Element;
+export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, approval, decide, onDecisionActive, wide, onDismissPeek, display, tool, speaking, busy, attachment, history, onExpand, expandTitle, suggestions, onSuggestion, waiting, fullText, onExpandHistory, }: SpeechBalloonProps): JSX.Element;
 export default SpeechBalloon;

package/lib/chat/assistant/SpeechBalloon.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { Button, IconButton, Text } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { XIcon } from '@primer/octicons-react';
@@ -8,6 +8,12 @@ import { moreWaiting } from './ConversationBalloon';
 import { DecisionAsk } from './DecisionAsk';
 import { BalloonToolLineView, CurrentBalloonBody, ToolLineAnnouncer, conversationHeaderText, } from './BalloonParts';
 import { BalloonExpandButton } from './BalloonVisual';
+import { ScreenFullIcon } from '@primer/octicons-react';
+import { TypingDots } from '../indicators/TypingDots';
+/** The suggestions, as chips: each sends its prompt. */
+export function BalloonSuggestions({ suggestions, onSuggestion, }) {
+    return (_jsx(Box, { role: "group", "aria-label": "Suggestions", "data-balloon-suggestions": "", sx: { display: 'flex', flexWrap: 'wrap', gap: 1, mt: 2 }, children: suggestions.map(suggestion => (_jsx(Button, { size: "small", "data-balloon-suggestion": suggestion.label, "aria-label": `Ask: ${suggestion.prompt}`, title: suggestion.prompt, onClick: () => onSuggestion(suggestion), sx: { borderRadius: 999 }, children: suggestion.label }, suggestion.label))) }));
+}
 /** How tall the listed conversation grows before it scrolls, in pixels. */
 export const BALLOON_HISTORY_MAX_HEIGHT = 220;
 /** Shorter, when something goes with the words under it (a notebook). */
@@ -17,7 +23,24 @@ export const BALLOON_HISTORY_WITH_ATTACHMENT_MAX_HEIGHT = 120;
  * opens it, then every message, the person's to the right, scrolled to the
  * newest.
  */
-function BalloonHistory({ history, onOpen, maxHeight = BALLOON_HISTORY_MAX_HEIGHT, }) {
+/**
+ * The history balloon, large (*Expand*): every message, then the tool being
+ * called and what goes with the words, in the overlay or the page's area,
+ * scrolled there.
+ */
+export function BalloonHistoryLarge({ history, tool, attachment, }) {
+    return (_jsxs(Box, { role: "log", "aria-label": "Conversation", "data-balloon-history-large": "", sx: { display: 'flex', flexDirection: 'column', gap: 2, fontSize: 1 }, children: [history.map(message => (_jsx(Box, { "data-balloon-history-message": message.role, sx: {
+                    alignSelf: message.role === 'user' ? 'flex-end' : 'flex-start',
+                    maxWidth: '80%',
+                    px: 3,
+                    py: 2,
+                    borderRadius: 2,
+                    bg: message.role === 'user' ? 'accent.subtle' : 'canvas.subtle',
+                    whiteSpace: 'pre-wrap',
+                    overflowWrap: 'anywhere',
+                }, children: message.text }, message.id))), tool ? _jsx(BalloonToolLineView, { line: tool }) : null, attachment ? _jsx(Box, { children: attachment }) : null] }));
+}
+function BalloonHistory({ history, onOpen, maxHeight = BALLOON_HISTORY_MAX_HEIGHT, onExpand, }) {
     const listRef = useRef(null);
     const newest = history[history.length - 1]?.id;
     useEffect(() => {
@@ -39,7 +62,7 @@ function BalloonHistory({ history, onOpen, maxHeight = BALLOON_HISTORY_MAX_HEIGH
                     fontWeight: 'semibold',
                     color: 'fg.muted',
                     '&:hover': { textDecoration: 'underline' },
-                }, children: conversationHeaderText(history.length) }), _jsx(Box, { ref: listRef, role: "log", "aria-label": "Conversation", "data-balloon-history-list": "", sx: {
+                }, children: conversationHeaderText(history.length) }), onExpand ? (_jsx(IconButton, { icon: ScreenFullIcon, size: "small", variant: "invisible", "aria-label": "Expand the conversation", "data-balloon-history-expand": "", onClick: onExpand, sx: { position: 'absolute', top: '4px', right: '28px' } })) : null, _jsx(Box, { ref: listRef, role: "log", "aria-label": "Conversation", "data-balloon-history-list": "", sx: {
                     maxHeight,
                     overflowY: 'auto',
                     display: 'flex',
@@ -56,7 +79,19 @@ function BalloonHistory({ history, onOpen, maxHeight = BALLOON_HISTORY_MAX_HEIGH
                         overflowWrap: 'anywhere',
                     }, children: message.text }, message.id))) })] }));
 }
-export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above', align, tailAt, approval, decide, onDecisionActive, wide = false, onDismissPeek, display = 'history', tool, speaking = false, busy = false, attachment, history, onExpand, expandTitle, }) {
+export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above', align, tailAt, approval, decide, onDecisionActive, wide = false, onDismissPeek, display = 'history', tool, speaking = false, busy = false, attachment, history, onExpand, expandTitle, suggestions, onSuggestion, waiting = false, fullText, onExpandHistory, }) {
+    // *more*: the words whole, when they were cut or overflow their lines.
+    const [whole, setWhole] = useState(false);
+    const [overflowing, setOverflowing] = useState(false);
+    const cut = (!!fullText && fullText !== text) || (!!more && text.endsWith('…'));
+    const wholeText = fullText ?? text;
+    // Other words, folded again.
+    useEffect(() => {
+        setWhole(false);
+    }, [wholeText.slice(0, 40)]);
+    const offered = suggestions && suggestions.length > 0 && onSuggestion && !approval
+        ? suggestions
+        : null;
     const current = display === 'current';
     // History with messages to list: all of them, not the newest line alone.
     const listed = !current && history && history.length > 0 ? history : null;
@@ -68,8 +103,14 @@ export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above
                 ? { bottom: `${above}px` }
                 : { top: `${above}px` }),
             [align]: 0,
-            maxWidth: wide || listed || (current && attachment) ? 300 : current ? 260 : 280,
-            width: wide || listed || (current && attachment) ? 300 : 'max-content',
+            maxWidth: wide || listed || offered || whole || (current && attachment)
+                ? 300
+                : current
+                    ? 260
+                    : 280,
+            width: wide || listed || offered || whole || (current && attachment)
+                ? 300
+                : 'max-content',
             px: 3,
             py: 2,
             bg: 'canvas.default',
@@ -106,7 +147,7 @@ export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above
                             font: 'inherit',
                             textAlign: 'left',
                             cursor: 'pointer',
-                        }, children: _jsx(CurrentBalloonBody, { text: text, tool: tool, busy: busy, speaking: speaking }) })) : listed ? (_jsx(BalloonHistory, { history: listed, onOpen: onOpen, maxHeight: attachment
+                        }, children: _jsx(CurrentBalloonBody, { text: text, tool: tool, busy: busy, speaking: speaking, waiting: waiting, whole: whole, fullText: wholeText, onOverflow: setOverflowing }) })) : listed ? (_jsx(BalloonHistory, { history: listed, onOpen: onOpen, onExpand: onExpandHistory, maxHeight: attachment
                             ? BALLOON_HISTORY_WITH_ATTACHMENT_MAX_HEIGHT
                             : BALLOON_HISTORY_MAX_HEIGHT })) : (_jsx(Box, { as: "button", type: "button", "data-balloon-peek": "", "data-balloon-more": more ? '' : undefined, onClick: onOpen, sx: {
                             flex: 1,
@@ -120,6 +161,17 @@ export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above
                             textAlign: 'left',
                             cursor: 'pointer',
                             '&:hover': { textDecoration: 'underline' },
-                        }, children: tool ? (_jsx(BalloonToolLineView, { line: tool })) : (_jsx(Box, { as: "span", role: "status", "aria-live": "polite", 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] }), listed && tool ? (_jsx(Box, { "data-balloon-history-tool": "", sx: { mt: 1 }, children: _jsx(BalloonToolLineView, { line: tool }) })) : 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] })), attachment ? (_jsxs(Box, { "data-balloon-attachment": "", sx: { mt: 2, display: 'flex', flexDirection: 'column', gap: 1 }, children: [attachment, onExpand ? (_jsx(BalloonExpandButton, { title: expandTitle ?? 'the visual', onExpand: onExpand })) : null] })) : null, !current ? _jsx(ToolLineAnnouncer, { line: tool }) : null, decide && _jsx(DecisionAsk, { ask: decide, onActiveChange: onDecisionActive })] }));
+                        }, children: tool ? (_jsx(BalloonToolLineView, { line: tool })) : (_jsx(Box, { as: "span", role: "status", "aria-live": "polite", 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] }), current && !approval && !tool && (cut || overflowing || whole) ? (_jsx(Box, { as: "button", type: "button", "aria-expanded": whole, "data-balloon-whole": whole ? 'less' : 'more', onClick: () => setWhole(!whole), sx: {
+                    m: 0,
+                    mt: 1,
+                    p: 0,
+                    border: 0,
+                    bg: 'transparent',
+                    color: 'accent.fg',
+                    font: 'inherit',
+                    fontSize: 0,
+                    cursor: 'pointer',
+                    '&:hover': { textDecoration: 'underline' },
+                }, children: whole ? 'less' : 'more' })) : null, listed && tool ? (_jsx(Box, { "data-balloon-history-tool": "", sx: { mt: 1 }, children: _jsx(BalloonToolLineView, { line: tool }) })) : null, !current && waiting ? (_jsx(Box, { "data-balloon-waiting": "", sx: { mt: 1 }, children: _jsx(TypingDots, { size: 6 }) })) : 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] })), offered && onSuggestion ? (_jsx(BalloonSuggestions, { suggestions: offered, onSuggestion: onSuggestion })) : null, attachment ? (_jsxs(Box, { "data-balloon-attachment": "", sx: { mt: 2, display: 'flex', flexDirection: 'column', gap: 1 }, children: [attachment, onExpand ? (_jsx(BalloonExpandButton, { title: expandTitle ?? 'the visual', onExpand: onExpand })) : null] })) : null, !current ? _jsx(ToolLineAnnouncer, { line: tool }) : null, decide && _jsx(DecisionAsk, { ask: decide, onActiveChange: onDecisionActive })] }));
 }
 export default SpeechBalloon;