@datalayer/agent-runtimes 1.3.71 → 1.3.72

package/lib/components/teams/useA2ATeam.js

@@ -28,7 +28,8 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { stepCountIs, ToolLoopAgent } from 'ai';
 import { createBrowserModel, } from '../../runtimes/browser/model';
 import { a2aPeerTool, NOTEBOOK_MEDIA_TYPE, } from '../../runtimes/browser/a2aPeer';
-import { callsAfter, flowAfter, pruneCalls, } from './a2aTeamFlow';
+import { callsAfter, flowAfter, toolOwnName, pruneCalls, } from './a2aTeamFlow';
+import { toolLineOfStep, } from '../../chat/assistant/toolLine';
 const NO_CONNECTIONS = [];
 export const AT_REST = {
     state: 'idle',
@@ -116,6 +117,7 @@ export function useA2ATeam(options) {
                 state: 'greeting',
                 saying: 'On it. Let me read the books.',
                 insist: true,
+                tool: undefined,
             }));
         }
         else if (event.phase === 'working') {
@@ -126,7 +128,12 @@ export function useA2ATeam(options) {
                 ...prev,
                 state: 'working',
                 saying: event.note ? balloonLine(event.note) : prev.saying,
-                insist: Boolean(event.note) || prev.insist,
+                insist: Boolean(event.note) || Boolean(event.tool) || prev.insist,
+                // The tool it calls, in plain words, from the step it told; a
+                // step without a tool (its own words) puts the tool line away.
+                tool: event.tool
+                    ? toolLineOfStep(event.tool, toolOwnName(event.tool.name, peerConnections))
+                    : undefined,
             }));
         }
         else if (event.phase === 'answered') {
@@ -145,7 +152,12 @@ export function useA2ATeam(options) {
                 state: 'speaking',
                 saying: balloonLine(event.answer),
                 insist: true,
+                tool: undefined,
             }));
+            // The entry was given a notebook: in its balloon, read-only.
+            if (given) {
+                setEntryPersona(prev => ({ ...prev, notebook: given }));
+            }
         }
         else {
             setExchange(prev => [
@@ -157,6 +169,7 @@ export function useA2ATeam(options) {
                 state: 'idle',
                 saying: balloonLine(event.error),
                 insist: true,
+                tool: undefined,
             }));
         }
     }, [entry.name, peerApp.id, peerApp.name, peerConnections]);
@@ -210,6 +223,14 @@ export function useA2ATeam(options) {
                         state: 'waiting',
                         saying: balloonLine(`${peerApp.name}, could you: ${request}`),
                         insist: true,
+                        // Its one tool, in its own words: it asks its peer.
+                        tool: {
+                            id: part.toolCallId,
+                            tool: askTool,
+                            name: askTool,
+                            phase: 'running',
+                            words: `Asking ${peerApp.name}…`,
+                        },
                     }));
                 }
                 else if (part.type === 'tool-result' && part.toolName === askTool) {
@@ -217,6 +238,7 @@ export function useA2ATeam(options) {
                         ...prev,
                         state: 'thinking',
                         saying: 'Thanks!',
+                        tool: undefined,
                     }));
                     // Accounting has handed its answer over: back at rest, its last
                     // words still in its balloon.
@@ -229,6 +251,16 @@ export function useA2ATeam(options) {
                         state: 'speaking',
                         saying: balloonLine(said),
                         insist: true,
+                        tool: undefined,
+                    }));
+                }
+                else if (part.type === 'tool-error' && part.toolName === askTool) {
+                    setEntryPersona(prev => ({
+                        ...prev,
+                        state: 'thinking',
+                        tool: prev.tool
+                            ? { ...prev.tool, phase: 'failed', words: undefined }
+                            : undefined,
                     }));
                 }
                 else if (part.type === 'error') {
@@ -257,6 +289,7 @@ export function useA2ATeam(options) {
                 state: 'idle',
                 saying: balloonLine(`Something went wrong: ${message}`),
                 insist: true,
+                tool: undefined,
             }));
             setFlow('still');
             callsNow.current = [];
@@ -266,7 +299,9 @@ export function useA2ATeam(options) {
             abort.current = null;
             setBusy(false);
             // However the turn ended, neither member is still at work.
-            setPeerPersona(prev => prev.state === 'idle' ? prev : { ...prev, state: 'idle' });
+            setPeerPersona(prev => prev.state === 'idle' && !prev.tool
+                ? prev
+                : { ...prev, state: 'idle', tool: undefined });
         }
     }, [agent, busy, askTool, peerApp.name]);
     const stop = useCallback(() => abort.current?.abort(), []);

package/lib/examples/AgentA2ATeamExample.d.ts

@@ -14,14 +14,18 @@
  * — the edge flows back — each in its own state and balloon. Under
  * Accounting hangs Odoo, its connection (the odoo-accounting MCP server, from
  * its Appspec): the edge to it flows while Accounting calls one of its tools,
- * the tool's name on it. Then the report appears. The page's own state is `useA2ATeam`'s, which the landing's home
- * page runs too.
+ * the tool's name on it. Each balloon shows only what its member says or
+ * does now (`current`): "Asking Accounting…" for Sales' one tool, "Using
+ * list_invoices…" while Accounting calls Odoo. Then the report appears. The
+ * page's own state is `useA2ATeam`'s, which the landing's home page runs too.
  *
  * Sales accepts a Jupyter notebook from Accounting besides its words
  * (`acceptedOutputModes`, `NOTEBOOK_AND_WORDS`). When Accounting gives one,
