@datalayer/agent-runtimes 1.3.73 → 1.3.74

package/lib/chat/ChatFloating.d.ts

@@ -18,6 +18,7 @@
 import React from 'react';
 import type { ChatVoice } from '../voice';
 import { type BalloonDisplay, type BalloonToolLine } from './assistant/toolLine';
+import type { BalloonExpandTarget } from './assistant/BalloonVisual';
 import { type AssistantCharacter } from './assistant/characters';
 import type { AssistantCharacterData } from './assistant/formats/types';
 import { type AssistantSaying } from './assistant/state';
@@ -118,7 +119,7 @@ export interface ChatFloatingProps extends ChatCommonProps {
      * How the floating assistant's balloon shows the conversation (LOOP
      * T-23; an Appspec's `interface.balloon`):
      * - 'history': every message, scrolled, under a header that counts them,
-     *   the composer last; closed, a peek of the newest words.
+     *   the composer last; closed, the balloon lists the messages too.
      * - 'current': only what it says or does now — the answer being written,
      *   or the tool it calls — in one compact balloon, *Now* on it; open, that
      *   line and the composer, nothing to scroll.
@@ -126,6 +127,12 @@ export interface ChatFloatingProps extends ChatCommonProps {
      * @default 'history'
      */
     balloonDisplay?: BalloonDisplay;
+    /**
+     * Where a large visual the assistant's balloon carries (a notebook) is
+     * drawn when expanded: an element of the page, through a portal; unsaid,
+     * a large dialog over the page.
+     */
+    expandTarget?: BalloonExpandTarget;
     /**
      * The runtime the floating assistant asks typed decisions at — its
      * `/api/v1/configure/inference/decisions`, as the `decide` tool asks — and
@@ -177,5 +184,5 @@ export interface ChatFloatingProps extends ChatCommonProps {
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, themeOverrides, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, assistantCharacter, balloonDisplay, conversation, decisions, voice, }: ChatFloatingProps): React.JSX.Element;
+export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, themeOverrides, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, assistantCharacter, balloonDisplay, expandTarget, conversation, decisions, voice, }: ChatFloatingProps): React.JSX.Element;
 export default ChatFloating;

package/lib/chat/ChatFloating.js

@@ -40,7 +40,7 @@ import { ConversationBalloonHeader, CurrentBalloonBody, } from './assistant/Ball
 import { DEFAULT_BALLOON_DISPLAY, conversationCount, newestToolLine, toolLineText, } from './assistant/toolLine';
 import { SpeechBalloon } from './assistant/SpeechBalloon';
 import { DEFAULT_ASSISTANT_CHARACTER, } from './assistant/characters';
-import { assistantStateOf, latestSaying, newestIsAnswer, keepAway, keptAway, ASSISTANT_WORDS, } from './assistant/state';
+import { assistantStateOf, balloonHistoryOf, latestSaying, newestIsAnswer, keepAway, keptAway, ASSISTANT_WORDS, } from './assistant/state';
 import { presenceState, presenceToolOf, } from './presence/presenceStatus';
 import { useChatOpen, useChatMessages, useChatStore, } from '../stores/chatStore';
 import { useChatKeyboardShortcuts, getShortcutDisplay, } from '@datalayer/core/lib/hooks';
@@ -70,7 +70,7 @@ const clamp = (value, max) => Math.max(8, Math.min(value, Math.max(8, max)));
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, themeOverrides, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, assistantCharacter = DEFAULT_ASSISTANT_CHARACTER, balloonDisplay = DEFAULT_BALLOON_DISPLAY, conversation, decisions, voice, }) {
+export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, themeOverrides, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, assistantCharacter = DEFAULT_ASSISTANT_CHARACTER, balloonDisplay = DEFAULT_BALLOON_DISPLAY, expandTarget, conversation, decisions, voice, }) {
     // Store-based state
     const storeIsOpen = useChatOpen();
     const storeMessages = useChatMessages();
@@ -136,6 +136,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
     // The tool it calls now, and how many messages the history holds (T-23).
     const [ownTool, setOwnTool] = useState();
     const [messageCount, setMessageCount] = useState(0);
+    // The conversation's messages, listed in the closed `history` balloon.
+    const [ownHistory, setOwnHistory] = useState([]);
     /*
      * Its voice (VOICE.md V1): the answers said by the speech service, as
      * they are written (VO-20), the state following the sound (VO-22).
@@ -259,6 +261,11 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
     const toolSaid = toolLine && (toolLine.phase === 'running' || atWork) ? toolLine : undefined;
     // Current: what is said now — thinking until the answer's words arrive.
     const currentWords = atWork && !answering ? 'Thinking…' : saying?.text || undefined;
+    // History: the closed balloon lists the conversation, not its newest line.
+    const listedHistory = !showsCurrent && !conversation && ownHistory.length > 0
+        ? ownHistory
+        : undefined;
+    const withHistory = (said) => listedHistory ? { ...said, history: listedHistory } : said;
     const assistantBalloon = assistantState === 'paused'
         ? { text: ASSISTANT_WORDS.paused }
         : speakerState.sentence
@@ -267,11 +274,18 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             : speakerState.refused
                 ? { text: speakerState.refused }
                 : balloonApproval
-                    ? { text: ASSISTANT_WORDS.approval, approval: balloonApproval }
+                    ? withHistory({
+                        text: ASSISTANT_WORDS.approval,
+                        approval: balloonApproval,
+                    })
                     : assistantState === 'waiting'
                         ? { text: ASSISTANT_WORDS.waiting }
                         : toolSaid
-                            ? { text: toolLineText(toolSaid), tool: toolSaid, busy: atWork }
+                            ? withHistory({
+                                text: toolLineText(toolSaid),
+                                tool: toolSaid,
+                                busy: atWork,
+                            })
                             : showsCurrent && (unheard || atWork)
                                 ? // Current: the words as they are written, whole.
                                     {
@@ -287,15 +301,16 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                                             : undefined,
                                     }
                                 : unheard && saying
-                                    ? {
-                                        // A peek: the first words; the rest is in the conversation.
+                                    ? withHistory({
+                                        // A peek: the first words; the rest is in the
+                                        // conversation, listed when there is one.
                                         ...peekLine(saying.text),
                                         onDismiss: () => {
                                             setHeardId(saying.id);
                                             setFreshSaying(false);
                                         },
-                                    }
-                                    : { text: description };
+                                    })
+                                    : withHistory({ text: description });
     const balloonInsists = !!speakerState.sentence ||
         assistantState === 'greeting' ||
         assistantState === 'waiting' ||
@@ -321,6 +336,12 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             ? previous
             : line);
         setMessageCount(conversationCount(items));
+        const listed = balloonHistoryOf(items);
+        setOwnHistory(previous => previous.length === listed.length &&
+            previous.every((message, index) => message.id === listed[index].id &&
+                message.text === listed[index].text)
+            ? previous
+            : listed);
         setVoiceItems(items);
         const said = latestSaying(items);
         setSaying(previous => previous?.id === said?.id && previous?.text === said?.text
@@ -1050,7 +1071,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, balloonDisplay: balloonDisplay, insist: balloonInsists, onDismiss: dismissAssistant, ownRef: popupRef, mouthLevel: mouthLevel })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
+                    : getPositionStyles(), stageRef: stageRef, onDragStart: stageDrag.onHandlePointerDown, open: isOpen, onToggle: handleToggle, balloon: assistantBalloon, balloonDisplay: balloonDisplay, expandTarget: expandTarget, insist: balloonInsists, onDismiss: dismissAssistant, ownRef: popupRef, mouthLevel: mouthLevel })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
                     ...getPositionStyles(),
                 }, children: _jsxs(Box, { sx: {
                         position: 'relative',

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

@@ -16,10 +16,11 @@
  */
 import type { JSX, ReactNode, RefObject } from 'react';
 import { type AssistantCharacter } from './characters';
+import { type BalloonExpandTarget, type BalloonVisual } from './BalloonVisual';
 import type { AssistantCharacterData } from './formats/types';
 import type { DecisionAsker } from './decisions';
 import type { BalloonDisplay, BalloonToolLine } from './toolLine';
-import { type AssistantAway, type AssistantState, type BalloonApproval } from './state';
+import { type AssistantAway, type AssistantState, type BalloonApproval, type BalloonHistoryMessage } from './state';
 /**
  * Where the balloon goes so that it stays inside the window (T-23): toward
  * the middle of the page from whichever half the character stands in, and
@@ -88,11 +89,34 @@ export interface AssistantStageProps {
         busy?: boolean;
         /** What goes with the words (`current`): a notebook given, read-only. */
         attachment?: ReactNode;
+        /**
+         * The conversation's messages (`history`): the balloon lists them all,
+         * counted and scrolled, rather than the newest line alone.
+         */
+        history?: readonly BalloonHistoryMessage[];
+        /**
+         * The large visual `attachment` is the compact form of (a notebook):
+         * the balloon offers *Expand*, and draws it large — into
+         * `expandTarget`, or in a dialog over the page.
+         */
+        visual?: BalloonVisual;
     };
     /**
-     * How the balloon shows the conversation (LOOP T-23): a peek of it
-     * (`history`, the default — open, the conversation is the whole history),
-     * or the one thing being said or done now (`current`).
+     * Where a balloon's large visual is drawn when expanded: an element of
+     * the page (through a portal), such as the area under a team's graph;
+     * without one, a large dialog over the page.
+     */
+    expandTarget?: BalloonExpandTarget;
+    /**
+     * Draw a large visual into `expandTarget` as soon as it arrives, without
+     * waiting for *Expand*: a team's notebook, under its graph.
+     */
+    expandOnArrival?: boolean;
+    /**
+     * How the balloon shows the conversation (LOOP T-23): the conversation
+     * (`history`, the default — closed, the messages in `balloon.history`, or
+     * a peek of the newest when none are given; open, the whole history), or
+     * the one thing being said or done now (`current`).
      */
     balloonDisplay?: BalloonDisplay;
     /** Show the balloon without being hovered: something new to say. */
@@ -129,5 +153,5 @@ export declare function mouthOpening(level: number): 0 | 1 | 2 | 3;
  * `data-assistant-mouth`, each frame, without drawing the character again.
  */
 export declare function useMouth(stageRef: RefObject<HTMLElement | null>, mouthLevel: (() => number) | undefined, speaking: boolean): void;
-export declare function AssistantStage({ character, state, size, place, stageRef, onDragStart, open, onToggle, balloon, insist, onDismiss, ownRef, decide, mouthLevel, stayPut, balloonDisplay, }: AssistantStageProps): JSX.Element;
+export declare function AssistantStage({ character, state, size, place, stageRef, onDragStart, open, onToggle, balloon, insist, onDismiss, ownRef, decide, mouthLevel, stayPut, balloonDisplay, expandTarget, expandOnArrival, }: AssistantStageProps): JSX.Element;
 export default AssistantStage;

package/lib/chat/assistant/AssistantStage.js

@@ -5,6 +5,7 @@ import { Box } from '@datalayer/primer-addons';
 import { XIcon } from '@primer/octicons-react';
 import { assistantCharacter } from './characters';
 import { SpeechBalloon } from './SpeechBalloon';
+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. */
@@ -209,7 +210,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, }) {
     // 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'
@@ -232,6 +233,23 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
     // A decision being asked, or its answer, keeps the balloon up.
     const [deciding, setDeciding] = useState(false);
     const showBalloon = !aside && !open && !!balloon && (hovered || insist || deciding);
+    // 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;
+    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,7 +349,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, 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: [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) => {
                     pressedAt.current = { x: event.clientX, y: event.clientY };
                     onDragStart(event);
                 }, onClick: (event) => {

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

@@ -0,0 +1,57 @@
+/**
+ * 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. */
+    render: () => ReactNode;
+}
+/** 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, 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: XIcon, size: "small", variant: "invisible", "aria-label": `Close ${visual.title}`, "data-balloon-expanded-close": "", onClick: onClose }) }), visual.render()] }), 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() }) }));
+}
+/**
+ * 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,10 @@
  * 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.
+ *
  * 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,7 +23,7 @@
  * @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';
 export interface SpeechBalloonProps {
@@ -59,6 +63,22 @@ 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;
 }
-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;
+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;
 export default SpeechBalloon;

package/lib/chat/assistant/SpeechBalloon.js

@@ -1,13 +1,65 @@
 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';
+import { ASSISTANT_WORDS, } from './state';
 import { moreWaiting } from './ConversationBalloon';
 import { DecisionAsk } from './DecisionAsk';
-import { BalloonToolLineView, CurrentBalloonBody, ToolLineAnnouncer, } from './BalloonParts';
-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, }) {
+import { BalloonToolLineView, CurrentBalloonBody, ToolLineAnnouncer, conversationHeaderText, } from './BalloonParts';
+import { BalloonExpandButton } from './BalloonVisual';
+/** 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). */
+export 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.
+ */
+function BalloonHistory({ history, onOpen, maxHeight = BALLOON_HISTORY_MAX_HEIGHT, }) {
+    const listRef = useRef(null);
+    const newest = history[history.length - 1]?.id;
+    useEffect(() => {
+        const list = listRef.current;
+        if (list) {
+            list.scrollTop = list.scrollHeight;
+        }
+    }, [history.length, newest]);
+    return (_jsxs(Box, { "data-balloon-history": "", sx: { flex: 1, minWidth: 0, display: 'flex', flexDirection: 'column' }, children: [_jsx(Box, { as: "button", type: "button", "data-balloon-peek": "", "data-balloon-header": "", onClick: onOpen, sx: {
+                    m: 0,
+                    p: 0,
+                    pb: 1,
+                    border: 0,
+                    bg: 'transparent',
+                    font: 'inherit',
+                    textAlign: 'left',
+                    cursor: 'pointer',
+                    fontSize: 0,
+                    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: {
+                    maxHeight,
+                    overflowY: 'auto',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: 1,
+                    pr: 1,
+                }, children: history.map(message => (_jsx(Box, { "data-balloon-history-message": message.role, sx: {
+                        alignSelf: message.role === 'user' ? 'flex-end' : 'flex-start',
+                        maxWidth: '88%',
+                        px: 2,
+                        py: 1,
+                        borderRadius: 2,
+                        bg: message.role === 'user' ? 'accent.subtle' : 'canvas.subtle',
+                        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, }) {
     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;
     return (_jsxs(Box, { "data-speech-balloon": "", "data-balloon-display": display, sx: {
             position: 'absolute',
             // Pixels, as strings: a number here is read as the theme's space
@@ -16,8 +68,8 @@ export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above
                 ? { bottom: `${above}px` }
                 : { top: `${above}px` }),
             [align]: 0,
-            maxWidth: wide || (current && attachment) ? 300 : current ? 260 : 280,
-            width: wide || (current && attachment) ? 300 : 'max-content',
+            maxWidth: wide || listed || (current && attachment) ? 300 : current ? 260 : 280,
+            width: wide || listed || (current && attachment) ? 300 : 'max-content',
             px: 3,
             py: 2,
             bg: 'canvas.default',
@@ -54,7 +106,9 @@ 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 }) })) : (_jsx(Box, { as: "button", type: "button", "data-balloon-peek": "", "data-balloon-more": more ? '' : undefined, onClick: onOpen, sx: {
+                        }, children: _jsx(CurrentBalloonBody, { text: text, tool: tool, busy: busy, speaking: speaking }) })) : listed ? (_jsx(BalloonHistory, { history: listed, onOpen: onOpen, 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,
                             minWidth: 0,
                             m: 0,
@@ -66,6 +120,6 @@ 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] }), 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] })), current && attachment ? (_jsx(Box, { "data-balloon-attachment": "", sx: { mt: 2 }, children: attachment })) : 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] }), 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 })] }));
 }
 export default SpeechBalloon;

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

