@datalayer/agent-runtimes 1.3.74 → 1.3.75

package/lib/components/teams/useA2ATeam.js

@@ -11,8 +11,8 @@
  * with whatever `inference` holds — a signed-in person's token, or a
  * visitor's trial key. Its one tool asks the peer (Accounting) with
  * {@link a2aPeerTool}. What each of them does is kept as a persona — the
- * state its character acts and what its balloon says — and the exchange
- * between them as a log, the peer's last answer as the report, and the way
+ * state its character acts and what its balloon says — the peer's last
+ * answer as the report, and the way
  * the link carries a message as the flow ({@link flowAfter}). What the peer
  * gives besides words — the formats the page accepts (`accept`), such as a
  * Jupyter notebook — is kept as its artifacts, and its latest notebook kept
@@ -20,6 +20,11 @@
  * peer calls on its connections (its MCP servers), told over A2A as it calls
  * them, are kept as the calls running now ({@link callsAfter}).
  *
+ * Given an Agent Inspector's sink (`inspector`), the entry's turns (its
+ * model, its tokens), its call to the peer, and what the peer's events were
+ * made of are recorded there; the A2A traffic itself is recorded by the
+ * peer's fetch (`connectA2APeer`'s `inspect`).
+ *
  * What `A2ATeamGraph` draws, and what a page's composer sends.
  *
  * @module components/teams/useA2ATeam
@@ -41,7 +46,7 @@ export const NOTEBOOK_AND_WORDS = [
     NOTEBOOK_MEDIA_TYPE,
     'text/markdown',
 ];
