@datalayer/agent-runtimes 1.3.73 → 1.3.75

package/lib/chat/assistant/AssistantStage.js

@@ -1,10 +1,14 @@
 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';
 /** The motions, by the state the stage is in. */
@@ -57,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"`. */
@@ -209,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', }) {
+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'
@@ -225,13 +351,76 @@ 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;
+    const [expanded, setExpanded] = useState(null);
+    const expand = visual
+        ? () => {
+            setExpanded(visual);
+            if (expandTarget) {
+                requestAnimationFrame(() => focusExpanded(expandTarget));
+            }
+        }
+        : 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);
+        }
+    }, [visual?.id, expandOnArrival, !!expandTarget]);
     return (_jsxs(Box, { ref: stageRef, "data-assistant-state": state, "data-assistant-aside": aside, "data-assistant-balloon": balloonDisplay, sx: {
             position: 'fixed',
             zIndex: 1002,
@@ -331,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: [showBalloon && balloon && (_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, 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;
@@ -363,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

@@ -0,0 +1,65 @@
+/**
+ * A large visual a balloon carries (LOOP T-23): a notebook today, a chart or
+ * a table later. The balloon shows it compact — its `attachment`, such as
+ * the read-only preview of a notebook — with an *Expand* button; expanded,
+ * the visual is drawn large: into the element the host names
+ * (`expandTarget`, through a portal), or, when it names none, in a large
+ * dialog over the page — Esc closes it, and the focus stays in it while it
+ * is open.
+ *
+ * What the expanded visual is, the visual says (`render`): for a notebook,
+ * the one that runs and is edited on the browser sandbox (`TeamNotebook`).
+ *
+ * @module chat/assistant/BalloonVisual
+ */
+import type { JSX, ReactNode, RefObject } from 'react';
+/** A large visual a balloon carries, and how it is drawn large. */
+export interface BalloonVisual {
+    /** Its id: a new one is a new visual. */
+    id: string;
+    /** What it is: `Accounting's notebook`; the dialog's title. */
+    title: string;
+    /**
+     * 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>;
+/**
+ * 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.
+ */
+export declare const BalloonExpandContext: import("react").Context<(() => void) | null>;
+/** The balloon's way to expand its visual, if it carries one. */
+export declare function useBalloonExpand(): (() => void) | null;
+/** The balloon's *Expand* button. */
+export declare function BalloonExpandButton({ title, onExpand, }: {
+    title: string;
+    onExpand: () => void;
+}): JSX.Element;
+/** How large the dialog is when no target is named: most of the window. */
+export declare const EXPANDED_DIALOG_SIZE: {
+    readonly width: "80vw";
+    readonly height: "80vh";
+};
+/**
+ * The visual, expanded: into `target` when it names an element, else in a
+ * large dialog over the page, closed with Esc or its close button.
+ */
+export declare function ExpandedVisual({ visual, target, onClose, }: {
+    visual: BalloonVisual;
+    target?: BalloonExpandTarget;
+    onClose: () => void;
+}): JSX.Element | null;
+/**
+ * Brings an expanded visual into view in its target: scrolled to, and the
+ * first element that takes the focus there (a notebook's section) focused.
+ */
+export declare function focusExpanded(target: BalloonExpandTarget | undefined): void;

package/lib/chat/assistant/BalloonVisual.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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, 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.
+ */
+export const BalloonExpandContext = createContext(null);
+/** The balloon's way to expand its visual, if it carries one. */
+export function useBalloonExpand() {
+    return useContext(BalloonExpandContext);
+}
+/** The balloon's *Expand* button. */
+export function BalloonExpandButton({ title, onExpand, }) {
+    return (_jsx(Button, { size: "small", variant: "invisible", leadingVisual: ScreenFullIcon, "aria-label": `Expand ${title}`, "data-balloon-expand": "", onClick: onExpand, sx: { alignSelf: 'flex-start', px: 1 }, children: "Expand" }));
+}
+/** How large the dialog is when no target is named: most of the window. */
+export const EXPANDED_DIALOG_SIZE = { width: '80vw', height: '80vh' };
+/**
+ * The visual, expanded: into `target` when it names an element, else in a
+ * large dialog over the page, closed with Esc or its close button.
+ */
+export function ExpandedVisual({ visual, target, onClose, }) {
+    const element = target?.current;
+    if (target) {
+        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: 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: _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
+ * first element that takes the focus there (a notebook's section) focused.
+ */
+export function focusExpanded(target) {
+    const element = target?.current;
+    if (!element) {
+        return;
+    }
+    const still = typeof window !== 'undefined' &&
+        !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+    element.scrollIntoView?.({
+        behavior: still ? 'auto' : 'smooth',
+        block: 'start',
+    });
+    const focusable = element.querySelector('[tabindex="-1"]') ?? element;
+    focusable.focus?.({ preventScroll: true });
+}

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

@@ -9,6 +9,13 @@
  * the conversation is elsewhere (the LOOP workspace), *Ask a decision*: a
  * typed decision asked of Jev, its answer said back in the balloon.
  *
+ * Shown `history` with the conversation's messages (`history`), it lists
+ * 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
@@ -19,9 +26,19 @@
  * @module chat/assistant/SpeechBalloon
  */
 import type { JSX, ReactNode } from 'react';
-import { type BalloonApproval } from './state';
+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. */
@@ -59,6 +76,55 @@ export interface SpeechBalloonProps {
     busy?: boolean;
     /** What goes with the words, under them: a notebook given, read-only. */
     attachment?: ReactNode;
+    /**
+     * The conversation's messages (`history`): listed in the balloon, every
+     * one, in place of the newest line alone.
+     */
+    history?: readonly BalloonHistoryMessage[];
+    /**
+     * What goes with the words is a large visual (a notebook): an *Expand*
+     * button under it draws it large, named by `expandTitle`.
+     */
+    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;
 }
-export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, approval, decide, onDecisionActive, wide, onDismissPeek, display, tool, speaking, busy, attachment, }: SpeechBalloonProps): JSX.Element;
+/** 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;
+/**
+ * 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;