- * it opens under the conversation in place of the report, on the browser
+ * Sales' balloon shows it read-only (`NotebookPreview`: no kernel), and it
+ * opens right under the team, in place of the report, on the browser
  * sandbox — a Pyodide kernel in this page — to run, change and download
- * (`TeamNotebook`, loaded only then).
+ * (`TeamNotebook`, loaded only then); a click on the one in the balloon
+ * comes to it.
  *
  * Where Accounting is: `VITE_A2A_ACCOUNTING_URL`, else the examples' local
  * server (`…:8765/api/v1/a2a/agents/accounting`), which answers this machine

package/lib/examples/AgentA2ATeamExample.js

@@ -112,7 +112,7 @@ function AgentA2ATeam() {
                         persona: team.peerPersona,
                         onAway: team.setPeerAway,
                         connections: ACCOUNTING_CONNECTIONS,
-                    }, flow: team.flow, calls: team.calls, connected: peer !== null, label: peer ? `A2A · ${peer.skill.name}` : 'A2A · not connected' }) }), _jsxs(Box, { sx: { display: 'flex', gap: 3, flexWrap: 'wrap' }, children: [_jsxs(Box, { sx: { flex: '1 1 420px', minWidth: 0 }, children: [_jsxs(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: ["Ask ", SALES.name] }), _jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap', mb: 2 }, children: (SALES.interface.starters ?? []).map(starter => (_jsx(Button, { size: "small", disabled: !team.ready || team.busy, onClick: () => send(starter.message), children: starter.label }, starter.label))) }), _jsx(Textarea, { ref: composer, block: true, rows: 3, value: draft, placeholder: "Ask for a financial report\u2026", onChange: event => setDraft(event.target.value), onKeyDown: event => {
+                    }, flow: team.flow, calls: team.calls, connected: peer !== null, label: peer ? `A2A · ${peer.skill.name}` : 'A2A · not connected' }) }), team.notebook && (_jsx(Box, { sx: { mb: 3 }, "data-team-notebook-placement": "under-graph", children: _jsx(TeamNotebook, { notebook: team.notebook, title: `${ACCOUNTING.name}\u2019s notebook` }) })), _jsxs(Box, { sx: { display: 'flex', gap: 3, flexWrap: 'wrap' }, children: [_jsxs(Box, { sx: { flex: '1 1 420px', minWidth: 0 }, children: [_jsxs(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: ["Ask ", SALES.name] }), _jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap', mb: 2 }, children: (SALES.interface.starters ?? []).map(starter => (_jsx(Button, { size: "small", disabled: !team.ready || team.busy, onClick: () => send(starter.message), children: starter.label }, starter.label))) }), _jsx(Textarea, { ref: composer, block: true, rows: 3, value: draft, placeholder: "Ask for a financial report\u2026", onChange: event => setDraft(event.target.value), onKeyDown: event => {
                                     if (event.key === 'Enter' && !event.shiftKey) {
                                         event.preventDefault();
                                         send(draft);
@@ -128,7 +128,7 @@ function AgentA2ATeam() {
                                             borderColor: 'border.default',
                                             borderRadius: 2,
                                             minHeight: 120,
-                                        }, "data-team-report": "", children: team.report ? (_jsx(Streamdown, { children: team.report })) : (_jsx(Text, { sx: { color: 'fg.muted' }, children: "The report Accounting returns appears here, as it returned it, or as a notebook to run when it gives one." })) })] }))] })] }), team.notebook && (_jsx(Box, { sx: { mt: 3 }, children: _jsx(TeamNotebook, { notebook: team.notebook, title: `${ACCOUNTING.name}\u2019s notebook` }) }))] }));
+                                        }, "data-team-report": "", children: team.report ? (_jsx(Streamdown, { children: team.report })) : (_jsx(Text, { sx: { color: 'fg.muted' }, children: "The report Accounting returns appears here, as it returned it, or as a notebook to run when it gives one." })) })] }))] })] })] }));
 }
 export function AgentA2ATeamExample() {
     return (_jsx(ThemedProvider, { children: _jsx(AgentA2ATeam, {}) }));

package/lib/examples/ChatAssistantExample.js

@@ -73,6 +73,8 @@ const ChatAssistantExample = () => {
         ? assistantCharacterNamed(reactor, character)
         : character;
     const [loadError, setLoadError] = useState();
+    // How the balloon shows the conversation (T-23): history, or current.
+    const [balloon, setBalloon] = useState('history');
     // Pixel, the test sprite, read once through the clippy.js reader.
     const [pixel, setPixel] = useState();
     useEffect(() => {
@@ -135,7 +137,7 @@ const ChatAssistantExample = () => {
                                     }, "aria-pressed": option.id === character, "data-assistant-character": option.id, children: option.name }, option.id))), pixel && (_jsxs(Button, { variant: character === pixel ? 'primary' : 'default', onClick: () => {
                                         setCharacter(pixel);
                                         setLoadError(undefined);
-                                    }, "aria-pressed": character === pixel, "data-assistant-character": "sprite", children: [pixel.name, " (sprite)"] }))] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "The clippy.js characters" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: ["Fetched when picked from the", ' ', _jsxs("code", { children: ["clippyjs@", CLIPPY_JS_VERSION] }), " package on jsDelivr and read as data by the same reader. They are not in this repository: clippy.js\u2019s licence covers its code only, and the characters are Microsoft\u2019s."] }), _jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: CLIPPY_JS_CHARACTERS.map(name => {
+                                    }, "aria-pressed": character === pixel, "data-assistant-character": "sprite", children: [pixel.name, " (sprite)"] }))] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "The balloon" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: [_jsx("strong", { children: "History" }), ": open, the whole conversation, counted in its header, the composer last. ", _jsx("strong", { children: "Current" }), ": only what it says or does now \u2014 the answer as it is written, or the tool it calls (\u201CUsing current_time\u2026\u201D) \u2014 in one compact balloon. Either way, a tool call is said in the balloon."] }), _jsx(Box, { sx: { display: 'flex', gap: 2 }, children: ['history', 'current'].map(option => (_jsx(Button, { variant: option === balloon ? 'primary' : 'default', "aria-pressed": option === balloon, "data-assistant-balloon-choice": option, onClick: () => setBalloon(option), children: option === 'history' ? 'History' : 'Current' }, option))) })] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "The clippy.js characters" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: ["Fetched when picked from the", ' ', _jsxs("code", { children: ["clippyjs@", CLIPPY_JS_VERSION] }), " package on jsDelivr and read as data by the same reader. They are not in this repository: clippy.js\u2019s licence covers its code only, and the characters are Microsoft\u2019s."] }), _jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: CLIPPY_JS_CHARACTERS.map(name => {
                                         const picked = clippyJs[name] !== undefined && character === clippyJs[name];
                                         return (_jsx(Button, { variant: picked ? 'primary' : 'default', onClick: () => void pickClippyJs(name), disabled: fetching !== undefined, "aria-pressed": picked, "data-assistant-character": `clippy-js-${name.toLowerCase()}`, children: fetching === name ? `${name}…` : name }, name));
                                     }) })] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "A character you bring" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: ["The characters of Microsoft Office \u2014 Clippy, Merlin, Links and the others \u2014 are Microsoft\u2019s. Load only a character file you have the right to use: a Microsoft Agent ", _jsx("code", { children: ".acs" }), " file, or a clippy.js character\u2019s ", _jsx("code", { children: "agent.js" }), " and map image. It is read in this page and sent nowhere."] }), _jsx("input", { type: "file", multiple: true, accept: ".acs,.js,.png,.gif,.webp,.jpg,.jpeg", "aria-label": "Character files", onChange: async (event) => {
@@ -152,7 +154,7 @@ const ChatAssistantExample = () => {
                                         }
                                     } }), loadError && (_jsx(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mt: 2 }, children: loadError })), typeof character !== 'string' &&
                                     character !== pixel &&