-/** What an exchange line calls what the peer gave: its words, and each of its artifacts. */
+/** What the peer gave, in words: its words, and each of its artifacts. */
 export function answeredLine(artifacts) {
     const besides = artifacts.map(artifact => artifact.mediaType === NOTEBOOK_MEDIA_TYPE
         ? `a notebook, ${artifact.name}`
@@ -61,7 +66,7 @@ export function balloonLine(text, length = 120) {
 }
 /** Run a team of two over A2A in the page. */
 export function useA2ATeam(options) {
-    const { entry, peerApp, peer, inference, maxSteps = 6, peerConnections = NO_CONNECTIONS, } = options;
+    const { entry, peerApp, peer, inference, maxSteps = 6, peerConnections = NO_CONNECTIONS, inspector = null, } = options;
     // By what it names, so that a page passing a new array of the same media
     // types does not make the agent again.
     const acceptKey = options.accept?.join('\n');
@@ -71,24 +76,34 @@ export function useA2ATeam(options) {
         ...AT_REST,
         state: 'greeting',
         saying: balloonLine(entry.interface.welcome ?? ''),
+        full: entry.interface.welcome ?? '',
         insist: Boolean(entry.interface.welcome),
     }));
     const [peerPersona, setPeerPersona] = useState(AT_REST);
     const [turns, setTurns] = useState([]);
+    const [peerHistory, setPeerHistory] = useState([]);
+    const told = useRef(0);
+    const tell = useCallback((role, text) => {
+        told.current += 1;
+        const id = `peer-${told.current}`;
+        setPeerHistory(prev => [...prev, { id, role, text }]);
+    }, []);
     const [report, setReport] = useState(null);
     const [artifacts, setArtifacts] = useState([]);
     const [notebook, setNotebook] = useState(null);
-    const [exchange, setExchange] = useState([]);
     const [flow, setFlow] = useState('still');
     const [calls, setCalls] = useState([]);
     const callsNow = useRef([]);
     const callTimer = useRef(undefined);
     const [busy, setBusy] = useState(false);
     const history = useRef([]);
+    const turnCount = useRef(0);
     const abort = useRef(null);
     const flowTimer = useRef(undefined);
     // What the peer does, as it does it: its own state and balloon, and the link.
     const onPeerEvent = useCallback((event) => {
+        // Linked to the A2A entry it came from (the capture's linker).
+        inspector?.note(event);
         const next = flowAfter(event);
         clearTimeout(flowTimer.current);
         setFlow(next.flow);
@@ -108,26 +123,27 @@ export function useA2ATeam(options) {
             }, after.holdMs);
         }
         if (event.phase === 'asked') {
-            setExchange(prev => [
-                ...prev,
-                `${entry.name} → ${peerApp.name}: ${event.request}`,
-            ]);
+            tell('user', event.request);
             setPeerPersona(prev => ({
                 ...prev,
                 state: 'greeting',
                 saying: 'On it. Let me read the books.',
+                full: undefined,
                 insist: true,
                 tool: undefined,
             }));
         }
         else if (event.phase === 'working') {
-            if (event.note) {
-                setExchange(prev => [...prev, `${peerApp.name}: ${event.note}`]);
+            if (event.tool?.ended) {
+                tell('assistant', event.tool.error
+                    ? `${event.tool.name} failed: ${event.tool.error}`
+                    : `Used ${toolOwnName(event.tool.name, peerConnections)}`);
             }
             setPeerPersona(prev => ({
                 ...prev,
                 state: 'working',
                 saying: event.note ? balloonLine(event.note) : prev.saying,
+                full: event.note ?? prev.full,
                 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.
@@ -137,10 +153,7 @@ export function useA2ATeam(options) {
             }));
         }
         else if (event.phase === 'answered') {
-            setExchange(prev => [
-                ...prev,
-                `${peerApp.name} → ${entry.name}: ${answeredLine(event.artifacts)}`,
-            ]);
+            tell('assistant', event.answer);
             setReport(event.answer);
             setArtifacts(event.artifacts);
             const given = notebookAmong(event.artifacts);
@@ -151,6 +164,7 @@ export function useA2ATeam(options) {
                 ...prev,
                 state: 'speaking',
                 saying: balloonLine(event.answer),
+                full: event.answer,
                 insist: true,
                 tool: undefined,
             }));
@@ -160,19 +174,17 @@ export function useA2ATeam(options) {
             }
         }
         else {
-            setExchange(prev => [
-                ...prev,
-                `${peerApp.name} could not answer: ${event.error}`,
-            ]);
+            tell('assistant', `Could not answer: ${event.error}`);
             setPeerPersona(prev => ({
                 ...prev,
                 state: 'idle',
                 saying: balloonLine(event.error),
+                full: event.error,
                 insist: true,
                 tool: undefined,
             }));
         }
-    }, [entry.name, peerApp.id, peerApp.name, peerConnections]);
+    }, [peerApp.id, peerConnections, inspector, tell]);
     const agent = useMemo(() => {
         if (!peer) {
             return null;
@@ -198,7 +210,6 @@ export function useA2ATeam(options) {
         setBusy(true);
         setReport(null);
         setArtifacts([]);
-        setExchange([]);
         setTurns(prev => [...prev, { role: 'user', text: asked }]);
         setEntryPersona({
             ...AT_REST,
@@ -210,6 +221,19 @@ export function useA2ATeam(options) {
         history.current = [...history.current, { role: 'user', content: asked }];
         abort.current = new AbortController();
         let said = '';
+        // The turn, in the inspector: the entry's model, from the question to
+        // the answer, and its tokens.
+        turnCount.current += 1;
+        const turnKey = `turn:${entry.id}:${turnCount.current}`;
+        inspector?.start({
+            key: turnKey,
+            actor: entry.name,
+            source: 'model',
+            kind: 'turn',
+            name: entry.model || undefined,
+            summary: balloonLine(asked, 160),
+            payload: { prompt: asked, model: entry.model || undefined },
+        });
         try {
             const result = await agent.stream({
                 messages: history.current,
@@ -218,10 +242,21 @@ export function useA2ATeam(options) {
             for await (const part of result.fullStream) {
                 if (part.type === 'tool-call' && part.toolName === askTool) {
                     const request = String(part.input?.request ?? '');
+                    // Its tool runs here, in the page, and asks the peer over A2A.
+                    inspector?.start({
+                        key: `tool:${part.toolCallId}`,
+                        actor: entry.name,
+                        source: 'frontend-tool',
+                        kind: 'tool-call',
+                        name: askTool,
+                        summary: balloonLine(request, 160),
+                        payload: part.input,
+                    });
                     setEntryPersona(prev => ({
                         ...prev,
                         state: 'waiting',
                         saying: balloonLine(`${peerApp.name}, could you: ${request}`),
+                        full: `${peerApp.name}, could you: ${request}`,
                         insist: true,
                         // Its one tool, in its own words: it asks its peer.
                         tool: {
@@ -234,10 +269,16 @@ export function useA2ATeam(options) {
                     }));
                 }
                 else if (part.type === 'tool-result' && part.toolName === askTool) {
+                    const output = part.output;
+                    inspector?.end(`tool:${part.toolCallId}`, {
+                        result: part.output,
+                        ...(output?.error ? { error: String(output.error) } : {}),
+                    });
                     setEntryPersona(prev => ({
                         ...prev,
                         state: 'thinking',
                         saying: 'Thanks!',
+                        full: undefined,
                         tool: undefined,
                     }));
                     // Accounting has handed its answer over: back at rest, its last
@@ -250,11 +291,18 @@ export function useA2ATeam(options) {
                         ...prev,
                         state: 'speaking',
                         saying: balloonLine(said),
+                        full: said,
                         insist: true,
                         tool: undefined,
                     }));
                 }
                 else if (part.type === 'tool-error' && part.toolName === askTool) {
+                    inspector?.end(`tool:${part.toolCallId}`, {
+                        status: 'failed',
+                        error: part.error instanceof Error
+                            ? part.error.message
+                            : String(part.error),
+                    });
                     setEntryPersona(prev => ({
                         ...prev,
                         state: 'thinking',
@@ -271,15 +319,24 @@ export function useA2ATeam(options) {
                 ...history.current,
                 { role: 'assistant', content: said },
             ];
+            if (inspector) {
+                const usage = await Promise.resolve(result.totalUsage).catch(() => undefined);
+                inspector.end(turnKey, {
+                    result: { text: said, ...(usage ? { usage } : {}) },
+                    summary: `${balloonLine(asked, 60)} → ${balloonLine(said, 80)}${usage?.totalTokens ? ` · ${usage.totalTokens} tokens` : ''}`,
+                });
+            }
             setTurns(prev => [...prev, { role: 'assistant', text: said }]);
             setEntryPersona(prev => ({
                 ...prev,
                 state: 'idle',
                 saying: balloonLine(said),
+                full: said,
             }));
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            inspector?.end(turnKey, { status: 'failed', error: message });
             setTurns(prev => [
                 ...prev,
                 { role: 'assistant', text: `Something went wrong: ${message}` },
@@ -288,6 +345,7 @@ export function useA2ATeam(options) {
                 ...prev,
                 state: 'idle',
                 saying: balloonLine(`Something went wrong: ${message}`),
+                full: `Something went wrong: ${message}`,
                 insist: true,
                 tool: undefined,
             }));
@@ -303,7 +361,7 @@ export function useA2ATeam(options) {
                 ? prev
                 : { ...prev, state: 'idle', tool: undefined });
         }
-    }, [agent, busy, askTool, peerApp.name]);
+    }, [agent, busy, askTool, peerApp.name, entry, inspector]);
     const stop = useCallback(() => abort.current?.abort(), []);
     useEffect(() => () => {
         abort.current?.abort();
@@ -312,13 +370,19 @@ export function useA2ATeam(options) {
     }, []);
     const setEntryAway = useCallback((away) => setEntryPersona(prev => ({ ...prev, away })), []);
     const setPeerAway = useCallback((away) => setPeerPersona(prev => ({ ...prev, away })), []);
+    const entryHistory = useMemo(() => turns.map((turn, index) => ({
+        id: `turn-${index}`,
+        role: turn.role,
+        text: turn.text,
+    })), [turns]);
     return {
+        entryHistory,
+        peerHistory,
         entryPersona,
         peerPersona,
         setEntryAway,
         setPeerAway,
         turns,
-        exchange,
         report,
         artifacts,
         notebook,

package/lib/examples/AgentA2ATeamExample.d.ts

@@ -19,6 +19,19 @@
  * 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.
  *
+ * Under the graph, each member has its own Agent Inspector: Sales' — its
+ * model turns, its `ask_accounting` call, the A2A messages it sends and
+ * receives — and Accounting's — what it received over A2A, its Odoo MCP
+ * calls, `write_notebook`, its status updates and artifacts, as the A2A
+ * stream tells them. Both read one record (`useAgentInspector`), fed by the
+ * team (`useA2ATeam`'s `inspector`) and by the fetch the A2A client sends
+ * with (`inspectA2AFetch`); an A2A message shows in both, sent in one and
+ * received in the other. Right-click a member for its menu: *Inspect the
+ * agent…* opens its inspector over the page.
+ *
+ * Sales' suggestions — its Appspec's starters — are chips in its balloon
+ * while it waits for a question: one clicked is asked, as if typed.
+ *
  * Sales accepts a Jupyter notebook from Accounting besides its words
  * (`acceptedOutputModes`, `NOTEBOOK_AND_WORDS`). When Accounting gives one,
  * Sales' balloon shows it read-only (`NotebookPreview`: no kernel), and it

package/lib/examples/AgentA2ATeamExample.js

@@ -1,4 +1,4 @@
-import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { Button, Flash, Heading, Text, Textarea } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
@@ -10,8 +10,9 @@ import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { useBrowserInference } from '../hooks/useBrowserInference';
 import { readJwtClaims, tokenLifetimeMs, useAnonymousSessionStore, } from '../runtimes/browser/anonymousToken';
 import { connectA2APeer } from '../runtimes/browser/a2aPeer';
-import { A2ATeamGraph, NOTEBOOK_AND_WORDS, teamConnectionsOf, useA2ATeam, } from '../components/teams';
+import { A2ATeamGraph, NOTEBOOK_AND_WORDS, teamConnectionsOf, teamToolClassifier, useA2ATeam, } from '../components/teams';
 import { ACCOUNTING_APP_0_0_1, SALES_APP_0_0_1 } from '../specs/apps';
+import { AgentInspector, classifyToolCall, inspectA2AFetch, useAgentInspector, } from '../components/inspector';
 import { SALES_AND_ACCOUNTING_TEAM_SPEC_0_0_1 } from '../specs/teams/teams';
 const TEAM = SALES_AND_ACCOUNTING_TEAM_SPEC_0_0_1;
 const SALES = SALES_APP_0_0_1;
@@ -45,6 +46,8 @@ function AgentA2ATeam() {
     }, [accountingKey]);
     const [accountingKeyEnded, setAccountingKeyEnded] = useState(() => accountingKeyClock !== undefined &&
         accountingKeyClock.expiresAt <= Date.now());
+    // One record of what both members do, each inspector showing its own.
+    const { sink: inspector } = useAgentInspector();
     const [peer, setPeer] = useState(null);
     const [peerError, setPeerError] = useState(null);
     const [draft, setDraft] = useState('');
@@ -55,14 +58,24 @@ function AgentA2ATeam() {
         let current = true;
         setPeer(null);
         setPeerError(null);
-        connectA2APeer({ url: accountingUrl, key: accountingKey })
+        connectA2APeer({
+            url: accountingUrl,
+            key: accountingKey,
+            // The A2A traffic, recorded: Sales sends, Accounting answers.
+            fetch: inspectA2AFetch(globalThis.fetch.bind(globalThis), {
+                sink: inspector,
+                asker: SALES.name,
+                peer: ACCOUNTING.name,
+                classifyTool: teamToolClassifier(ACCOUNTING_CONNECTIONS, classifyToolCall),
+            }),
+        })
             .then(found => current && setPeer(found))
             .catch(error => current &&
             setPeerError(error instanceof Error ? error.message : String(error)));
         return () => {
             current = false;
         };
-    }, [accountingUrl, accountingKey]);
+    }, [accountingUrl, accountingKey, inspector]);
     // Sales runs here and asks Accounting over A2A: the conversation, the
     // exchange, the report and the way the link carries a message.
     const team = useA2ATeam({
@@ -74,7 +87,13 @@ function AgentA2ATeam() {
         peerConnections: ACCOUNTING_CONNECTIONS,
         // Its words, and a notebook to run here when it gives one.
         accept: NOTEBOOK_AND_WORDS,
+        inspector,
     });
+    // Sales' starters, in its balloon while it waits for a question.
+    const suggestions = useMemo(() => (SALES.interface.starters ?? []).map(starter => ({
+        label: starter.label,
+        prompt: starter.message,
+    })), []);
     const send = (text) => {
         setDraft('');
         void team.send(text);
@@ -82,7 +101,7 @@ function AgentA2ATeam() {
     const accountingWhere = accountingKey
         ? `on a runtime, ${new URL(accountingUrl).host}, with a temporary key`
         : `on a runtime, ${new URL(accountingUrl).host}`;
-    return (_jsxs(Box, { sx: { p: 4, maxWidth: 1080, mx: 'auto' }, children: [_jsxs(Heading, { as: "h2", sx: { fontSize: 4, mb: 1 }, children: [TEAM.emoji, " ", TEAM.name] }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', mt: 0 }, children: TEAM.description }), ((anonymous.status === 'active' && anonymous.expiresAt) ||
+    return (_jsxs(Box, { sx: { p: 4, maxWidth: 1080, mx: 'auto' }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 4, mb: 1 }, children: "Agents A2A Team" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mt: 0 }, children: [TEAM.emoji, " ", _jsx("strong", { children: TEAM.name }), ": ", TEAM.description] }), ((anonymous.status === 'active' && anonymous.expiresAt) ||
                 (accountingKeyClock && !accountingKeyEnded)) && (_jsxs(Box, { sx: { display: 'flex', gap: 4, flexWrap: 'wrap', mb: 3 }, children: [anonymous.status === 'active' && anonymous.expiresAt && (_jsx(AnonymousKeyTimer, { expiresAt: anonymous.expiresAt, grantedMs: anonymous.grantedMs, label: `${SALES.name}'s trial key`, onExpire: () => useAnonymousSessionStore.getState().expire() })), accountingKeyClock && !accountingKeyEnded && (_jsx(AnonymousKeyTimer, { expiresAt: accountingKeyClock.expiresAt, grantedMs: accountingKeyClock.grantedMs, label: `${ACCOUNTING.name}'s temporary key`, onExpire: () => setAccountingKeyEnded(true) }))] })), anonymous.status === 'expired' && (_jsx(Box, { sx: { mb: 3 }, children: _jsx(AnonymousKeyExpired, { agentName: SALES.name, 
                     // Sales runs in this page: what ended is its model's key, and
                     // signing in gives it the person's own.
@@ -104,9 +123,21 @@ function AgentA2ATeam() {
                             : 'on a runtime',
                         persona: team.entryPersona,
                         onToggle: () => composer.current?.focus(),
+                        conversationLabel: `Ask ${SALES.name}`,
                         onAway: team.setEntryAway,
+                        history: team.entryHistory,
                         expandTarget: notebookArea,
                         notebookTitle: `${ACCOUNTING.name}\u2019s notebook`,
+                        suggestions: team.ready && !team.busy ? suggestions : undefined,
+                        onSuggestion: suggestion => send(suggestion.prompt),
+                        inspector,
+                        onStop: team.busy ? team.stop : undefined,
+                        about: {
+                            name: SALES.name,
+                            spec: `${SALES.id}:${SALES.version}`,
+                            model: SALES.model || undefined,
+                            where: 'in your browser',
+                        },
                     }, peer: {
                         id: ACCOUNTING.id,
                         name: ACCOUNTING.name,
@@ -115,8 +146,25 @@ function AgentA2ATeam() {
                         where: accountingWhere,
                         persona: team.peerPersona,
                         onAway: team.setPeerAway,
+                        history: team.peerHistory,
                         connections: ACCOUNTING_CONNECTIONS,
-                    }, flow: team.flow, calls: team.calls, connected: peer !== null, label: peer ? `A2A · ${peer.skill.name}` : 'A2A · not connected' }) }), _jsx(Box, { ref: notebookArea, sx: { mb: team.notebook ? 3 : 0 }, "data-team-notebook-placement": "under-graph" }), _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 => {
+                        inspector,
+                        about: {
+                            name: ACCOUNTING.name,
+                            spec: `${ACCOUNTING.id}:${ACCOUNTING.version}`,
+                            model: ACCOUNTING.model || undefined,
+                            where: accountingWhere,
+                        },
+                    }, flow: team.flow, calls: team.calls, 
+                    // Room for the balloons: suggestions, *more* and a notebook.
+                    balloonRoom: 320, connected: peer !== null, label: peer ? `A2A · ${peer.skill.name}` : 'A2A · not connected' }) }), _jsx(Box, { ref: notebookArea, sx: { mb: team.notebook ? 3 : 0 }, "data-team-notebook-placement": "under-graph" }), _jsx(Box, { sx: {
+                    display: 'grid',
+                    gridTemplateColumns: ['1fr', '1fr', '1fr 1fr'],
+                    gap: 3,
+                    mb: 3,
+                }, "data-team-inspectors": "", children: [SALES, ACCOUNTING].map(member => (_jsxs(Box, { sx: { minWidth: 0 }, "data-team-inspector": member.id, children: [_jsxs(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: [member.emoji, " ", member.name, "\u2019s Agent Inspector"] }), _jsx(AgentInspector, { sink: inspector, agent: member.name, maxHeight: 360, exportName: `agent-inspector-${member.id}`, emptyText: member === SALES
+                                ? 'Its model turns, its call to Accounting and the A2A messages it sends and receives show here.'
+                                : 'What it receives over A2A, its Odoo MCP calls and what it sends back show here.' })] }, member.id))) }), _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] }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', fontSize: 1, mt: 0 }, children: ["Or choose one of ", SALES.name, "\u2019s suggestions in its balloon."] }), _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);
@@ -126,13 +174,13 @@ function AgentA2ATeam() {
                                         mb: 2,
                                         borderRadius: 2,
                                         bg: turn.role === 'user' ? 'accent.subtle' : 'canvas.subtle',
-                                    }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block' }, children: turn.role === 'user' ? 'You' : SALES.name }), _jsx(Streamdown, { children: turn.text })] }, index))) })] }), _jsxs(Box, { sx: { flex: '1 1 360px', minWidth: 0 }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: "The exchange" }), _jsx(Box, { as: "ol", sx: { pl: 3, color: 'fg.muted', fontSize: 1 }, "data-team-exchange": "", children: team.exchange.length === 0 ? (_jsx(Text, { as: "li", children: "Nothing asked yet." })) : (team.exchange.map((step, index) => (_jsx(Text, { as: "li", children: step }, index)))) }), !team.notebook && (_jsxs(_Fragment, { children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mt: 3, mb: 2 }, children: "The report" }), _jsx(Box, { sx: {
-                                            p: 3,
-                                            border: '1px solid',
-                                            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." })) })] }))] })] })] }));
+                                    }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block' }, children: turn.role === 'user' ? 'You' : SALES.name }), _jsx(Streamdown, { children: turn.text })] }, index))) })] }), _jsx(Box, { sx: { flex: '1 1 360px', minWidth: 0 }, children: !team.notebook && (_jsxs(_Fragment, { children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: "The report" }), _jsx(Box, { sx: {
+                                        p: 3,
+                                        border: '1px solid',
+                                        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." })) })] })) })] })] }));
 }
 export function AgentA2ATeamExample() {
     return (_jsx(ThemedProvider, { children: _jsx(AgentA2ATeam, {}) }));

package/lib/examples/AssistantExample.js

@@ -15,6 +15,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * and so are the characters clippy.js publishes, fetched when picked.
  */
 import { useEffect, useRef, useState } from 'react';
+import { useAgentInspector } from '../components/inspector/agentInspector';
 import { buildReactorFromPlugins } from '@datalayer/reactor';
 import { Button, Heading, Text, ToggleSwitch } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
@@ -34,6 +35,35 @@ const SERVER = ((typeof window === 'undefined'
     ? null
     : new URLSearchParams(window.location.search).get('agentRuntimesUrl')) ||
     'http://127.0.0.1:8765').replace(/\/+$/, '');
+/** The agent the assistant talks to on that server. */
+const AGENT_ID = 'assistant';
+/**
+ * Make sure the server has the assistant's agent: `npm run examples` starts
+ * the server with none, so the page creates it from the
+ * `example-agentic-chat` spec the first time, over AG-UI, the spec's own
+ * protocol.
+ */
+async function ensureAssistantAgent() {
+    const found = await fetch(`${SERVER}/api/v1/agents/${AGENT_ID}`);
+    if (found.ok) {
+        return;
+    }
+    if (found.status !== 404) {
+        throw new Error(`The server could not say whether the ${AGENT_ID} agent exists (${found.status}).`);
+    }
+    const created = await fetch(`${SERVER}/api/v1/agents`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            name: AGENT_ID,
+            agent_spec_id: 'example-agentic-chat',
+            transport: 'ag-ui',
+        }),
+    });
+    if (!created.ok && created.status !== 409) {
+        throw new Error(`The server could not create the ${AGENT_ID} agent (${created.status}).`);
+    }
+}
 /** The plugins this page enables: Datalayer's characters and the owl's. */
 const reactor = buildReactorFromPlugins([
     AssistantCharactersPlugin,
@@ -73,8 +103,21 @@ const AssistantExample = () => {
         ? assistantCharacterNamed(reactor, character)
         : character;
     const [loadError, setLoadError] = useState();
+    // The agent on the server, made if it is not there yet.
+    const [agentReady, setAgentReady] = useState(false);
+    const [agentError, setAgentError] = useState();
+    useEffect(() => {
+        let cancelled = false;
+        ensureAssistantAgent().then(() => !cancelled && setAgentReady(true), error => !cancelled &&
+            setAgentError(`${error instanceof Error ? error.message : String(error)} The assistant talks to an agent-runtimes server at ${SERVER}.`));
+        return () => {
+            cancelled = true;
+        };
+    }, []);
     // How the balloon shows the conversation (T-23): history, or current.
     const [balloon, setBalloon] = useState('history');
+    // What the agent does, for the menu's *Inspect the agent…*.
+    const { sink: inspector } = useAgentInspector();
     // Pixel, the test sprite, read once through the clippy.js reader.
     const [pixel, setPixel] = useState();
     useEffect(() => {
@@ -156,8 +199,25 @@ const AssistantExample = () => {
                                         }
                                     } }), 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, 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, 
+                                    !isClippyJs && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), agentError && (_jsx(Box, { sx: { maxWidth: 720, mx: 'auto', mt: 3 }, children: _jsx(Text, { as: "p", role: "alert", sx: { color: 'danger.fg' }, children: agentError }) })), agentReady && (_jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: drawn, balloonDisplay: balloon, protocol: "ag-ui", endpoint: `${SERVER}/api/v1/ag-ui/${AGENT_ID}/`, 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)] }) }));
+                    decisions: { serverUrl: SERVER }, 
+                    // Right-click the character: its menu.
+                    inspector: inspector, onBalloonDisplayChange: setBalloon, onChangeCharacter: () => document
+                        .querySelector('[data-assistant-character]')
+                        ?.focus(), about: {
+                        name: 'Assistant',
+                        spec: AGENT_ID,
+                        where: `on a runtime, ${new URL(SERVER).host}`,
+                    }, suggestions: [
+                        {
+                            title: 'What is on this page?',
+                            message: 'What is on this page?',
+                        },
+                        {
+                            title: 'Tell me a joke',
+                            message: 'Tell me a short joke about accountants.',
+                        },
+                    ] }, typeof character === 'string' ? character : character.sprite))] }) }));
 };
 export default AssistantExample;

