@datalayer/agent-runtimes 1.3.74 → 1.3.78

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,56 @@ 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 message = {
+            id: `peer-${told.current}`,
+            role,
+            content: text,
+            createdAt: new Date(),
+        };
+        setPeerHistory(prev => [...prev, message]);
+    }, []);
+    // A tool the peer calls, as the chat holds one: added when it starts,
+    // updated when it ends.
+    const toolCalled = useCallback((step) => {
+        const id = step.id ?? step.name;
+        const call = {
+            id: `peer-tool:${id}`,
+            type: 'tool-call',
+            toolCallId: id,
+            toolName: toolOwnName(step.name, peerConnections),
+            args: {},
+            status: step.error ? 'error' : step.ended ? 'complete' : 'executing',
+            ...(step.error ? { error: step.error } : {}),
+        };
+        setPeerHistory(prev => prev.some(item => item.id === call.id)
+            ? prev.map(item => (item.id === call.id ? call : item))
+            : [...prev, call]);
+    }, [peerConnections]);
     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 +145,25 @@ 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) {
+                toolCalled(event.tool);
             }
             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 +173,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 +184,7 @@ export function useA2ATeam(options) {
                 ...prev,
                 state: 'speaking',
                 saying: balloonLine(event.answer),
+                full: event.answer,
                 insist: true,
                 tool: undefined,
             }));
@@ -160,19 +194,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, toolCalled]);
     const agent = useMemo(() => {
         if (!peer) {
             return null;
@@ -198,7 +230,6 @@ export function useA2ATeam(options) {
         setBusy(true);
         setReport(null);
         setArtifacts([]);
-        setExchange([]);
         setTurns(prev => [...prev, { role: 'user', text: asked }]);
         setEntryPersona({
             ...AT_REST,
@@ -210,6 +241,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 +262,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 +289,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 +311,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 +339,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 +365,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 +381,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 +390,20 @@ 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,
+        content: turn.text,
+        createdAt: new Date(0),
+    })), [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,22 @@ 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',
+                            description: SALES.description || undefined,
+                        },
                     }, peer: {
                         id: ACCOUNTING.id,
                         name: ACCOUNTING.name,
@@ -115,8 +147,30 @@ 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,
+                            // What its A2A card says, once it is reached.
+                            description: peer?.card.description || ACCOUNTING.description || undefined,
+                            skills: peer?.card.skills.map(skill => skill.name),
+                            protocol: peer ? 'a2a' : undefined,
+                            url: peer ? accountingUrl : undefined,
+                        },
+                    }, 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 +180,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';
@@ -24,7 +25,7 @@ import { AssistantCharactersPlugin, assistantCharacterNamed, assistantCharacters
 import { OwlCharacterPlugin } from './utils/owlCharacterPlugin';
 import { readTestSpriteCharacter } from './utils/testSpriteCharacter';
 import { CLIPPY_JS_CHARACTERS, CLIPPY_JS_VERSION, readClippyJsCharacter, } from './utils/clippyJsCharacters';
-import { readAcsCharacter, readClippyCharacter, } from '../chat/assistant/formats';
+import { CHARACTER_FILES_ACCEPT, readCharacterFiles, } from '../chat/assistant/formats';
 /**
  * The agent-runtimes server the assistant talks to: `?agentRuntimesUrl=`
  * when given, else this machine's on port 8765. It serves the `assistant`
@@ -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,
@@ -45,27 +75,6 @@ const CATALOGUE = assistantCharactersOf(reactor).map(entry => ({
     id: entry.id,
     name: entry.character.name,
 }));
-/**
- * A character file a person picked, read in the page (T-26): one `.acs`, or
- * a clippy.js character's `agent.js` and `map.png` (and its sounds file).
- */
-async function readPicked(files) {
-    const acs = files.find(file => file.name.toLowerCase().endsWith('.acs'));
-    if (acs) {
-        return readAcsCharacter(await acs.arrayBuffer());
-    }
-    const agentJs = files.find(file => file.name.toLowerCase() === 'agent.js');
-    const mapPng = files.find(file => /\.(png|gif|webp|jpe?g)$/i.test(file.name));
-    const soundsJs = files.find(file => /^sounds-.*\.js$/i.test(file.name));
-    if (!agentJs || !mapPng) {
-        throw new Error('Pick one .acs file, or a clippy.js character: its agent.js and its map image (and a sounds file if you have one).');
-    }
-    return readClippyCharacter({
-        agentJs: await agentJs.text(),
-        mapPng,
-        soundsJs: soundsJs ? await soundsJs.text() : undefined,
-    });
-}
 const AssistantExample = () => {
     const [character, setCharacter] = useState('paperclip');
     // A character chosen by id is the one its plugin contributes.
@@ -73,8 +82,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(() => {
@@ -142,13 +164,13 @@ const AssistantExample = () => {
                                             onClick: () => setBalloon(balloon === 'history' ? 'current' : 'history') }), _jsx(Text, { "aria-live": "polite", "data-toggle-state": "", sx: { color: 'fg.muted' }, children: balloon === 'history' ? 'History' : 'Current' })] })] }), _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) => {
+                                    }) })] }), _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: CHARACTER_FILES_ACCEPT, "aria-label": "Character files", onChange: async (event) => {
                                         const files = Array.from(event.target.files ?? []);
                                         if (!files.length) {
                                             return;
                                         }
                                         try {
-                                            setCharacter(await readPicked(files));
+                                            setCharacter(await readCharacterFiles(files));
                                             setLoadError(undefined);
                                         }
                                         catch (error) {
@@ -156,8 +178,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/examples/AssistantGalleryExample.js

@@ -163,7 +163,8 @@ const AssistantGalleryExample = () => {
                     {
                         id: 'notebook',
                         role: 'assistant',
-                        text: SAMPLE_NOTEBOOK_SAYING,
+                        content: SAMPLE_NOTEBOOK_SAYING,
+                        createdAt: new Date(0),
                     },
                 ]
                 : []),