-                                    !isClippyJs && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: drawn, protocol: "vercel-ai", endpoint: `${SERVER}/api/v1/vercel-ai/assistant`, title: "Assistant", description: "Hello! Ask me anything about this page.", position: "bottom-right", useStore: false, 
+                                    !isClippyJs && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: drawn, balloonDisplay: balloon, protocol: "vercel-ai", endpoint: `${SERVER}/api/v1/vercel-ai/assistant`, title: "Assistant", description: "Hello! Ask me anything about this page.", position: "bottom-right", useStore: false, 
                     // Ask a decision beside the composer: Jev, through this server.
                     decisions: { serverUrl: SERVER } }, typeof character === 'string' ? character : character.sprite)] }) }));
 };

package/lib/examples/ChatAssistantGalleryExample.d.ts

@@ -4,7 +4,11 @@
  * contributes to `loop.assistant.character`, a test sprite read through
  * the clippy.js reader, and, when asked, the characters clippy.js publishes,
  * fetched from jsDelivr — in each state it acts, stepped aside, with its
- * balloon, in light and dark, moving or still.
+ * balloon, in light and dark, moving or still. The balloon shows the
+ * conversation either way (T-23): a peek of it (`history`), or only what is
+ * said or done now (`current`); a tool call is said in plain words ("Using
+ * list_invoices…", "Done: list_invoices", "list_invoices failed"), and a
+ * recorded notebook shows read-only in the current balloon.
  *
  * Static data, no agent: it opens without a server or an account.
  */

package/lib/examples/ChatAssistantGalleryExample.js

@@ -9,7 +9,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * contributes to `loop.assistant.character`, a test sprite read through
  * the clippy.js reader, and, when asked, the characters clippy.js publishes,
  * fetched from jsDelivr — in each state it acts, stepped aside, with its
- * balloon, in light and dark, moving or still.
+ * balloon, in light and dark, moving or still. The balloon shows the
+ * conversation either way (T-23): a peek of it (`history`), or only what is
+ * said or done now (`current`); a tool call is said in plain words ("Using
+ * list_invoices…", "Done: list_invoices", "list_invoices failed"), and a
+ * recorded notebook shows read-only in the current balloon.
  *
  * Static data, no agent: it opens without a server or an account.
  */
@@ -20,11 +24,11 @@ import { ThemedProvider } from './utils/themedProvider';
 import { useExampleThemeStore } from './utils/themeStore';
 import { AssistantStage } from '../chat/assistant/AssistantStage';
 import { useViewportDrag } from '../chat/useViewportDrag';
-import { AssistantGalleryGrid, GalleryObstacle, Still, useGalleryCharacters, } from './utils/AssistantGalleryGrid';
-import { GALLERY_POSES, GALLERY_POSE_LABELS, balloonForPose, sampleApproval, sampleSaying, stateOfPose, } from './utils/assistantGallery';
+import { AssistantGalleryGrid, GalleryBalloons, GalleryNotebook, GalleryObstacle, Still, useGalleryCharacters, } from './utils/AssistantGalleryGrid';
+import { GALLERY_POSES, GALLERY_POSE_LABELS, SAMPLE_NOTEBOOK_SAYING, balloonForPose, sampleApproval, sampleSaying, sampleToolLine, stateOfPose, } from './utils/assistantGallery';
 import { CLIPPY_JS_VERSION, useClippyJsCharacters, } from './utils/clippyJsCharacters';
 const STAGE_SIZE = 96;
-const PANEL_HEIGHT = 420;
+const PANEL_HEIGHT = 520;
 const LEAVE_MS = 700;
 const ARRIVE_MS = 1900;
 const AWAY_WORDS = {
@@ -34,7 +38,7 @@ const AWAY_WORDS = {
     always: 'for good',
 };
 /** One colour mode's panel, with the character on its own stage. */
-function ModePanel({ mode, character, pose, presence, balloon, insist, onToggle, onDismiss, onCallBack, away, replay, }) {
+function ModePanel({ mode, character, pose, presence, balloon, insist, onToggle, onDismiss, onCallBack, away, replay, display, }) {
     const panelRef = useRef(null);
     const stageRef = useRef(null);
     const drag = useViewportDrag(stageRef, { whole: true });
@@ -80,7 +84,7 @@ function ModePanel({ mode, character, pose, presence, balloon, insist, onToggle,
                     position: 'absolute',
                     left: spot.left,
                     top: spot.top + STAGE_SIZE / 2 - 16,
-                }, children: [_jsxs(Button, { size: "small", onClick: onCallBack, "data-gallery-call-back": "", children: ["Call ", character.name, " back"] }), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1 }, children: ["Sent away ", AWAY_WORDS[away], "."] })] })) : (_jsx(AssistantStage, { character: character.character, state: state, size: STAGE_SIZE, place: { position: 'absolute', left: spot.left, top: spot.top }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: false, onToggle: onToggle, balloon: presence === 'here' ? balloon : undefined, insist: insist, onDismiss: onDismiss }, `${character.id}-${replay}`)), pose === 'aside' && presence === 'here' && (_jsx(GalleryObstacle, { sx: {
+                }, children: [_jsxs(Button, { size: "small", onClick: onCallBack, "data-gallery-call-back": "", children: ["Call ", character.name, " back"] }), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1 }, children: ["Sent away ", AWAY_WORDS[away], "."] })] })) : (_jsx(AssistantStage, { character: character.character, state: state, size: STAGE_SIZE, place: { position: 'absolute', left: spot.left, top: spot.top }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: false, onToggle: onToggle, balloon: presence === 'here' ? balloon : undefined, balloonDisplay: display, insist: insist, onDismiss: onDismiss }, `${character.id}-${replay}`)), pose === 'aside' && presence === 'here' && (_jsx(GalleryObstacle, { sx: {
                     left: spot.left - 12,
                     top: spot.top - 12,
                     width: STAGE_SIZE + 24,
@@ -115,6 +119,10 @@ const ChatAssistantGalleryExample = () => {
     const [presence, setPresence] = useState('here');
     const [away, setAway] = useState('none');
     const [replay, setReplay] = useState(0);
+    // How the balloon shows the conversation, a tool being called, a notebook (T-23).
+    const [display, setDisplay] = useState('current');
+    const [toolPhase, setToolPhase] = useState();
+    const [withNotebook, setWithNotebook] = useState(false);
     const character = characters.find(entry => entry.id === characterId) ?? characters[0];
     // Leaving takes the goodbye's length; arriving, the greeting's.
     useEffect(() => {
@@ -138,10 +146,20 @@ const ChatAssistantGalleryExample = () => {
     };
     const approval = sampleApproval(() => setDecision('Approved: send_reply.'), () => setDecision('Denied: send_reply.'));
     const balloon = balloonForPose(pose, {
-        saying: saying === undefined ? undefined : sampleSaying(saying),
+        saying: saying === undefined
+            ? withNotebook
+                ? { text: SAMPLE_NOTEBOOK_SAYING, more: false }
+                : undefined
+            : sampleSaying(saying),
         approval,
+        tool: toolPhase ? sampleToolLine(toolPhase) : undefined,
+        attachment: withNotebook && display === 'current' ? (_jsx(GalleryNotebook, { onOpen: () => setDecision('The notebook would open below to run.') })) : undefined,
     });
-    const insist = saying !== undefined || pose === 'waiting' || pose === 'paused';
+    const insist = saying !== undefined ||
+        toolPhase !== undefined ||
+        withNotebook ||
+        pose === 'waiting' ||
+        pose === 'paused';
     return (_jsx(ThemedProvider, { children: _jsx(Box, { sx: {
                 minHeight: '100vh',
                 bg: 'canvas.default',
@@ -174,13 +192,25 @@ const ChatAssistantGalleryExample = () => {
                                             gap: 2,
                                             flexWrap: 'wrap',
                                             alignItems: 'center',
-                                        }, children: [_jsx(Button, { onClick: say, "data-gallery-say": "", children: "Say something" }), saying !== undefined && (_jsx(Button, { variant: "invisible", onClick: () => setSaying(undefined), children: "Hush" })), presence === 'away' ? (_jsx(Button, { onClick: callBack, children: "Call it back" })) : (_jsx(Button, { onClick: () => sendAway('page'), disabled: presence !== 'here', "data-gallery-send-away": "", children: "Send it away" })), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Drag the character to move it; hover it for its own send-away menu." }), decision && (_jsx(Text, { role: "status", sx: { fontSize: 1 }, children: decision }))] })] }))] }), problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["The test sprite could not be read: ", problem] })), clippyJs.problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["A clippy.js character could not be read: ", clippyJs.problem] })), _jsx(Still, { still: still, children: view === 'stage' ? (_jsx(InModes, { modes: modes, children: mode => (_jsx(ModePanel, { mode: mode, character: character, pose: pose, presence: presence, balloon: balloon, insist: insist, onToggle: () => saying === undefined ? say() : setSaying(undefined), onDismiss: sendAway, onCallBack: callBack, away: away, replay: replay })) })) : (_jsx(InModes, { modes: modes, stacked: true, children: mode => (_jsx(Box, { "data-gallery-mode": mode, sx: {
+                                        }, children: [_jsx(SegmentedControl, { "aria-label": "Balloon", children: ['history', 'current'].map(option => (_jsx(SegmentedControl.Button, { selected: display === option, onClick: () => setDisplay(option), "data-gallery-balloon": option, children: option === 'history' ? 'History' : 'Current' }, option))) }), _jsx(Button, { onClick: say, "data-gallery-say": "", children: "Say something" }), _jsx(Button, { "data-gallery-tool": toolPhase ?? 'none', onClick: () => setToolPhase(toolPhase === undefined
+                                                    ? 'running'
+                                                    : toolPhase === 'running'
+                                                        ? 'done'
+                                                        : toolPhase === 'done'
+                                                            ? 'failed'
+                                                            : undefined), children: toolPhase === undefined
+                                                    ? 'Use a tool'
+                                                    : toolPhase === 'running'
+                                                        ? 'Tool done'
+                                                        : toolPhase === 'done'
+                                                            ? 'Tool failed'
+                                                            : 'No tool' }), _jsx(Button, { "data-gallery-notebook": withNotebook ? 'on' : 'off', "aria-pressed": withNotebook, onClick: () => setWithNotebook(!withNotebook), children: withNotebook ? 'Take the notebook' : 'Give a notebook' }), saying !== undefined && (_jsx(Button, { variant: "invisible", onClick: () => setSaying(undefined), children: "Hush" })), presence === 'away' ? (_jsx(Button, { onClick: callBack, children: "Call it back" })) : (_jsx(Button, { onClick: () => sendAway('page'), disabled: presence !== 'here', "data-gallery-send-away": "", children: "Send it away" })), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Drag the character to move it; hover it for its own send-away menu." }), decision && (_jsx(Text, { role: "status", sx: { fontSize: 1 }, children: decision }))] })] }))] }), problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["The test sprite could not be read: ", problem] })), clippyJs.problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["A clippy.js character could not be read: ", clippyJs.problem] })), _jsx(Still, { still: still, children: view === 'stage' ? (_jsx(InModes, { modes: modes, children: mode => (_jsx(ModePanel, { mode: mode, character: character, pose: pose, presence: presence, balloon: balloon, insist: insist, onToggle: () => saying === undefined ? say() : setSaying(undefined), onDismiss: sendAway, onCallBack: callBack, away: away, replay: replay, display: display })) })) : (_jsx(InModes, { modes: modes, stacked: true, children: mode => (_jsxs(Box, { "data-gallery-mode": mode, sx: {
                                     bg: 'canvas.default',
                                     border: '1px solid',
                                     borderColor: 'border.default',
                                     borderRadius: 2,
                                     p: 2,
                                     overflowX: 'auto',
-                                }, children: _jsx(AssistantGalleryGrid, { characters: characters }, replay) })) })) })] }) }) }));
+                                }, children: [_jsx(AssistantGalleryGrid, { characters: characters }, replay), _jsx(GalleryBalloons, { character: character })] })) })) })] }) }) }));
 };
 export default ChatAssistantGalleryExample;

