@datalayer/agent-runtimes 1.3.74 → 1.3.75

package/lib/chat/base/ChatBase.js

@@ -58,6 +58,8 @@ const EphemeralDocument = React.lazy(() => import('../document/EphemeralDocument
     default: m.EphemeralDocument,
 })));
 import { useNotebookTools } from '../../tools/adapters/agent-runtimes/notebookHooks';
+import { useAgentInspectorSink } from '../../components/inspector/agentInspector';
+import { chatInspectorRecorder, } from '../../components/inspector/chatInspect';
 // Tracks pending prompts already auto-sent for a given conversation scope.
 // This prevents layout-driven unmount/remount cycles from re-sending prompts.
 const sentPendingPromptKeys = new Set();
@@ -513,7 +515,7 @@ useStore: useStoreMode = true, protocol: protocolRaw, onSendMessage, onSendReady
 // Extended props
 brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderToolResult, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, welcome, trailingContent, voice, voiceSpeaking = false, onStopSpeaking, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, onItemsChange, onDisplayItemsChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, 
 // Tool invocation hooks
-onToolCallStart, onToolCallComplete, 
+onToolCallStart, onToolCallComplete, inspector: inspectorGiven, 
 // Identity/Authorization props
 onAuthorizationRequired: _onAuthorizationRequired, connectedIdentities, 
 // Conversation persistence
@@ -1589,6 +1591,25 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     onToolCallStartRef.current = onToolCallStart;
     const onToolCallCompleteRef = useRef(onToolCallComplete);
     onToolCallCompleteRef.current = onToolCallComplete;
+    // The Agent Inspector: the turns and tool calls, recorded as they happen.
+    const inspectorFromContext = useAgentInspectorSink();
+    const inspectorSink = inspectorGiven ?? inspectorFromContext;
+    const inspectorActorRef = useRef('Agent');
+    inspectorActorRef.current =
+        (typeof title === 'string' && title) || activeAgentId || 'Agent';
+    const recorderRef = useRef(null);
+    if (inspectorSink && recorderRef.current?.sink !== inspectorSink) {
+        recorderRef.current = {
+            sink: inspectorSink,
+            recorder: chatInspectorRecorder(inspectorSink, () => inspectorActorRef.current, {
+                frontendTools: () => (frontendToolsRef.current ?? []).map(tool => tool.name),
+            }),
+        };
+    }
+    else if (!inspectorSink) {
+        recorderRef.current = null;
+    }
+    const inspectAnswerRef = useRef('');
     const handleRespondRef = useRef(null);
     // A decision made outside the chat — a host page's own approval banner —
     // is answered exactly as the tool card's buttons answer it: through the
@@ -2415,6 +2436,9 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                             const sanitizedContent = typeof rawContent === 'string'
                                 ? sanitizeAssistantContent(rawContent)
                                 : (rawContent ?? '');
+                            if (typeof sanitizedContent === 'string' && sanitizedContent) {
+                                inspectAnswerRef.current = sanitizedContent;
+                            }
                             setDisplayItems(prev => {
                                 const newItems = [...prev];
                                 const idx = newItems.findIndex(item => !isToolCallMessage(item) && item.id === currentId);
@@ -2520,6 +2544,11 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                                 toolCallId,
                                 args,
                             });
+                            recorderRef.current?.recorder.toolStarted({
+                                id: toolCallId,
+                                name: toolName,
+                                args,
+                            });
                             const frontendTool = frontendToolsRef.current?.find(t => t.name === toolName);
                             const toolHandler = frontendTool?.handler;
                             // Execute when the args are complete. The protocol says so
@@ -2604,6 +2633,13 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                                 setDisplayItems(prev => prev.map(item => isToolCallMessage(item) && item.toolCallId === toolCallId
                                     ? updatedToolCall
                                     : item));