@@ -79,6 +79,25 @@ export interface AssistantSaying {
 }
 /** How much of a message is kept as the agent's saying before it is cut. */
 export declare const SAYING_LIMIT = 220;
+/**
+ * A message's content as plain words, for a balloon: its text parts joined,
+ * code blocks left out, links and Markdown read as plain words.
+ */
+export declare function plainWordsOf(content: unknown): string;
+/** A message of the conversation, as the `history` balloon lists it. */
+export interface BalloonHistoryMessage {
+    id: string;
+    /** Who said it: the person, or the agent. */
+    role: 'user' | 'assistant';
+    /** Its words, plain. */
+    text: string;
+}
+/**
+ * The conversation as the `history` balloon lists it (T-23): the person's
+ * and the agent's messages with words, in order — not the tool calls, not
+ * an empty message — the same messages its header counts.
+ */
+export declare function balloonHistoryOf(items: readonly unknown[]): BalloonHistoryMessage[];
 /**
  * The newest thing the agent said, as the Office Assistant said it: in the
  * balloon, while the conversation is closed (T-23). Only its own messages

package/lib/chat/assistant/state.js

@@ -52,6 +52,49 @@ export const ASSISTANT_WORDS = {
 };
 /** How much of a message is kept as the agent's saying before it is cut. */
 export const SAYING_LIMIT = 220;