package/lib/examples/utils/AssistantGalleryGrid.d.ts

@@ -1,14 +1,3 @@
-/**
- * The floating assistant's characters, every one in every pose, small, for
- * a quick visual check (LOOP T-16, T-22, T-24 to T-27): Datalayer's four and
- * the owl as the enabled plugins contribute them to
- * `loop.assistant.character`, and a test sprite read through the clippy.js
- * reader. Each cell is the real `AssistantStage`, set in the grid's flow
- * rather than fixed to the window; stepped aside is the real `useKeepClear`
- * stepping it aside from a composer laid over the cell.
- *
- * @module examples/utils/AssistantGalleryGrid
- */
 import type { JSX, ReactNode } from 'react';
 import type { AssistantCharacter } from '../../chat/assistant/characters';
 import type { AssistantCharacterData } from '../../chat/assistant/formats/types';
@@ -50,4 +39,18 @@ export declare function AssistantGalleryGrid({ characters, size, }: {
     characters: readonly GalleryCharacter[];
     size?: number;
 }): JSX.Element;
+/** How tall the notebook in a balloon is, in the stage and in the grid. */
+export declare const GALLERY_NOTEBOOK_HEIGHT = 160;
+/** The notebook a balloon holds in the gallery: jupyter-react's, read-only. */
+export declare function GalleryNotebook({ onOpen, }: {
+    onOpen?: () => void;
+}): JSX.Element;
+/**
+ * The balloon's displays (T-23), one character: a peek of the history, the
+ * current balloon with a tool line, and with a notebook given — the same
+ * read-only jupyter-react notebook as in the stage, loaded when drawn.
+ */
+export declare function GalleryBalloons({ character, }: {
+    character: GalleryCharacter;
+}): JSX.Element;
 export default AssistantGalleryGrid;