+                                recorderRef.current?.recorder.toolEnded(toolCallId, {
+                                    result: event.toolResult.result,
+                                    error: event.toolResult.error ??
+                                        (updatedToolCall.status === 'error'
+                                            ? (executionError ?? 'failed')
+                                            : undefined),
+                                });
                                 // Fire post-hook for tool results
                                 onToolCallCompleteRef.current?.({
                                     toolName: existingToolCall.toolName,
@@ -2657,6 +2693,11 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                      * The bar and its ring simply never appeared for a browser agent.
                      */
                     {
+                        recorderRef.current?.recorder.turnEnded({
+                            text: inspectAnswerRef.current || undefined,
+                            usage: event.usage,
+                        });
+                        inspectAnswerRef.current = '';
                         const turnInput = event.usage?.promptTokens ?? 0;
                         const turnOutput = event.usage?.completionTokens ?? 0;
                         // The parts sum to the total when the harness did not send one:
@@ -2710,6 +2751,9 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                     break;
                 case 'error':
                     console.error('[ChatBase] Protocol error:', event.error);
+                    recorderRef.current?.recorder.turnEnded({
+                        error: event.error?.message ?? 'error',
+                    });
                     if (event.error?.message &&
                         /exceeded maximum retries/i.test(event.error.message) &&
                         hideMessagesAfterToolUIRef.current) {
@@ -2777,6 +2821,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                     result,
                     status: 'complete',
                 };
+                recorderRef.current?.recorder.toolEnded(toolCallId, { result });
                 toolCallsRef.current.set(toolCallId, completedToolCall);
                 setDisplayItems(prev => prev.map(item => isToolCallMessage(item) && item.toolCallId === toolCallId
                     ? completedToolCall
@@ -2789,6 +2834,9 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                     status: 'error',
                     error: err.message,
                 };
+                recorderRef.current?.recorder.toolEnded(toolCallId, {
+                    error: err.message,
+                });
                 toolCallsRef.current.set(toolCallId, errorToolCall);
                 setDisplayItems(prev => prev.map(item => isToolCallMessage(item) && item.toolCallId === toolCallId
                     ? errorToolCall
@@ -2838,6 +2886,8 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         if (!adapterRef.current && !onSendMessage)
             return;
         stoppedRef.current = false;
+        inspectAnswerRef.current = '';
+        recorderRef.current?.recorder.turnStarted(messageContent, selectedModel || undefined);
         suppressAssistantTextForToolOnlyRef.current =
             isToolCallOnlyPrompt(messageContent);
         // Said, then sent: by the microphone at once, or from the composer it

package/lib/chat/indicators/TypingDots.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Three pulsing dots: a speaker is still at work and has not written yet —
+ * the chat's waiting indicator, and the assistant's balloon's. Still, but
+ * shown, for a reader who asks for reduced motion. Hidden from a screen
+ * reader: the live region beside it says the state.
+ *
+ * @module chat/indicators/TypingDots
+ */
+import type { ReactElement } from 'react';
+export declare function TypingDots({ size }: {
+    size?: number;
+}): ReactElement;
+export default TypingDots;

package/lib/chat/indicators/TypingDots.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from '@datalayer/primer-addons';
+export function TypingDots({ size = 8 }) {
+    return (_jsx(Box, { "aria-hidden": "true", "data-typing-dots": "", sx: { display: 'inline-flex', alignItems: 'center', gap: '4px' }, children: [0, 0.2, 0.4].map((delay, index) => (_jsx(Box, { sx: {
+                width: size,
+                height: size,
+                borderRadius: '50%',
+                bg: 'fg.muted',
+                animation: 'typingPulse 1.4s ease-in-out infinite',
+                animationDelay: `${delay}s`,
+                '@keyframes typingPulse': {
+                    '0%, 60%, 100%': { transform: 'scale(0.6)', opacity: 0.4 },
+                    '30%': { transform: 'scale(1)', opacity: 1 },
+                },
+                '@media (prefers-reduced-motion: reduce)': {
+                    animation: 'none',
+                    opacity: 0.7,
+                },
+            } }, index))) }));
+}
+export default TypingDots;

package/lib/chat/messages/ChatMessageList.js

@@ -18,6 +18,7 @@ import { Streamdown } from 'streamdown';
 import { streamdownMarkdownStyles, streamdownCodeBlockStyles, } from '../styles/streamdownStyles';
 import { ToolCallDisplay } from '../tools/ToolCallDisplay';
 import { marksOfToolCall, skillIdOfCall } from '../marks';
+import { TypingDots } from '../indicators/TypingDots';
 import { TurnFooter } from './TurnFooter';
 import { normalizeAssistantMarkdown } from './assistantMarkdown';
 import { parseFormSubmission } from './formSubmission';
@@ -62,21 +63,6 @@ function toneColorsOf(tone) {
         fg: `${tone}.fg`,
     };
 }
-/** Three pulsing dots: a speaker is still writing and has not settled yet. */
-function TypingDots({ size = 8 }) {
-    return (_jsx(Box, { sx: { display: 'flex', alignItems: 'center', gap: '4px' }, children: [0, 0.2, 0.4].map((delay, index) => (_jsx(Box, { sx: {
-                width: size,
-                height: size,
-                borderRadius: '50%',
-                bg: 'fg.muted',
-                animation: 'typingPulse 1.4s ease-in-out infinite',
-                animationDelay: `${delay}s`,
-                '@keyframes typingPulse': {
-                    '0%, 60%, 100%': { transform: 'scale(0.6)', opacity: 0.4 },
-                    '30%': { transform: 'scale(1)', opacity: 1 },
-                },
-            } }, index))) }));
-}
 const SUBAGENT_AVATAR_CONFIG = {
     userAvatar: _jsx(PersonIcon, { size: 14 }),
     assistantAvatar: _jsx(DependabotIcon, { size: 14 }),

package/lib/components/inspector/AgentInspector.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The Agent Inspector: what agents do, one row a thing, newest last — the
+ * time (to the millisecond, and since the first), who did it and toward
+ * whom, its source and kind, its name with its mark, its status and
+ * duration, and a line that says it. A row unfolds to its payload as a JSON
+ * tree (a call's arguments and its result), and to what was made of it.
+ *
+ * Filters by source, kind and actor; *Pause* holds the rows still while the
+ * record goes on, *Clear* empties it, *Export* saves the session as JSON. A
+ * large payload (a notebook) says its size and stays folded until asked.
+ *
+ * Fed by a sink (`useAgentInspector`) or given its entries.
+ *
+ * @module components/inspector/AgentInspector
+ */
+import type { JSX } from 'react';
+import { type AgentInspectorEntry, type AgentInspectorExport, type AgentInspectorSink, type AgentInspectorSource } from './agentInspector';
+export type AgentInspectorProps = {
+    /** The record to show, kept current. */
+    sink?: AgentInspectorSink | null;
+    /** Or its entries, as given. */
+    entries?: readonly AgentInspectorEntry[];
+    /** How tall the rows grow before they scroll. */
+    maxHeight?: number | string;
+    /** Payloads larger than this, in bytes, stay folded until asked. */
+    largeBytes?: number;
+    /** What is said while nothing is recorded. */
+    emptyText?: string;
+    /** The file name the session is exported as, without `.json`. */
+    exportName?: string;
+    /**
+     * One agent's own record: what it did (`actor`), and the A2A messages it
+     * sent or received — one message shows in the sender's and in the
+     * receiver's, the same entry, as sent in one and received in the other.
+     */
+    agent?: string;
+};
+/** Whether an entry is one agent's: done by it, or sent to or by it. */
+export declare function isAgentsEntry(entry: AgentInspectorEntry, agent: string): boolean;
+/** Which way an entry went, from one agent's side: `→ Accounting`, `← Accounting`. */
+export declare function directionFrom(entry: AgentInspectorEntry, agent: string | undefined): string;
+/** A time of day, to the millisecond: `15:44:31.299`. */
+export declare function clockTime(at: number): string;
+/** Time since the first entry: `+1.204s`. */
+export declare function sinceFirst(at: number, first: number): string;
+/** How long a call took: `412 ms`, `3.4 s`. */
+export declare function durationText(ms: number): string;
+export type AgentInspectorFilter = {
+    sources: ReadonlySet<AgentInspectorSource>;
+    kinds: ReadonlySet<string>;
+    actors: ReadonlySet<string>;
+};
+/** The entries a filter keeps: an empty set keeps every value. */
+export declare function filterEntries(entries: readonly AgentInspectorEntry[], filter: AgentInspectorFilter): AgentInspectorEntry[];
+/** A session, as JSON. */
+export declare function exportEntries(entries: readonly AgentInspectorEntry[]): AgentInspectorExport;
+/** The Agent Inspector. */
+export declare function AgentInspector({ sink, entries: given, maxHeight, largeBytes, emptyText, exportName, agent, }: AgentInspectorProps): JSX.Element;
+export default AgentInspector;

package/lib/components/inspector/AgentInspector.js

@@ -0,0 +1,220 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo, useState } from 'react';
+import { ActionList, ActionMenu, Button, Label, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { DownloadIcon, PlayIcon, TrashIcon, PauseIcon, } from '@primer/octicons-react';
+import { SpecMark } from '../../chat/marks';
+import { AGENT_INSPECTOR_SOURCES, AGENT_INSPECTOR_SOURCE_LABELS, formatBytes, useAgentInspectorEntries, } from './agentInspector';
+import { JsonTree } from './JsonTree';
+/** Whether an entry is one agent's: done by it, or sent to or by it. */
+export function isAgentsEntry(entry, agent) {
+    return (entry.actor === agent ||
+        entry.direction?.from === agent ||
+        entry.direction?.to === agent);
+}
+/** Which way an entry went, from one agent's side: `→ Accounting`, `← Accounting`. */
+export function directionFrom(entry, agent) {
+    const direction = entry.direction;
+    if (!direction) {
+        return entry.actor;
+    }
+    if (agent === direction.from) {
+        return `sent → ${direction.to}`;
+    }
+    if (agent === direction.to) {
+        return `received ← ${direction.from}`;
+    }
+    return `${direction.from} → ${direction.to}`;
+}
+/** A kind, as its label is coloured. */
+const KIND_VARIANTS = {
+    request: 'accent',
+    'status-update': 'attention',
+    'artifact-update': 'success',
+    task: 'secondary',
+    message: 'done',
+    'agent-card': 'secondary',
+    response: 'secondary',
+    'tool-call': 'sponsors',
+    turn: 'primary',
+    error: 'danger',
+    approval: 'severe',
+};
+const pad = (value, length = 2) => String(value).padStart(length, '0');
+/** A time of day, to the millisecond: `15:44:31.299`. */
+export function clockTime(at) {
+    const date = new Date(at);
+    return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+}
+/** Time since the first entry: `+1.204s`. */
+export function sinceFirst(at, first) {
+    return `+${((at - first) / 1000).toFixed(3)}s`;
+}
+/** How long a call took: `412 ms`, `3.4 s`. */
+export function durationText(ms) {
+    return ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(1)} s`;
+}
+/** The entries a filter keeps: an empty set keeps every value. */
+export function filterEntries(entries, filter) {
+    return entries.filter(entry => (!filter.sources.size || filter.sources.has(entry.source)) &&
+        (!filter.kinds.size || filter.kinds.has(entry.kind)) &&
+        (!filter.actors.size || filter.actors.has(entry.actor)));
+}
+/** A session, as JSON. */
+export function exportEntries(entries) {
+    return { exportedAt: new Date().toISOString(), entries: [...entries] };
+}
+function toggle(set, value) {
+    const next = new Set(set);
+    if (next.has(value)) {
+        next.delete(value);
+    }
+    else {
+        next.add(value);
+    }
+    return next;
+}
+function FilterMenu({ label, options, selected, onToggle, onAll, name, }) {
+    return (_jsxs(ActionMenu, { children: [_jsxs(ActionMenu.Button, { size: "small", "data-inspector-filter": label.toLowerCase(), children: [label, selected.size ? ` · ${selected.size}` : ''] }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsxs(ActionList, { selectionVariant: "multiple", "aria-label": label, children: [_jsx(ActionList.Item, { selected: !selected.size, onSelect: onAll, children: "All" }), _jsx(ActionList.Divider, {}), options.map(option => (_jsx(ActionList.Item, { selected: selected.has(option), onSelect: () => onToggle(option), children: name(option) }, option)))] }) })] }));
+}
+function Payload({ title, value, large, }) {
+    const bytes = useMemo(() => {
+        try {
+            return new TextEncoder().encode(JSON.stringify(value) ?? '').length;
+        }
+        catch {
+            return 0;
+        }
+    }, [value]);
+    const [shown, setShown] = useState(bytes <= large);
+    return (_jsxs(Box, { sx: { minWidth: 0 }, "data-inspector-payload": title, children: [_jsxs(Text, { sx: {
+                    fontSize: 0,
+                    color: 'fg.muted',
+                    fontWeight: 600,
+                    display: 'block',
+                }, children: [title, " \u00B7 ", formatBytes(bytes)] }), shown ? (_jsx(JsonTree, { value: value, expandDepth: bytes > large ? 1 : 2 })) : (_jsxs(Button, { size: "small", onClick: () => setShown(true), "data-inspector-large": "", children: ["Show ", formatBytes(bytes)] }))] }));
+}
+function Row({ entry, first, open, onToggle, large, agent, }) {
+    const ended = entry.endedAt !== undefined;
+    return (_jsxs(Box, { as: "li", "data-inspector-entry": entry.id, "data-inspector-source": entry.source, "data-inspector-kind": entry.kind, "data-inspector-status": entry.status ?? '', sx: {
+            borderBottom: '1px solid',
+            borderColor: 'border.muted',
+            listStyle: 'none',
+        }, children: [_jsxs(Box, { as: "button", type: "button", "aria-expanded": open, onClick: onToggle, sx: {
+                    width: '100%',
+                    display: 'grid',
+                    gridTemplateColumns: ['auto 1fr', 'auto auto auto minmax(0, 1fr)'],
+                    columnGap: 2,
+                    rowGap: 1,
+                    alignItems: 'center',
+                    px: 2,
+                    py: 1,
+                    border: 0,
+                    bg: open ? 'canvas.subtle' : 'transparent',
+                    color: 'fg.default',
+                    font: 'inherit',
+                    fontSize: 0,
+                    textAlign: 'left',
+                    cursor: 'pointer',
+                    '&:hover': { bg: 'canvas.subtle' },
+                }, children: [_jsxs(Box, { sx: { fontFamily: 'mono', color: 'fg.muted', whiteSpace: 'nowrap' }, children: [_jsx("span", { title: new Date(entry.at).toISOString(), children: clockTime(entry.at) }), ' ', _jsx(Text, { sx: { opacity: 0.7 }, children: sinceFirst(entry.at, first) })] }), _jsx(Text, { sx: { whiteSpace: 'nowrap', fontWeight: 600 }, "data-inspector-direction": "", children: directionFrom(entry, agent) }), _jsxs(Box, { sx: { display: 'flex', gap: 1, flexWrap: 'wrap' }, children: [_jsx(Label, { size: "small", variant: "secondary", children: AGENT_INSPECTOR_SOURCE_LABELS[entry.source] }), _jsx(Label, { size: "small", variant: KIND_VARIANTS[entry.kind] ?? 'secondary', children: entry.kind })] }), _jsxs(Box, { sx: { display: 'flex', gap: 1, alignItems: 'center', minWidth: 0 }, children: [(entry.icon || entry.emoji) && (_jsx(SpecMark, { icon: entry.icon, emoji: entry.emoji, size: 14 })), entry.name && entry.kind !== 'request' && (_jsx(Text, { sx: { fontFamily: 'mono', fontWeight: 600, whiteSpace: 'nowrap' }, children: entry.name })), entry.status && (_jsxs(Label, { size: "small", variant: entry.status === 'failed'
+                                    ? 'danger'
+                                    : entry.status === 'running'
+                                        ? 'attention'
+                                        : 'success', children: [entry.status, ended && entry.endedAt !== undefined
+                                        ? ` · ${durationText(entry.endedAt - entry.at)}`
+                                        : ''] })), _jsx(Text, { sx: {
+                                    color: 'fg.muted',
+                                    overflow: 'hidden',
+                                    textOverflow: 'ellipsis',
+                                    whiteSpace: 'nowrap',
+                                    minWidth: 0,
+                                }, title: entry.summary, children: entry.summary }), entry.bytes > large && (_jsx(Text, { sx: { color: 'fg.muted', whiteSpace: 'nowrap' }, children: formatBytes(entry.bytes) }))] })] }), open && (_jsxs(Box, { "data-inspector-details": "", sx: {
+                    px: 3,
+                    py: 2,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: 2,
+                    bg: 'canvas.subtle',
+                }, children: [entry.a2a && (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', fontFamily: 'mono' }, children: [
+                            entry.a2a.method && `method ${entry.a2a.method}`,
+                            entry.a2a.rpcId !== undefined && `id ${entry.a2a.rpcId}`,
+                            entry.a2a.taskId && `task ${entry.a2a.taskId}`,
+                            entry.a2a.contextId && `context ${entry.a2a.contextId}`,
+                            entry.a2a.state && entry.a2a.state,
+                            entry.a2a.chunks &&
+                                entry.a2a.chunks > 1 &&
+                                `${entry.a2a.chunks} chunks`,
+                        ]
+                            .filter(Boolean)
+                            .join(' · ') })), entry.error && (_jsx(Text, { sx: { color: 'danger.fg', fontSize: 0 }, children: entry.error })), entry.payload !== undefined && (_jsx(Payload, { title: entry.kind === 'tool-call' ? 'Arguments' : 'Payload', value: entry.payload, large: large })), entry.result !== undefined && (_jsx(Payload, { title: "Result", value: entry.result, large: large })), entry.events.length > 0 && (_jsx(Payload, { title: "Events", value: entry.events, large: large })), entry.links.length > 0 && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["Linked: ", entry.links.join(', ')] }))] }))] }));
+}
+/** Save a session as a JSON file. */
+function download(name, session) {
+    const blob = new Blob([JSON.stringify(session, null, 2)], {
+        type: 'application/json',
+    });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = `${name}.json`;
+    link.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+/** The Agent Inspector. */
+export function AgentInspector({ sink, entries: given, maxHeight = 420, largeBytes = 16_000, emptyText = 'Nothing recorded yet.', exportName = 'agent-inspector', agent, }) {
+    const live = useAgentInspectorEntries(sink);
+    const everything = given ?? live;
+    const all = useMemo(() => agent
+        ? everything.filter(entry => isAgentsEntry(entry, agent))
+        : everything, [everything, agent]);
+    const [held, setHeld] = useState(null);
+    const [clearedAt, setClearedAt] = useState(0);
+    const [sources, setSources] = useState(new Set());
+    const [kinds, setKinds] = useState(new Set());
+    const [actors, setActors] = useState(new Set());
+    const [open, setOpen] = useState(new Set());
+    const recorded = useMemo(() => (clearedAt ? all.filter(entry => entry.at >= clearedAt) : all), [all, clearedAt]);
+    const shown = held ?? recorded;
+    const waiting = held ? recorded.length - held.length : 0;
+    const kindOptions = useMemo(() => [...new Set(recorded.map(entry => entry.kind))].sort(), [recorded]);
+    const actorOptions = useMemo(() => [...new Set(recorded.map(entry => entry.actor))].sort(), [recorded]);
+    const sourceOptions = useMemo(() => AGENT_INSPECTOR_SOURCES.filter(source => recorded.some(entry => entry.source === source)), [recorded]);
+    const rows = useMemo(() => filterEntries(shown, { sources, kinds, actors }), [shown, sources, kinds, actors]);
+    const first = shown[0]?.at ?? 0;
+    return (_jsxs(Box, { "data-agent-inspector": "", sx: {
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            bg: 'canvas.default',
+            color: 'fg.default',
+            minWidth: 0,
+        }, children: [_jsxs(Box, { role: "toolbar", "aria-label": agent ? `${agent}'s Agent Inspector` : 'Agent Inspector', sx: {
+                    display: 'flex',
+                    flexWrap: 'wrap',
+                    gap: 2,
+                    alignItems: 'center',
+                    p: 2,
+                    borderBottom: '1px solid',
+                    borderColor: 'border.default',
+                }, children: [_jsx(FilterMenu, { label: "Source", options: sourceOptions, selected: sources, onToggle: value => setSources(toggle(sources, value)), onAll: () => setSources(new Set()), name: value => AGENT_INSPECTOR_SOURCE_LABELS[value] }), _jsx(FilterMenu, { label: "Kind", options: kindOptions, selected: kinds, onToggle: value => setKinds(toggle(kinds, value)), onAll: () => setKinds(new Set()), name: value => value }), _jsx(FilterMenu, { label: "Actor", options: actorOptions, selected: actors, onToggle: value => setActors(toggle(actors, value)), onAll: () => setActors(new Set()), name: value => value }), _jsx(Box, { sx: { flex: 1 } }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, "data-inspector-count": "", children: [rows.length === shown.length
+                                ? `${rows.length} ${rows.length === 1 ? 'entry' : 'entries'}`
+                                : `${rows.length} of ${shown.length}`, waiting > 0 ? ` · ${waiting} new` : ''] }), _jsx(Button, { size: "small", leadingVisual: held ? PlayIcon : PauseIcon, "aria-pressed": held !== null, onClick: () => setHeld(held ? null : recorded), "data-inspector-pause": "", children: held ? 'Resume' : 'Pause' }), _jsx(Button, { size: "small", leadingVisual: TrashIcon, onClick: () => {
+                            setOpen(new Set());
+                            setHeld(null);
+                            // One agent's view of a shared record clears only itself.
+                            if (sink && !given && !agent) {
+                                sink.clear();
+                            }
+                            else {
+                                setClearedAt(Date.now());
+                            }
+                        }, "data-inspector-clear": "", children: "Clear" }), _jsx(Button, { size: "small", leadingVisual: DownloadIcon, disabled: !recorded.length, onClick: () => download(exportName, exportEntries(recorded)), "data-inspector-export": "", children: "Export" })] }), _jsx(Box, { as: "ol", "aria-label": "Recorded", sx: { m: 0, p: 0, maxHeight, overflowY: 'auto' }, children: rows.length === 0 ? (_jsx(Text, { as: "li", sx: {
+                        display: 'block',
+                        p: 3,
+                        color: 'fg.muted',
+                        fontSize: 1,
+                        listStyle: 'none',
+                    }, children: emptyText })) : (rows.map(entry => (_jsx(Row, { entry: entry, first: first, large: largeBytes, agent: agent, open: open.has(entry.id), onToggle: () => setOpen(toggle(open, entry.id)) }, entry.id)))) })] }));
+}
+export default AgentInspector;

