@datalayer/agent-runtimes 1.3.73 → 1.3.75

package/lib/chat/ChatFloating.d.ts

@@ -18,10 +18,14 @@
 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';
 import { type PresenceState } from './presence/presenceStatus';
+import type { AgentInspectorSink } from '../components/inspector/agentInspector';
+import type { AssistantMenuItem } from './assistant/AssistantContextMenu';
+import type { AssistantAbout } from './assistant/AssistantStage';
 import type { ChatCommonProps, ChatViewMode, ThemeOverrides } from '../types';
 /**
  * A conversation the host draws in the floating window, in place of the
@@ -118,7 +122,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 +130,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
@@ -165,6 +175,19 @@ export interface ChatFloatingProps extends ChatCommonProps {
      * own props (`protocol`, `suggestions`, …) are then not read.
      */
     conversation?: FloatingConversation;
+    /**
+     * The Agent Inspector's sink: the chat records its agent's turns and tool
+     * calls there, and the assistant's menu offers *Inspect the agent…*.
+     */
+    inspector?: AgentInspectorSink | null;
+    /** The balloon's display, changed from the assistant's menu. */
+    onBalloonDisplayChange?: (display: BalloonDisplay) => void;
+    /** Opens the host's character picker, from the assistant's menu. */
+    onChangeCharacter?: () => void;
+    /** What the assistant's menu's *About* says. */
+    about?: AssistantAbout;
+    /** The host's own entries of the assistant's menu. */
+    contextMenu?: readonly AssistantMenuItem[];
     /**
      * Its voice (VOICE.md V1): push-to-talk in the composer, heard on the
      * device; with `output: 'always'`, its answers said by Datalayer's speech
@@ -177,5 +200,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: balloonDisplayGiven, expandTarget, conversation, decisions, voice, inspector, onBalloonDisplayChange, onChangeCharacter, about, contextMenu, }: 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,20 @@ 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: balloonDisplayGiven = DEFAULT_BALLOON_DISPLAY, expandTarget, conversation, decisions, voice, inspector, onBalloonDisplayChange, onChangeCharacter, about, contextMenu, }) {
+    // The chat's own send, once it can: what a suggestion in the balloon sends.
+    const chatControls = useRef(null);
+    const [suggestionPrompt, setSuggestionPrompt] = useState();
+    const [speechMuted, setSpeechMuted] = useState(false);
+    // The balloon's display, as the assistant's menu chose it; the host's
+    // until then, and again when the host changes it.
+    const [chosenDisplay, setChosenDisplay] = useState();
+    useEffect(() => setChosenDisplay(undefined), [balloonDisplayGiven]);
+    const balloonDisplay = chosenDisplay ?? balloonDisplayGiven;
+    const changeBalloonDisplay = useCallback((next) => {
+        setChosenDisplay(next);
+        onBalloonDisplayChange?.(next);
+    }, [onBalloonDisplayChange]);
     // Store-based state
     const storeIsOpen = useChatOpen();
     const storeMessages = useChatMessages();
@@ -136,6 +149,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).
@@ -174,7 +189,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             window.removeEventListener('keydown', unlock);
         };
     }, [speaker]);
-    useSpokenAnswers(voiceItems, chatBusy, !!speaker, speaker);
+    useSpokenAnswers(voiceItems, chatBusy, !!speaker && !speechMuted, speaker);
     const stopSpeaking = useCallback(() => speaker?.stop(), [speaker]);
     const mouthLevel = useMemo(() => (speaker ? () => speaker.level() : undefined), [speaker]);
     const [arriving, setArriving] = useState(false);
@@ -259,6 +274,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 +287,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 +314,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' ||
@@ -303,6 +331,28 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         !!toolSaid ||
         (showsCurrent && atWork) ||
         (unheard && (assistantState === 'speaking' || freshSaying));
+    // The chat's suggestions, in the balloon while it waits for a question:
+    // one clicked is sent as the prompt, as if typed.
+    const balloonSuggestions = useMemo(() => conversation || !suggestions?.length
+        ? undefined
+        : suggestions.map(suggestion => ({
+            label: suggestion.title,
+            prompt: suggestion.message,
+        })), [conversation, suggestions]);
+    const sendSuggestion = useCallback((suggestion) => {
+        if (chatControls.current) {
+            chatControls.current.send(suggestion.prompt);
+        }
+        else {
+            // Not able to send yet: sent once it is.
+            setSuggestionPrompt(suggestion.prompt);
+        }
+    }, []);
+    const panelOnSendReady = panelProps?.onSendReady;
+    const handleSendReady = useCallback(controls => {
+        chatControls.current = controls;
+        panelOnSendReady?.(controls);
+    }, [panelOnSendReady]);
     const panelOnLoadingChange = panelProps?.onLoadingChange;
     const panelOnDisplayItemsChange = panelProps?.onDisplayItemsChange;
     const handleLoadingChange = useCallback((loading) => {
@@ -321,6 +371,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
@@ -1000,9 +1056,9 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     ...poweredByProps,
                 }, renderToolResult: renderToolResult, description: description, onStateUpdate: onStateUpdate, onNewChat: onNewChat, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: {
                     showAvatars: true,
-                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, voice: voice, voiceSpeaking: speakerState.speaking, onStopSpeaking: speaker ? stopSpeaking : undefined, ...panelProps, ...assistantChat, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, children: conversationBalloon && currentOpen ? (
+                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt ?? suggestionPrompt, inspector: inspector, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, voice: voice, voiceSpeaking: speakerState.speaking, onStopSpeaking: speaker ? stopSpeaking : undefined, ...panelProps, ...assistantChat, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, onSendReady: handleSendReady, children: conversationBalloon && currentOpen ? (
                 // Current: the one thing said or done now, over the composer.
-                _jsx(Box, { sx: { px: 3, pt: 3, pb: 2, overflow: 'hidden' }, children: _jsx(CurrentBalloonBody, { text: toolSaid ? undefined : (currentWords ?? description), tool: toolSaid, busy: atWork, speaking: answering && atWork }) })) : (children) }))] }));
+                _jsx(Box, { sx: { px: 3, pt: 3, pb: 2, overflow: 'hidden' }, children: _jsx(CurrentBalloonBody, { text: toolSaid ? undefined : (currentWords ?? description), tool: toolSaid, busy: atWork, speaking: answering && atWork, waiting: atWork && !answering }) })) : (children) }))] }));
     /*
      * The floating popup's button. Words not yet heard make it blink for the
      * person's attention, until the chat is opened; hovered, they show in a
@@ -1050,7 +1106,19 @@ 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, suggestions: balloonSuggestions, onSuggestion: sendSuggestion, inspector: inspector, onBalloonDisplayChange: changeBalloonDisplay, onStop: chatBusy && chatControls.current
+                    ? () => chatControls.current?.stop()
+                    : undefined, onNewChat: !conversation && showNewChatButton ? handleNewChat : undefined, onClear: !conversation && useStoreMode ? handleClear : undefined, onChangeCharacter: onChangeCharacter, speech: speaker
+                    ? {
+                        muted: speechMuted,
+                        onToggle: () => {
+                            if (!speechMuted) {
+                                speaker.stop();
+                            }
+                            setSpeechMuted(!speechMuted);
+                        },
+                    }
+                    : undefined, onResetPosition: stageDrag.position ? stageDrag.reset : undefined, about: about, contextMenu: contextMenu })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
                     ...getPositionStyles(),
                 }, children: _jsxs(Box, { sx: {
                         position: 'relative',

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

@@ -0,0 +1,67 @@
+/**
+ * The assistant's own menu (LOOP T-27): right-click the character — or
+ * Shift+F10 or the ContextMenu key while it has the focus, or a long press on
+ * a touch screen — and a menu opens where the pointer is, with what applies
+ * to this agent on this page: inspect it, open the conversation, the
+ * balloon's display, the suggestions, stop the turn, a new conversation,
+ * another character, its voice, send it away, put it back, about it. Esc or
+ * a click outside closes it.
+ *
+ * Its entries are composed from what the host passes ({@link
+ * AssistantMenuItem}s): a host or a plugin adds its own (`contextMenu`; in
+ * the LOOP workspace, the `loop.assistant.menu` contribution point).
+ *
+ * @module chat/assistant/AssistantContextMenu
+ */
+import type { JSX, RefObject } from 'react';
+import type { Icon } from '@primer/octicons-react';
+/** One entry of the assistant's menu. */
+export type AssistantMenuItem = {
+    /** Stable id: `inspect`, `stop`, a plugin's own. */
+    id: string;
+    label: string;
+    /** Said under the label, smaller. */
+    description?: string;
+    /** An octicon, before the label. */
+    icon?: Icon;
+    onSelect: () => void;
+    /**
+     * Checkable: `true` or `false` makes it one of a choice — the entries of
+     * its group are a radio group, one checked.
+     */
+    checked?: boolean;
+    disabled?: boolean;
+    /** The group it is listed in, by its heading; ungrouped entries come first. */
+    group?: string;
+    /** Drawn as a danger: send away. */
+    danger?: boolean;
+};
+/** The entries by group, in the order their first entry came. */
+export declare function menuGroups(items: readonly AssistantMenuItem[]): {
+    group: string | undefined;
+    items: AssistantMenuItem[];
+}[];
+/** Whether a key opens the menu: Shift+F10, or the ContextMenu key. */
+export declare function opensContextMenu(event: {
+    key: string;
+    shiftKey: boolean;
+}): boolean;
+/** How long a touch is held before the menu opens, in ms. */
+export declare const LONG_PRESS_MS = 550;
+export type AssistantContextMenuProps = {
+    /** Where it opens, in the window's coordinates; closed when `null`. */
+    at: {
+        x: number;
+        y: number;
+    } | null;
+    items: readonly AssistantMenuItem[];
+    /** It closed: Esc, a click outside, or an entry chosen. */
+    onClose: () => void;
+    /** Where the focus goes back to once it closes. */
+    returnFocusRef?: RefObject<HTMLElement | null>;
+    /** Its name, for a screen reader: `Paper clip's menu`. */
+    label: string;
+};
+/** The menu, anchored at a point of the window. */
+export declare function AssistantContextMenu({ at, items, onClose, returnFocusRef, label, }: AssistantContextMenuProps): JSX.Element | null;
+export default AssistantContextMenu;