package/lib/examples/utils/AssistantGalleryGrid.js

@@ -6,8 +6,9 @@ import { buildReactorFromPlugins } from '@datalayer/reactor';
 import { AssistantStage } from '../../chat/assistant/AssistantStage';
 import { AssistantCharactersPlugin, assistantCharactersOf, } from '../../loop/plugins/assistant-characters';
 import { OWL_CHARACTER, OwlCharacterPlugin } from './owlCharacterPlugin';
+import { NotebookPreview } from '../../components/teams/NotebookPreview';
 import { readTestSpriteCharacter } from './testSpriteCharacter';
-import { GALLERY_POSES, GALLERY_POSE_LABELS, stateOfPose, } from './assistantGallery';
+import { GALLERY_POSES, GALLERY_POSE_LABELS, SAMPLE_NOTEBOOK, SAMPLE_NOTEBOOK_SAYING, sampleSaying, sampleToolLine, stateOfPose, } from './assistantGallery';
 /** The plugins the gallery enables: Datalayer's characters and the owl's. */
 const reactor = buildReactorFromPlugins([
     AssistantCharactersPlugin,
@@ -120,4 +121,44 @@ export function AssistantGalleryGrid({ characters, size = 48, }) {
             '& td': { p: 0, textAlign: 'center' },
         }, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", {}), GALLERY_POSES.map(pose => (_jsx("th", { scope: "col", children: GALLERY_POSE_LABELS[pose] }, pose)))] }) }), _jsx("tbody", { children: characters.map(character => (_jsxs("tr", { children: [_jsxs(Box, { as: "th", scope: "row", sx: { textAlign: 'left !important', pr: '12px !important' }, children: [_jsx(Text, { sx: { display: 'block', color: 'fg.default' }, children: character.name }), _jsx(Text, { sx: { fontWeight: 400 }, children: character.from })] }), GALLERY_POSES.map(pose => (_jsx("td", { children: _jsx(GalleryCell, { character: character, pose: pose, size: size }) }, pose)))] }, character.id))) })] }));
 }
+/** How tall the notebook in a balloon is, in the stage and in the grid. */
+export const GALLERY_NOTEBOOK_HEIGHT = 160;
+/** The notebook a balloon holds in the gallery: jupyter-react's, read-only. */
+export function GalleryNotebook({ onOpen, }) {
+    return (_jsx(NotebookPreview, { notebook: SAMPLE_NOTEBOOK, title: "Accounting\u2019s notebook", maxHeight: GALLERY_NOTEBOOK_HEIGHT, onOpen: onOpen }));
+}
+/** One balloon display, pictured: a character with what its balloon says. */
+function BalloonCell({ character, label, display, balloon, height, }) {
+    const stageRef = useRef(null);
+    return (_jsxs(Box, { "data-gallery-cell": `balloon-${label.toLowerCase().replace(/\W+/g, '-')}`, sx: {
+            position: 'relative',
+            width: 330,
+            height,
+            border: '1px solid',
+            borderColor: 'border.muted',
+            borderRadius: 2,
+        }, children: [_jsx(Text, { sx: {
+                    position: 'absolute',
+                    top: 1,
+                    right: 2,
+                    fontSize: 0,
+                    fontWeight: 600,
+                    color: 'fg.muted',
+                }, children: label }), _jsx(AssistantStage, { character: character.character, state: balloon.tool ? 'working' : 'speaking', size: 48, place: { position: 'absolute', left: '12px', bottom: '8px' }, stageRef: stageRef, onDragStart: () => undefined, open: false, onToggle: () => undefined, onDismiss: () => undefined, balloon: balloon, balloonDisplay: display, insist: true })] }));
+}
+/**
+ * The balloon's displays (T-23), one character: a peek of the history, the
+ * current balloon with a tool line, and with a notebook given — the same
+ * read-only jupyter-react notebook as in the stage, loaded when drawn.
+ */
+export function GalleryBalloons({ character, }) {
+    return (_jsxs(Box, { "data-gallery-balloons": "", sx: { display: 'flex', gap: 3, flexWrap: 'wrap', mt: 3 }, children: [_jsx(BalloonCell, { character: character, label: "History", display: "history", height: 180, balloon: { ...sampleSaying(0), onDismiss: () => undefined } }), _jsx(BalloonCell, { character: character, label: "Current \u00B7 tool", display: "current", height: 180, balloon: {
+                    text: 'Using list_invoices…',
+                    tool: sampleToolLine('running'),
+                    busy: true,
+                } }), _jsx(BalloonCell, { character: character, label: "Current \u00B7 notebook", display: "current", height: GALLERY_NOTEBOOK_HEIGHT + 210, balloon: {
+                    text: SAMPLE_NOTEBOOK_SAYING,
+                    attachment: _jsx(GalleryNotebook, {}),
+                } })] }));
+}
 export default AssistantGalleryGrid;

package/lib/examples/utils/assistantGallery.d.ts

@@ -7,6 +7,7 @@
  * @module examples/utils/assistantGallery
  */
 import type { AssistantStageProps } from '../../chat/assistant/AssistantStage';
+import { type BalloonToolLine, type ToolLinePhase } from '../../chat/assistant/toolLine';
 import { type AssistantState, type BalloonApproval } from '../../chat/assistant/state';
 /** What the gallery poses a character in: a state, or stepped aside. */
 export type GalleryPose = AssistantState | 'aside';
@@ -27,16 +28,63 @@ export declare function sampleSaying(index: number): {
     text: string;
     more: boolean;
 };
+/** The tool the gallery calls (T-23): Odoo's, as Accounting calls it. */
+export declare const SAMPLE_TOOL = "list_invoices";
+/** The sample tool's line, at a phase: "Using list_invoices…", "Done: …", "… failed". */
+export declare function sampleToolLine(phase: ToolLinePhase): BalloonToolLine;
+/**
+ * A small recorded notebook (nbformat 4), as Accounting gives one: a
+ * heading, the code that totals the open invoices, and its one output.
+ */
+export declare const SAMPLE_NOTEBOOK: {
+    nbformat: number;
+    nbformat_minor: number;
+    metadata: {
+        kernelspec: {
+            name: string;
+            display_name: string;
+            language: string;
+        };
+        language_info: {
+            name: string;
+        };
+    };
+    cells: ({
+        id: string;
+        cell_type: string;
+        metadata: {};
+        source: string;
+        execution_count?: undefined;
+        outputs?: undefined;
+    } | {
+        id: string;
+        cell_type: string;
+        metadata: {};
+        execution_count: number;
+        source: string;
+        outputs: {
+            output_type: string;
+            name: string;
+            text: string;
+        }[];
+    })[];
+};
+/** What the gallery says with the notebook it was given. */
+export declare const SAMPLE_NOTEBOOK_SAYING = "Here is the notebook Accounting gave: the open invoices.";
 /** The approval the gallery waits on (T-23): answered in the balloon. */
 export declare function sampleApproval(onApprove: () => void, onDeny: () => void): BalloonApproval;
 /**
  * The balloon for a pose: waiting holds the approval, paused says so, and
  * any other pose says the sample's words when asked to (`saying`).
  */
-export declare function balloonForPose(pose: GalleryPose, { saying, approval, }: {
+export declare function balloonForPose(pose: GalleryPose, { saying, approval, tool, attachment, }: {
     saying?: {
         text: string;
         more: boolean;
     };
     approval: BalloonApproval;
+    /** A tool being called: its line stands in for the words. */
+    tool?: BalloonToolLine;
+    /** What goes with the words in a `current` balloon: a notebook. */
+    attachment?: NonNullable<AssistantStageProps['balloon']>['attachment'];
 }): AssistantStageProps['balloon'];

package/lib/examples/utils/assistantGallery.js

@@ -2,6 +2,7 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+import { toolLineText, } from '../../chat/assistant/toolLine';
 import { ASSISTANT_WORDS, latestSaying, } from '../../chat/assistant/state';
 /** Every state, in the order an assistant lives them, then stepped aside. */
 export const GALLERY_POSES = [
@@ -73,6 +74,46 @@ export function sampleSaying(index) {
     }
     return { text: saying.text, more: saying.more };
 }
+/** The tool the gallery calls (T-23): Odoo's, as Accounting calls it. */
+export const SAMPLE_TOOL = 'list_invoices';
+/** The sample tool's line, at a phase: "Using list_invoices…", "Done: …", "… failed". */
+export function sampleToolLine(phase) {
+    return { id: 'gallery-tool', tool: SAMPLE_TOOL, name: SAMPLE_TOOL, phase };
+}
+/**
+ * A small recorded notebook (nbformat 4), as Accounting gives one: a
+ * heading, the code that totals the open invoices, and its one output.
+ */
+export const SAMPLE_NOTEBOOK = {
+    nbformat: 4,
+    nbformat_minor: 5,
+    metadata: {
+        kernelspec: {
+            name: 'python3',
+            display_name: 'Python 3',
+            language: 'python',
+        },
+        language_info: { name: 'python' },
+    },
+    cells: [
+        {
+            id: 'gallery-markdown',
+            cell_type: 'markdown',
+            metadata: {},
+            source: '## Open invoices\n\nFrom the books, **in EUR**.',
+        },
+        {
+            id: 'gallery-code',
+            cell_type: 'code',
+            metadata: {},
+            execution_count: 1,
+            source: 'due = {"Ada": 1200, "Grace": 860}\nprint(sum(due.values()))',
+            outputs: [{ output_type: 'stream', name: 'stdout', text: '2060\n' }],
+        },
+    ],
+};
+/** What the gallery says with the notebook it was given. */
+export const SAMPLE_NOTEBOOK_SAYING = 'Here is the notebook Accounting gave: the open invoices.';
 /** The approval the gallery waits on (T-23): answered in the balloon. */
 export function sampleApproval(onApprove, onDeny) {
     return {
@@ -88,7 +129,7 @@ export function sampleApproval(onApprove, onDeny) {
  * The balloon for a pose: waiting holds the approval, paused says so, and
  * any other pose says the sample's words when asked to (`saying`).
  */
-export function balloonForPose(pose, { saying, approval, }) {
+export function balloonForPose(pose, { saying, approval, tool, attachment, }) {
     if (pose === 'waiting') {
         return { text: ASSISTANT_WORDS.approval, approval };
     }
@@ -98,5 +139,15 @@ export function balloonForPose(pose, { saying, approval, }) {
     if (pose === 'goodbye' || pose === 'aside') {
         return undefined;
     }
+    if (tool) {
+        return {
+            text: toolLineText(tool),
+            tool,
+            busy: tool.phase === 'running',
+        };
+    }
+    if (saying && attachment) {
+        return { ...saying, attachment };
+    }
     return saying;
 }

package/lib/loop/apps/appspec.js

@@ -255,6 +255,9 @@ function parseInterface(data, kind) {
     if (isAssistantCharacterId(data.assistant)) {
         parsed.assistant = data.assistant;
     }
+    if (data.balloon === 'history' || data.balloon === 'current') {
+        parsed.balloon = data.balloon;
+    }
     return parsed;
 }
 function parseCriterion(data) {
@@ -516,6 +519,9 @@ function dumpInterface(spec, kind) {
     if (spec.assistant) {
         writer.data.assistant = spec.assistant;
     }
+    if (spec.balloon) {
+        writer.data.balloon = spec.balloon;
+    }
     // Its voice, when it says one (VO-41): a spec made before voice has none.
     if (spec.voice) {
         writer.part('voice', new Writer()

package/lib/loop/apps/checks.js

@@ -398,6 +398,7 @@ const ENUMS = {
     ],
     visibility: ['private', 'invited', 'organization', 'link', 'public'],
     mode: ['inline', 'bubble', 'panel', 'assistant'],
+    balloon: ['history', 'current'],
     trigger: ['schedule', 'event', 'once'],
     criterion: ['metric', 'noul', 'choice', 'score'],
     direction: ['higher', 'lower'],
@@ -525,6 +526,7 @@ export function documentShapeProblems(document) {
     mapping(d.interface, 'interface', ui => {
         oneOf(ui.layout, ENUMS.layout, 'interface.layout');
         oneOf(ui.accent, ENUMS.accent, 'interface.accent');
+        oneOf(ui.balloon, ENUMS.balloon, 'interface.balloon');
         if (ui.assistant !== undefined && !isAssistantCharacterId(ui.assistant)) {
             at('interface.assistant', 'names a character by the id a plugin contributes it under, lowercase words joined by a hyphen: `paperclip`, `acme-owl`');
         }

package/lib/loop/embed/AppEmbed.js

@@ -80,7 +80,9 @@ function FloatingApp({ app, view, colorMode, themeOverrides, character, serverUr
     // Datalayer knows — said, and nothing launched, for one it does not.
     const token = useIAMStore(state => state.token);
     const signedOut = !serverUrl && !token;
-    return (_jsx(ChatFloating, { defaultViewMode: view, ...(character ? { assistantCharacter: character } : {}), title: app.name, description: welcome, brandIcon: _jsx(Face, { emoji: app.emoji }), buttonIcon: _jsx(Face, { emoji: app.emoji }), buttonTooltip: `Talk to ${app.name}`, colorMode: colorMode, useStore: false, conversation: {
+    return (_jsx(ChatFloating, { defaultViewMode: view, ...(character ? { assistantCharacter: character } : {}), ...(app.interface.balloon
+            ? { balloonDisplay: app.interface.balloon }
+            : {}), title: app.name, description: welcome, brandIcon: _jsx(Face, { emoji: app.emoji }), buttonIcon: _jsx(Face, { emoji: app.emoji }), buttonTooltip: `Talk to ${app.name}`, colorMode: colorMode, useStore: false, conversation: {
             body: signedOut ? (_jsx(Text, { as: "p", role: "status", sx: { p: 3, m: 0, fontSize: 1 }, children: signedOutSentence(app) })) : (_jsx(AppRenderer, { app: app, target: serverUrl ? 'local' : 'datalayer', ...(serverUrl ? { serverUrl } : {}), instance: instance, 
                 // The host's accent and face over the application's own, inside
                 // its conversation too, in the embed's mode.