+/**
+ * A message's content as plain words, for a balloon: its text parts joined,
+ * code blocks left out, links and Markdown read as plain words.
+ */
+export function plainWordsOf(content) {
+    const raw = typeof content === 'string'
+        ? content
+        : Array.isArray(content)
+            ? content
+                .map(part => part &&
+                typeof part === 'object' &&
+                part.type === 'text'
+                ? String(part.text ?? '')
+                : '')
+                .join(' ')
+            : '';
+    return raw
+        .replace(/```[\s\S]*?```/g, ' ')
+        .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/[*_`#>]+/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * The conversation as the `history` balloon lists it (T-23): the person's
+ * and the agent's messages with words, in order — not the tool calls, not
+ * an empty message — the same messages its header counts.
+ */
+export function balloonHistoryOf(items) {
+    const history = [];
+    items.forEach((entry, index) => {
+        const item = entry;
+        if ((item.role !== 'user' && item.role !== 'assistant') ||
+            typeof item.toolName === 'string') {
+            return;
+        }
+        const text = plainWordsOf(item.content);
+        if (text) {
+            history.push({ id: String(item.id ?? index), role: item.role, text });
+        }
+    });
+    return history;
+}
 /**
  * The newest thing the agent said, as the Office Assistant said it: in the
  * balloon, while the conversation is closed (T-23). Only its own messages
@@ -64,23 +107,7 @@ export function latestSaying(items) {
         if (item.role !== 'assistant' || typeof item.toolName === 'string') {
             continue;
         }
-        const raw = typeof item.content === 'string'
-            ? item.content
-            : Array.isArray(item.content)
-                ? item.content
-                    .map(part => part &&
-                    typeof part === 'object' &&
-                    part.type === 'text'
-                    ? String(part.text ?? '')
-                    : '')
-                    .join(' ')
-                : '';
-        const plain = raw
-            .replace(/```[\s\S]*?```/g, ' ')
-            .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
-            .replace(/[*_`#>]+/g, '')
-            .replace(/\s+/g, ' ')
-            .trim();
+        const plain = plainWordsOf(item.content);
         if (!plain) {
             continue;
         }