package/lib/loop/apps/AppRenderer.js

@@ -209,7 +209,7 @@ export function appDatalayerCreatePayload(app, instance) {
         transport: 'ag-ui',
         agent_spec_id: agentIdOf(app),
         app_spec: dumpAppspec(app),
-        // Code Mode calls every tool through `execute_code`, which an
+        // Codemode calls every tool through `execute_code`, which an
         // application without a shell is refused: its tools are called
         // one by one instead, each decided by its rules.
         enable_codemode: Boolean(app.permissions?.computer?.shell),

package/lib/loop/core/index.d.ts

@@ -531,6 +531,23 @@ export type AssistantCharacterContribution = {
     character: AssistantCharacter | AssistantCharacterData;
 };
 export declare const LoopAssistantCharacter: import("@datalayer/reactor").ContributionPoint<AssistantCharacterContribution>;
+/**
+ * An entry of the floating assistant's own menu (right-click, Shift+F10, a
+ * long press): a plugin's, beside what the assistant offers itself. Its
+ * `group` is the heading it is listed under; `checked` makes it one of a
+ * choice.
+ */
+export type AssistantMenuContribution = {
+    /** Stable id, for the registry and the graph. */
+    id: string;
+    label: string;
+    description?: string;
+    onSelect: () => void;
+    checked?: boolean;
+    disabled?: boolean;
+    group?: string;
+};
+export declare const LoopAssistantMenu: import("@datalayer/reactor").ContributionPoint<AssistantMenuContribution>;
 export { LoopCanvasBlock, type CanvasBlockContribution } from './canvasBlocks';
 /**
  * The per-example chat extras a host feeds the loop's conversation live.

package/lib/loop/core/index.js

@@ -142,6 +142,7 @@ export const LoopChatHeader = defineContributionPoint('loop.chat.header');
 export const LoopAgentBlueprint = defineContributionPoint('loop.agent.blueprint');
 export const LoopChatSuggestion = defineContributionPoint('loop.chat.suggestion');
 export const LoopAssistantCharacter = defineContributionPoint('loop.assistant.character');
+export const LoopAssistantMenu = defineContributionPoint('loop.assistant.menu');
 // A block the Canvas may place (LOOP C-12), in a module of its own so that
 // the palette is read without the rest of the contracts.
 export { LoopCanvasBlock } from './canvasBlocks';

package/lib/loop/plugins/assistant/index.d.ts

@@ -68,6 +68,6 @@ export declare function assistantStateOfTurn(turn: ChatTurnSnapshot, presence: P
     arriving?: boolean;
     leaving?: boolean;
 }): AssistantState;
-export declare function LoopAssistant({ app, person, appId, decisions, balloon: display, }: LoopAssistantConfig): JSX.Element | null;
+export declare function LoopAssistant({ app, person, appId, decisions, balloon: displayGiven, }: LoopAssistantConfig): JSX.Element | null;
 export declare const LoopAssistantPlugin: import("@datalayer/reactor").ReactorPlugin<LoopAssistantConfig, unknown, unknown>;
 export default LoopAssistantPlugin;

package/lib/loop/plugins/assistant/index.js

@@ -13,7 +13,7 @@ import { ASSISTANT_WORDS, assistantStateOf, keepAway, keptAway, latestSaying, }
 import { useApproveToolRequest, useRejectToolRequest, useToolApprovalsQuery, } from '../../../hooks/useToolApprovals';
 import { approvalsOfApp, ruleOfApproval } from '../app-rules/AppRulesCard';
 import { useViewportDrag } from '../../../chat/useViewportDrag';
-import { LoopAssistantCharacter, LoopChatLayout, LoopChatTurn, LoopSlots, } from '../../core';
+import { LoopAssistantCharacter, LoopAssistantMenu, LoopChatLayout, LoopChatTurn, LoopSlots, } from '../../core';
 import { assistantCharacterFor } from '../assistant-characters';
 export const LOOP_ASSISTANT_PLUGIN_NAME = '@datalayer/loop-plugin-assistant';
 /** The character's size, in pixels, as the chat's own assistant. */
@@ -69,9 +69,14 @@ function focusComposer() {
     const composer = document.querySelector('[data-chat-composer] textarea, [data-chat-composer] [contenteditable="true"]');
     composer?.focus();
 }
-export function LoopAssistant({ app, person, appId, decisions, balloon: display = 'history', }) {
+export function LoopAssistant({ app, person, appId, decisions, balloon: displayGiven = 'history', }) {
+    // The balloon's display, as its menu chose it; the Appspec's until then.
+    const [chosenDisplay, setChosenDisplay] = useState();
+    const display = chosenDisplay ?? displayGiven;
     const contributed = useContributions(LoopAssistantCharacter).map(entry => entry.value);
     const chosen = assistantCharacterFor(contributed, { app, person });
+    // What the enabled plugins add to its menu.
+    const menuContributions = useContributions(LoopAssistantMenu).map(entry => entry.value);
     const turnEntries = useContributions(LoopChatTurn);
     const turn = useSignalValue(turnEntries[0]?.value.turn ?? NO_TURN);
     const presence = useSignalValue(turnEntries[0]?.value.presence ?? NO_PRESENCE);
@@ -199,7 +204,7 @@ export function LoopAssistant({ app, person, appId, decisions, balloon: display
     };
     return (_jsxs(_Fragment, { children: [appId && signedIn ? (_jsx(WaitingApprovals, { appId: appId, onWaiting: setApproval })) : null, _jsx(AssistantStage, { character: chosen.character, state: state, size: SIZE, place: drag.position
                     ? { left: `${drag.position.left}px`, top: `${drag.position.top}px` }
-                    : { right: '24px', bottom: '24px' }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: open, onToggle: onToggle, balloon: balloon, balloonDisplay: display, insist: insist, onDismiss: onDismiss, decide: decide })] }));
+                    : { right: '24px', bottom: '24px' }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: open, onToggle: onToggle, balloon: balloon, balloonDisplay: display, insist: insist, onDismiss: onDismiss, decide: decide, onResetPosition: drag.position ? drag.reset : undefined, onBalloonDisplayChange: setChosenDisplay, about: appId ? { name: appId, spec: appId } : undefined, contextMenu: menuContributions })] }));
 }
 export const LoopAssistantPlugin = definePlugin({
     name: LOOP_ASSISTANT_PLUGIN_NAME,