package/lib/chat/assistant/AssistantContextMenu.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { createPortal } from 'react-dom';
+import { ActionList, ActionMenu } from '@primer/react';
+/** The entries by group, in the order their first entry came. */
+export function menuGroups(items) {
+    const groups = [];
+    for (const item of items) {
+        const found = groups.find(group => group.group === item.group);
+        if (found) {
+            found.items.push(item);
+        }
+        else {
+            groups.push({ group: item.group, items: [item] });
+        }
+    }
+    // The ungrouped come first.
+    return [
+        ...groups.filter(group => group.group === undefined),
+        ...groups.filter(group => group.group !== undefined),
+    ];
+}
+/** Whether a key opens the menu: Shift+F10, or the ContextMenu key. */
+export function opensContextMenu(event) {
+    return event.key === 'ContextMenu' || (event.key === 'F10' && event.shiftKey);
+}
+/** How long a touch is held before the menu opens, in ms. */
+export const LONG_PRESS_MS = 550;
+/** The menu, anchored at a point of the window. */
+export function AssistantContextMenu({ at, items, onClose, returnFocusRef, label, }) {
+    const anchor = useRef(null);
+    const open = at !== null;
+    useEffect(() => {
+        if (!open) {
+            return;
+        }
+        // A scroll moves what it was opened on: it closes.
+        const close = () => onClose();
+        window.addEventListener('scroll', close, true);
+        return () => window.removeEventListener('scroll', close, true);
+    }, [open, onClose]);
+    if (!at || typeof document === 'undefined') {
+        return null;
+    }
+    const groups = menuGroups(items);
+    return (_jsxs(_Fragment, { children: [createPortal(_jsx("div", { ref: anchor, "aria-hidden": "true", "data-assistant-menu-anchor": "", style: {
+                    position: 'fixed',
+                    left: at.x,
+                    top: at.y,
+                    width: 1,
+                    height: 1,
+                    pointerEvents: 'none',
+                } }), document.body), _jsx(ActionMenu, { open: true, anchorRef: anchor, onOpenChange: next => {
+                    if (!next) {
+                        onClose();
+                        requestAnimationFrame(() => returnFocusRef?.current?.focus());
+                    }
+                }, children: _jsx(ActionMenu.Overlay, { width: "auto", "data-assistant-menu": "", children: _jsx(ActionList, { "aria-label": label, children: groups.map(({ group, items: entries }, index) => {
+                            const choice = entries.some(item => item.checked !== undefined);
+                            const list = entries.map(item => (_jsxs(ActionList.Item, { "data-assistant-menu-item": item.id, disabled: item.disabled, variant: item.danger ? 'danger' : 'default', ...(choice ? { selected: !!item.checked } : {}), onSelect: () => {
+                                    item.onSelect();
+                                    onClose();
+                                    requestAnimationFrame(() => returnFocusRef?.current?.focus());
+                                }, children: [item.icon && (_jsx(ActionList.LeadingVisual, { children: _jsx(item.icon, {}) })), item.label, item.description && (_jsx(ActionList.Description, { variant: "block", children: item.description }))] }, item.id)));
+                            return (_jsxs(ActionList.Group, { ...(choice ? { selectionVariant: 'single' } : {}), children: [group && (_jsx(ActionList.GroupHeading, { children: group })), list] }, group ?? `ungrouped-${index}`));
+                        }) }) }) })] }));
+}
+export default AssistantContextMenu;

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