package/lib/components/inspector/AgentInspectorDialog.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Agent Inspector over the page: a large dialog, the inspector loaded
+ * only when it opens, fed by the sink the agent's chat or team feeds. Esc
+ * closes it.
+ *
+ * @module components/inspector/AgentInspectorDialog
+ */
+import type { JSX } from 'react';
+import type { AgentInspectorSink } from './agentInspector';
+export type AgentInspectorDialogProps = {
+    sink: AgentInspectorSink | null;
+    /** The dialog's title. */
+    title?: string;
+    /** One agent's own record (`AgentInspector`'s `agent`); all of it without. */
+    agent?: string;
+    onClose: () => void;
+};
+export declare function AgentInspectorDialog({ sink, title, agent, onClose, }: AgentInspectorDialogProps): JSX.Element;
+export default AgentInspectorDialog;

package/lib/components/inspector/AgentInspectorDialog.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense, lazy } from 'react';
+import { Dialog } from '@primer/react';
+import { Text } from '@primer/react';
+const AgentInspector = lazy(() => import('./AgentInspector'));
+export function AgentInspectorDialog({ sink, title = 'Agent Inspector', agent, onClose, }) {
+    return (_jsx(Dialog, { title: title, onClose: onClose, width: "xlarge", height: "large", "data-agent-inspector-dialog": "", children: _jsx(Suspense, { fallback: _jsx(Text, { sx: { color: 'fg.muted' }, children: "Loading the Agent Inspector\u2026" }), children: _jsx(AgentInspector, { sink: sink, agent: agent, maxHeight: "calc(80vh - 140px)", emptyText: "Nothing recorded yet: what the agent does shows here as it does it." }) }) }));
+}
+export default AgentInspectorDialog;