@@ -8,6 +8,17 @@
  * working: it steps aside — out of sight and out of the pointer's way — until
  * the place is clear again.
  *
+ * Right-clicked — or Shift+F10 or the ContextMenu key while it has the
+ * focus, or a long press — it opens its own menu where the pointer is
+ * (`AssistantContextMenu`): what the host passes applies — *Inspect the
+ * agent…* (the Agent Inspector, in a dialog loaded then), the conversation,
+ * the balloon's display, the suggestions, *Stop*, a new conversation,
+ * another character, its voice, send it away, its place, about it — and
+ * what a host or a plugin adds (`contextMenu`).
+ *
+ * Given suggestions, its balloon offers them while it waits for a question
+ * (idle, or greeting): one clicked is sent as the prompt (`onSuggestion`).
+ *
  * Its motions are one set for every character, by the parts each drawing
  * names (`assistant-body`, `-pupils`, `-lids`, `-mouth`), and nothing moves
  * for a reader who asks the system for reduced motion.
@@ -16,10 +27,54 @@
  */
 import type { JSX, ReactNode, RefObject } from 'react';
 import { type AssistantCharacter } from './characters';
+import { type BalloonSuggestion } from './SpeechBalloon';
+import { type AssistantMenuItem } from './AssistantContextMenu';
+import type { AgentInspectorSink } from '../../components/inspector/agentInspector';
+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';
+/** What the assistant's *About* says. */
+export type AssistantAbout = {
+    /** The agent's name, or its application's. */
+    name?: string;
+    /** Its spec or application id, with its version. */
+    spec?: string;
+    /** Its model. */
+    model?: string;
+    /** Where it runs: `in your browser`, `on a runtime`. */
+    where?: string;
+};
+/**
+ * The entries of the assistant's menu, composed from what the host passes:
+ * each shows when what it does is there to do.
+ */
+export declare function assistantMenuItems(options: {
+    name: string;
+    open: boolean;
+    onToggle: () => void;
+    onDismiss: (away: AssistantAway) => void;
+    /** The conversation entry's label; `false` leaves it out. */
+    conversationLabel?: string | false;
+    inspect?: () => void;
+    balloonDisplay?: BalloonDisplay;
+    onBalloonDisplayChange?: (display: BalloonDisplay) => void;
+    suggestions?: readonly BalloonSuggestion[];
+    onSuggestion?: (suggestion: BalloonSuggestion) => void;
+    busy?: boolean;
+    onStop?: () => void;
+    onNewChat?: () => void;
+    onClear?: () => void;
+    onChangeCharacter?: () => void;
+    speech?: {
+        muted: boolean;
+        onToggle: () => void;
+    };
+    onResetPosition?: () => void;
+    about?: () => void;
+    extra?: readonly AssistantMenuItem[];
+}): AssistantMenuItem[];
 /**
  * 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
@@ -76,6 +131,8 @@ export interface AssistantStageProps {
      */
     balloon?: {
         text: string;
+        /** The words uncut, when `text` was cut to fit: *more* shows them. */
+        fullText?: string;
         more?: boolean;
         approval?: BalloonApproval;
         /** Puts the peek away (a × beside its line); never an approval's. */
@@ -88,15 +145,76 @@ 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. */
     insist?: boolean;
+    /**
+     * What the person may ask: chips in the balloon while it waits for a
+     * question (idle or greeting), and a group of its menu. One chosen is sent
+     * as the prompt with `onSuggestion`.
+     */
+    suggestions?: readonly BalloonSuggestion[];
+    onSuggestion?: (suggestion: BalloonSuggestion) => void;
+    /** The Agent Inspector's sink: its menu offers *Inspect the agent…*. */
+    inspector?: AgentInspectorSink | null;
+    /** The agent whose own record the inspector shows, of a shared sink (a team's member). */
+    inspectAgent?: string;
+    /**
+     * What its menu calls the conversation's entry, which does `onToggle`;
+     * `false` leaves it out, where there is no conversation to open (a team's
+     * member that is asked by another). Unsaid: *Open / Close the conversation*.
+     */
+    conversationLabel?: string | false;
+    /** The balloon's display changes from its menu: *Balloon: History / Current*. */
+    onBalloonDisplayChange?: (display: BalloonDisplay) => void;
+    /** Stops the turn: offered in its menu while it is at work. */
+    onStop?: () => void;
+    /** Starts a new conversation, from its menu. */
+    onNewChat?: () => void;
+    /** Clears the conversation, from its menu. */
+    onClear?: () => void;
+    /** Opens the host's character picker, from its menu. */
+    onChangeCharacter?: () => void;
+    /** Its voice, muted or not, from its menu. */
+    speech?: {
+        muted: boolean;
+        onToggle: () => void;
+    };
+    /** Puts it back where it started, after a drag: offered in its menu. */
+    onResetPosition?: () => void;
+    /** What its menu's *About* says. */
+    about?: AssistantAbout;
+    /** The host's or a plugin's own entries of its menu. */
+    contextMenu?: readonly AssistantMenuItem[];
     /** Send it away (T-27): for the page, for the session, or for good. */
     onDismiss: (away: AssistantAway) => void;
     /**
@@ -129,5 +247,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, suggestions, onSuggestion, inspector, inspectAgent, conversationLabel, onBalloonDisplayChange, onStop, onNewChat, onClear, onChangeCharacter, speech, onResetPosition, about, contextMenu, }: AssistantStageProps): JSX.Element;
 export default AssistantStage;