package/lib/components/inspector/JsonTree.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A JSON value as a tree: objects and arrays fold and unfold, each value
+ * coloured by its type (theme colours, light and dark), long strings cut
+ * until asked for whole, and the whole value copied as JSON.
+ *
+ * @module components/inspector/JsonTree
+ */
+import type { JSX } from 'react';
+export type JsonTreeProps = {
+    value: unknown;
+    /** The root's name, shown as its key. */
+    name?: string;
+    /** How many levels open at first. */
+    expandDepth?: number;
+    /** Offer *Copy JSON* above the tree. */
+    copyable?: boolean;
+    /** Longer strings are cut until clicked. */
+    stringLimit?: number;
+};
+/** A value's type, as the tree colours it. */
+export declare function jsonType(value: unknown): 'string' | 'number' | 'boolean' | 'null' | 'array' | 'object' | 'undefined';
+/** A JSON value, as a tree. */
+export declare function JsonTree({ value, name, expandDepth, copyable, stringLimit, }: JsonTreeProps): JSX.Element;
+export default JsonTree;

package/lib/components/inspector/JsonTree.js

@@ -0,0 +1,89 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Button, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { CopyIcon, CheckIcon } from '@primer/octicons-react';
+const MONO = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace';
+/** A value's type, as the tree colours it. */
+export function jsonType(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    const type = typeof value;
+    if (type === 'string' || type === 'number' || type === 'boolean') {
+        return type;
+    }
+    if (type === 'bigint') {
+        return 'number';
+    }
+    return type === 'undefined' ? 'undefined' : 'object';
+}
+const COLOURS = {
+    string: 'success.fg',
+    number: 'accent.fg',
+    boolean: 'done.fg',
+    null: 'fg.muted',
+    undefined: 'fg.muted',
+};
+function Leaf({ value, stringLimit, }) {
+    const type = jsonType(value);
+    const [whole, setWhole] = useState(false);
+    if (type === 'string') {
+        const text = value;
+        const cut = !whole && text.length > stringLimit;
+        return (_jsxs(Text, { "data-json-type": "string", sx: {
+                color: COLOURS.string,
+                whiteSpace: 'pre-wrap',
+                wordBreak: 'break-word',
+            }, children: [JSON.stringify(cut ? text.slice(0, stringLimit) : text), cut && (_jsxs(Box, { as: "button", type: "button", onClick: () => setWhole(true), sx: {
+                        ml: 1,
+                        p: 0,
+                        border: 0,
+                        bg: 'transparent',
+                        color: 'accent.fg',
+                        cursor: 'pointer',
+                        font: 'inherit',
+                    }, children: ["\u2026 ", text.length - stringLimit, " more"] }))] }));
+    }
+    return (_jsx(Text, { "data-json-type": type, sx: { color: COLOURS[type] ?? 'fg.default' }, children: type === 'undefined' ? 'undefined' : String(value) }));
+}
+function Node({ name, value, depth, expandDepth, stringLimit, }) {
+    const type = jsonType(value);
+    const branch = type === 'array' || type === 'object';
+    const [open, setOpen] = useState(depth < expandDepth);
+    const key = name !== undefined ? (_jsxs(Text, { sx: { color: 'fg.default', fontWeight: 600 }, children: [name, ": "] })) : null;
+    if (!branch) {
+        return (_jsxs(Box, { role: "treeitem", "data-json-node": "", sx: { pl: 3 }, children: [key, _jsx(Leaf, { value: value, stringLimit: stringLimit })] }));
+    }
+    const items = type === 'array'
+        ? value.map((item, index) => [String(index), item])
+        : Object.entries(value);
+    const [openMark, closeMark] = type === 'array' ? ['[', ']'] : ['{', '}'];
+    return (_jsxs(Box, { role: "treeitem", "aria-expanded": open, "data-json-node": "", sx: { pl: depth ? 3 : 0 }, children: [_jsxs(Box, { as: "button", type: "button", onClick: () => setOpen(!open), "aria-label": `${open ? 'Fold' : 'Unfold'} ${name ?? 'the value'}`, "data-json-toggle": "", sx: {
+                    p: 0,
+                    border: 0,
+                    bg: 'transparent',
+                    color: 'inherit',
+                    font: 'inherit',
+                    cursor: 'pointer',
+                    textAlign: 'left',
+                }, children: [_jsx(Text, { sx: { color: 'fg.muted', display: 'inline-block', width: '1em' }, children: open ? '▾' : '▸' }), key, _jsx(Text, { sx: { color: 'fg.muted' }, children: open
+                            ? openMark
+                            : `${openMark} ${items.length} ${type === 'array' ? (items.length === 1 ? 'item' : 'items') : items.length === 1 ? 'key' : 'keys'} ${closeMark}` })] }), open && (_jsxs(Box, { role: "group", children: [items.map(([itemName, item]) => (_jsx(Node, { name: itemName, value: item, depth: depth + 1, expandDepth: expandDepth, stringLimit: stringLimit }, itemName))), _jsx(Text, { sx: { color: 'fg.muted', pl: 3 }, children: closeMark })] }))] }));
+}
+/** A JSON value, as a tree. */
+export function JsonTree({ value, name, expandDepth = 1, copyable = true, stringLimit = 240, }) {
+    const [copied, setCopied] = useState(false);
+    const copy = () => {
+        const text = JSON.stringify(value, null, 2) ?? 'undefined';
+        void navigator.clipboard?.writeText(text).then(() => {
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1500);
+        }, () => undefined);
+    };
+    return (_jsxs(Box, { "data-json-tree": "", sx: { fontFamily: MONO, fontSize: 0, lineHeight: 1.6, minWidth: 0 }, children: [copyable && (_jsx(Button, { size: "small", variant: "invisible", leadingVisual: copied ? CheckIcon : CopyIcon, onClick: copy, "data-json-copy": "", sx: { float: 'right' }, children: copied ? 'Copied' : 'Copy JSON' })), _jsx(Box, { role: "tree", "aria-label": name ?? 'JSON', children: _jsx(Node, { name: name, value: value, depth: 0, expandDepth: expandDepth, stringLimit: stringLimit }) })] }));
+}
+export default JsonTree;